Intake
POST /v1/redemptions takes {"redemption": ..., "signature": "0x..."}: the redemption that preparation returned, unchanged, and the user’s signature of its typed data. It checks them at one block and answers with one code for the first check it fails, with 422 unless noted, in this order:
- The body:
INVALID_BODY, for the form of every field, the signature’s included, withdetails.field. - The operator:
OPERATOR_MISMATCH, a409whosedetails.expectedis the redemption operator. - The route and assets:
UNSUPPORTED_ROUTEfor a route other than6or7, withdetails.fieldredemption.inputs[0].routeId, andUNSUPPORTED_ASSETfor an asset ID or delegate ID other than the accepted one, whosedetailsgive thefieldand theexpectedID. - The deadline of a payload that is not already stored:
DEADLINE_TOO_SOON, whosedetailsgiveminimumDeadlineandminimumLifetimeSeconds. - The signature:
INVALID_SIGNATURE, including a contract wallet that rejects it. - The nonce:
NONCE_MISMATCH, whosedetailsgivesignedNonceandcurrentNonce. - The quote:
NO_QUOTEwhen the signed amounts cannot be quoted or the quote does not honor the signed exact amount, as when the depositor’s credits fall short of an exact-output redemption, andBOUND_NOT_METwhen an exact-output quote’s $TSY input is above the signed maximum (fieldmaxAmountIn, the signedboundand thequoted$TSY, both in whole $TSY, andlegIndex0). - The depositor:
INSUFFICIENT_CREDITS,INSUFFICIENT_BALANCE, andINSUFFICIENT_ALLOWANCE, each with the $TSYtokenandrequiredandavailablein whole $TSY, and for the allowance the Treasury delegate asspender. - Liquidity:
INSUFFICIENT_LIQUIDITY, with the USDCtokenandrequiredandavailablein whole USDC.
INSUFFICIENT_LIQUIDITY’s details.required is the quoted USDC output plus, for exact $TSY in, an execution reserve of 1 basis point of that output. details.available is the most USDC Multiliquid can pay out now, the same figure as preparation’s checks.liquidity.available, and intake decides as checks.liquidity.sufficient does. Prepare and sign a smaller redemption, keeping required within available, or try again later. The error message names no amount.
201. A 201 means the redemption could settle at intake, not that it will: the depositor can still move $TSY or revoke the allowance, and Multiliquid checks again before settling.
States
A redemption’sstate is coarse and moves only forward on its own:
processing moves to completed, failed, or underReview, and underReview to completed or failed. Only you can return a failed redemption to processing, by resubmitting its signed payload while failure.resubmittable is true.
Multiliquid settles each redemption in one atomic transaction, so the receiver is paid in full or not at all. settlement.transactionId is that transaction once the redemption is completed.
Failure codes
A failed redemption’sfailure.code is one of the following. “While the deadline is open” means more than ten minutes before the signed deadline, and resubmittable is false once settlement has started.
Idempotency and resubmission
The signed payload is the idempotency key: two posts of the same signed fields are the same redemption.201stores a new redemption, withreplayed: false.200withreplayed: truereturns the existing redemption of the same signed payload unchanged, so a post whose response was lost is safe to repeat. Concurrent identical posts resolve to one redemption.200withreplayed: falserestarts a failed redemption whosefailure.resubmittablewastrue. Posting the same signed payload again passes the same intake checks. The cause is fixed first, such as by approving more $TSY; no new signature is needed. A restart can still be rejected, for example withNONCE_MISMATCHwhen another transaction has since used the nonce.- Posting a payload whose failure is not resubmittable returns the failed redemption unchanged with
replayed: true. - A different signed payload for the same depositor and nonce replaces an earlier redemption that has not started settlement, which fails with
SUPERSEDED. Once settlement has started, the post is rejected with409and codeNONCE_IN_USE, whosedetails.redemptionId, when known, names the redemption holding the nonce. Track that redemption instead of signing again.
429 with code RATE_LIMITED and Retry-After, stores nothing, and is safe to repeat after the wait.
Tracking a redemption
PollGET /v1/redemptions/{redemptionId}:
- every 5 seconds while
stateisprocessing; - about once a minute while it is
underReview; - after a
429, no sooner thanRetry-After, doubling the interval after each one; - and stop at
completedorfailed.
Listing redemptions
GET /v1/redemptions selects redemptions in one of two ways:
An API key needs the
read scope for the organization’s list, and a key without it receives 403 with code INSUFFICIENT_SCOPE. A lookup by user or redemptionId needs no scope.
Every list takes state, createdAfter (inclusive, RFC 3339), createdBefore (exclusive), limit from 1 to 100, defaulting to 50, and cursor, and continues with nextCursor and the same filters. A cursor works only with the filters it was issued for, and for an organization’s list only with that organization’s credential; another limit is fine. Any other cursor, or an unknown query parameter, is a 400 with code INVALID_REQUEST and details.field. Only an organization’s list takes the receiver filter.
Organization redemptions
A credentialedPOST /v1/redemptions records the credential’s organization on a new redemption; a replay or resubmission keeps the organization recorded at creation. Polling GET /v1/redemptions?state=processing and GET /v1/redemptions?state=underReview with the organization’s credential, following each nextCursor, then follows every open redemption it submitted.
receiver appears in a redemption only for a credential of the organization that submitted it that holds the read scope, as every account session does: in that organization’s list, and in GET /v1/redemptions/{redemptionId} and POST /v1/redemptions responses to those credentials. An API key without read is not rejected by those two routes; their responses omit receiver.
The redemption record
Every time is RFC 3339 in UTC with whole seconds. A field that has no value yet is present and
null: statusDetail, completedAt, failedAt, settlement, failure, deadlineAt for a deadline after the year 9999, and a settlement’s blockNumber when the block was not recorded. A field that does not apply to the response is absent: replayed outside POST responses, receiver for a caller other than a read credential of the submitting organization, and the amount that swapType does not make exact.
A settlement’s transactionId is the settlement transaction’s hash and its blockNumber a decimal string. Its inputToken, outputToken, amountIn, and amountOut report what changed hands, the amounts in whole tokens.
Responses also carry older fields that published SDK versions read, such as requestId, which repeats redemptionId, status, an older state name rather than the HTTP status, and executionTxHash. Their amounts, such as signedTsyBound and actualUsdcOut, stay in base units. The interactive reference marks each one deprecated and names its replacement.