> ## Documentation Index
> Fetch the complete documentation index at: https://docs.multiliquid.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle

> What intake checks, how a redemption settles or fails, and how to resubmit and list redemptions.

## Intake

`POST /v1/redemptions` takes `{"redemption": ..., "signature": "0x..."}`: the `redemption` that [preparation](https://docs.multiliquid.xyz/api-reference/treasury/prepare-and-sign.md) 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.

```json theme={null}
{
  "error": "not enough USDC is available to settle this redemption now; redeem a smaller amount or retry later",
  "status": 422,
  "code": "INSUFFICIENT_LIQUIDITY",
  "details": {
    "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "required": "1000.1",
    "available": "750"
  },
  "requestId": "req_019a5c1e8f3b7c2d9e4f6a1b2c3d4e5f"
}
```

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:

| `state` | Meaning | Final | Fields |
| - | - | - | - |
| `processing` | Accepted and being settled | No | `statusDetail` notes a delay, such as a step being retried or a depositor shortfall Multiliquid waits on |
| `completed` | Settled: the \$TSY was redeemed and the USDC paid to the receiver | Yes | `completedAt` and `settlement`: `transactionId`, `blockNumber`, `settledAt`, `inputToken`, `outputToken`, and `amountIn` and `amountOut` in whole tokens |
| `failed` | Stopped without settling | Yes, unless you resubmit it | `failedAt` and `failure`: `code`, `message`, and `resubmittable` |
| `underReview` | The settlement transaction's outcome is unknown | No | `statusDetail`. Multiliquid resolves it to `completed` or `failed`. Don't sign a new redemption for the same nonce in the meantime. |

`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.

| `failure.code` | Meaning | `resubmittable` |
| - | - | - |
| `INSUFFICIENT_BALANCE`, `INSUFFICIENT_ALLOWANCE` | The depositor's \$TSY balance, or \$TSY allowance to the Treasury delegate, fell below the \$TSY the redemption needed | `true` while the deadline is open: the depositor restores it, and you resubmit |
| `INSUFFICIENT_CREDITS` | The depositor's Treasury credits fell below the \$TSY the redemption needed | `true` while the deadline is open. Prepare and sign a smaller redemption. |
| `INSUFFICIENT_LIQUIDITY` | Not enough USDC was available to settle it | `true` while the deadline is open |
| `BOUND_NOT_MET` | The quote moved outside the signed bounds | `true` while the deadline is open |
| `RETRIES_EXHAUSTED` | A temporary problem persisted until Multiliquid stopped retrying | `true` while the deadline is open |
| `INVALID_SIGNATURE` | The signature no longer authorizes the depositor, as when a contract wallet stops accepting it | `true` while the deadline is open |
| `PROCESSING_FAILED` | Any other reason | `true` while the deadline is open |
| `SUPERSEDED` | A newer signature for the same nonce replaced it | `true` while the deadline is open: posting it again replaces the newer one in turn, unless that one has started settlement. Once that one settles, the code becomes `NONCE_CONSUMED`. |
| `DEADLINE_EXPIRED` | The signed deadline passed before settlement | `false`: the depositor signs a new redemption |
| `NONCE_CONSUMED` | Another transaction used the signed nonce. When a redemption settles, the same depositor's failed redemptions with the same or a lower nonce that never started settlement and whose deadline has not passed take this code. | `false`: the depositor signs a new redemption with the current nonce |
| `SETTLEMENT_NOT_EXECUTED` | Review found that the settlement transaction did not execute | `false` |
| `SETTLEMENT_UNVERIFIED` | The settlement transaction executed but could not be verified | `false`: contact support with the redemption ID |

## 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:

| Query | Who | Returns |
| - | - | - |
| `user` or `redemptionId` | Anyone, with or without a credential | Summaries: `redemptionId`, `network`, `state`, `user`, `createdAt`, `updatedAt`, `completedAt`, and `failedAt` |
| Neither, with a credential | The credential's organization | The organization's redemptions in full, newest first, as `GET /v1/redemptions/{redemptionId}` returns them |

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

| Field | Description |
| - | - |
| `redemptionId` | The redemption's UUID |
| `network` | `evm-mainnet` |
| `state` | See [States](#states) |
| `statusDetail` | A note on a delay, while `processing` or `underReview`; `null` when there is nothing to report |
| `replayed` | On `POST` responses only: `true` for a replay, `false` for a creation or restart |
| `user` | The depositor that signed the redemption, in lowercase hex |
| `receiver` | The address that receives the USDC, for the submitting organization's credentials with the `read` scope only |
| `swapType` | Which amount the redemption signs exactly: `exactIn` or `exactOut` |
| `inputToken`, `outputToken` | \$TSY and USDC, as token objects |
| `amountIn` or `amountOut` | The exact amount, in whole tokens: `amountIn` for `exactIn`, `amountOut` for `exactOut`. The other one is absent. A \$TSY amount can show all 18 decimal places. |
| `bound` | The signed bound on the other amount, in whole tokens: `minAmountOut` for `exactIn`, `maxAmountIn` for `exactOut` |
| `nonce` | The signed swap nonce. A later redemption signed for the same nonce replaces this one if it arrives before settlement starts. |
| `deadlineAt` | The signed deadline, in RFC 3339; `null` for a deadline after 9999-12-31T23:59:59Z |
| `settlement`, `completedAt` | For a completed redemption; `null` otherwise |
| `failure`, `failedAt` | For a failed redemption; `null` otherwise |
| `createdAt`, `updatedAt` | When the redemption was stored and last changed |

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](https://api.multiliquid.xyz/scalar) marks each one deprecated and names its replacement.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.