Skip to main content

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:
  1. The body: INVALID_BODY, for the form of every field, the signature’s included, with details.field.
  2. The operator: OPERATOR_MISMATCH, a 409 whose details.expected is the redemption operator.
  3. The route and assets: UNSUPPORTED_ROUTE for a route other than 6 or 7, with details.field redemption.inputs[0].routeId, and UNSUPPORTED_ASSET for an asset ID or delegate ID other than the accepted one, whose details give the field and the expected ID.
  4. The deadline of a payload that is not already stored: DEADLINE_TOO_SOON, whose details give minimumDeadline and minimumLifetimeSeconds.
  5. The signature: INVALID_SIGNATURE, including a contract wallet that rejects it.
  6. The nonce: NONCE_MISMATCH, whose details give signedNonce and currentNonce.
  7. The quote: NO_QUOTE when 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, and BOUND_NOT_MET when an exact-output quote’s $TSY input is above the signed maximum (field maxAmountIn, the signed bound and the quoted $TSY, both in whole $TSY, and legIndex 0).
  8. The depositor: INSUFFICIENT_CREDITS, INSUFFICIENT_BALANCE, and INSUFFICIENT_ALLOWANCE, each with the $TSY token and required and available in whole $TSY, and for the allowance the Treasury delegate as spender.
  9. Liquidity: INSUFFICIENT_LIQUIDITY, with the USDC token and required and available in whole USDC.
For an exact-input redemption, the quote before interest accrues understates the USDC output, so the signed minimum USDC is enforced at settlement, after accrual. 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.
A rejected payload is never stored. An accepted redemption returns 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’s state 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’s failure.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.
  • 201 stores a new redemption, with replayed: false.
  • 200 with replayed: true returns 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.
  • 200 with replayed: false restarts a failed redemption whose failure.resubmittable was true. 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 with NONCE_MISMATCH when 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 with 409 and code NONCE_IN_USE, whose details.redemptionId, when known, names the redemption holding the nonce. Track that redemption instead of signing again.
There is no cancellation route: an unsettled redemption is withdrawn only by letting its deadline pass, or replaced by a new signature for the same nonce before settlement starts. One redemption is validated at a time. A post that arrives while another is being validated receives 429 with code RATE_LIMITED and Retry-After, stores nothing, and is safe to repeat after the wait.

Tracking a redemption

Poll GET /v1/redemptions/{redemptionId}:
  • every 5 seconds while state is processing;
  • about once a minute while it is underReview;
  • after a 429, no sooner than Retry-After, doubling the interval after each one;
  • and stop at completed or failed.
Settlement waits for the settlement transaction to become final, and there is no guaranteed completion time.

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 credentialed POST /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.