Burn self-serve test-mode funds off a programme float
/v1/simulated-withdrawalsRequires an API client bearer token.
Self-serve TEST-MODE programme defunding: burns test money off the named programme's float via the ledger's issuance path. Exactly one of `amount` or `drain: true` (drain requires `currency` — it reads the float's current available balance and burns exactly that, deliberately non-atomic against a racing top-up). Live-mode funding stays operator-only — this route is 403 in live mode regardless of caller role. Requires an Idempotency-Key header.
Parameters
Header parameters
| Name | Required | Description |
|---|---|---|
| Idempotency-Key | required | Client-chosen. An identical retry with the same key returns the stored response; reusing the key with a different payload returns 409. |
Request body
+ show properties− hide properties
Example
curl -X POST https://api.rigid.fi/v1/simulated-withdrawals \
-H "Authorization: Bearer $RIGID_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"program_id": "uuid"
}'Responses
200Result of the withdrawal.
+ show properties− hide properties
+ show properties− hide properties
400Validation error — including float_insufficient (posted-basis: the float cannot cover this burn), no_float (never minted into), nothing_to_drain (drain against a zero/absent balance), or a missing/blank Idempotency-Key header
401Authentication required
403Live mode, or caller is not a programme admin for this programme
409Idempotency-Key reused with a different payload, or the ledger module is definitely not enabled
500Internal server error
503This programme's module configuration has not been received yet (code `config_cold`) — retry