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

# Prepare and sign

> Prepare a redemption, read its checks, and sign its typed data.

`POST /v1/redemptions/prepare` returns everything a redemption needs before the depositor signs: the `redemption` to send back, the `typedData` to sign, the \$TSY `approval` to land first, the `checks` intake applies, and the `quote`. It stores nothing and reserves no liquidity, and `POST /v1/redemptions` checks everything again at intake.

## Preparation

| Field | Required | Description |
| - | - | - |
| `user` | Yes | The address that signs and redeems |
| `receiver` | No | The address that receives the USDC; defaults to `user` |
| `amountIn` | One of the two | The exact \$TSY to redeem, in whole tokens: a nonzero decimal string with at most 6 decimal places, such as `"995.21"` |
| `amountOut` | One of the two | The exact USDC to receive, in whole tokens, in the same form, such as `"1000"` |
| `slippageBps` | No | The tolerance applied to the quote to set the signed bound, from 0 to 5,000 basis points; default 50 |
| `deadline` | No | The signature's deadline in Unix seconds, more than ten minutes away and no later than `253402300799` (9999-12-31T23:59:59Z); defaults to one hour from now |
| `network` | No | `evm-mainnet`, the default |

```bash theme={null}
curl -X POST "https://api.multiliquid.xyz/v1/redemptions/prepare" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "0x1111111111111111111111111111111111111111",
    "amountOut": "1000",
    "slippageBps": 50
  }'
```

The example depositor, `0x1111…1111`, holds 2,000 \$TSY and 2,000 \$TSY of Treasury credits, and has not yet approved the Treasury delegate. Only `checks.allowance` fails, and `approval` covers it. The `redemption` and `typedData` are what the depositor signs, so they keep base units: `assetInAmt` `1000186050000000000000` is 1,000.18605 \$TSY, which has 18 decimals, and `assetOutAmt` `1000000000` is 1,000 USDC, which has 6. `checks` and `quote` are in whole tokens.

```json Response expandable theme={null}
{
  "redemption": {
    "network": "evm-mainnet",
    "user": "0x1111111111111111111111111111111111111111",
    "operator": "0x13D923C6E01DE19CF2E134Da3300F09aC42221f2",
    "receiver": "0x1111111111111111111111111111111111111111",
    "inputs": [
      {
        "routeId": "7",
        "assetInId": "0x780a0ed07e618523cabd294ee648537f4d185a074f97ecd50188d7f394e1e927",
        "assetOutId": "0x58e27f2731863499e6a23a1662ebeed9041d6b40996ea9ca7f4ebc54201823b4",
        "stablecoinDelegateId": "0x780a0ed07e618523cabd294ee648537f4d185a074f97ecd50188d7f394e1e927",
        "assetInAmt": "1000186050000000000000",
        "assetOutAmt": "1000000000"
      }
    ],
    "nonce": "3",
    "deadline": "1796140800"
  },
  "typedData": {
    "types": {
      "EIP712Domain": [
        {
          "name": "name",
          "type": "string"
        },
        {
          "name": "version",
          "type": "string"
        },
        {
          "name": "chainId",
          "type": "uint256"
        },
        {
          "name": "verifyingContract",
          "type": "address"
        }
      ],
      "SwapBatchApproval": [
        {
          "name": "user",
          "type": "address"
        },
        {
          "name": "operator",
          "type": "address"
        },
        {
          "name": "receiver",
          "type": "address"
        },
        {
          "name": "inputs",
          "type": "SwapInput[]"
        },
        {
          "name": "nonce",
          "type": "uint256"
        },
        {
          "name": "deadline",
          "type": "uint256"
        }
      ],
      "SwapInput": [
        {
          "name": "routeId",
          "type": "uint256"
        },
        {
          "name": "assetInID",
          "type": "bytes32"
        },
        {
          "name": "assetOutID",
          "type": "bytes32"
        },
        {
          "name": "stablecoinDelegateID",
          "type": "bytes32"
        },
        {
          "name": "assetInAmt",
          "type": "uint256"
        },
        {
          "name": "assetOutAmt",
          "type": "uint256"
        }
      ]
    },
    "primaryType": "SwapBatchApproval",
    "domain": {
      "name": "MultiliquidSwap",
      "version": "2",
      "chainId": 1,
      "verifyingContract": "0xD66211cf522Ba23B59789ffF6524c1f03E13E20c"
    },
    "message": {
      "user": "0x1111111111111111111111111111111111111111",
      "operator": "0x13D923C6E01DE19CF2E134Da3300F09aC42221f2",
      "receiver": "0x1111111111111111111111111111111111111111",
      "inputs": [
        {
          "routeId": "7",
          "assetInID": "0x780a0ed07e618523cabd294ee648537f4d185a074f97ecd50188d7f394e1e927",
          "assetOutID": "0x58e27f2731863499e6a23a1662ebeed9041d6b40996ea9ca7f4ebc54201823b4",
          "stablecoinDelegateID": "0x780a0ed07e618523cabd294ee648537f4d185a074f97ecd50188d7f394e1e927",
          "assetInAmt": "1000186050000000000000",
          "assetOutAmt": "1000000000"
        }
      ],
      "nonce": "3",
      "deadline": "1796140800"
    }
  },
  "approval": {
    "description": "Approve 1000.18605 TSY to the Treasury delegate of capital provider Uniform Labs",
    "transaction": {
      "runtime": "evm",
      "chainId": 1,
      "from": "0x1111111111111111111111111111111111111111",
      "to": "0x6f4e688a151dfa05b20cb3151e6066d9fd5d7b32",
      "data": "0x095ea7b30000000000000000000000001f2c73a2578b3d49843c9a40f473ef6768f6d6a3000000000000000000000000000000000000000000000036385ea9431f162000",
      "value": "0",
      "nonce": "9",
      "gas": "60000",
      "maxFeePerGas": "21500000000",
      "maxPriorityFeePerGas": "1500000000",
      "serialized": "0x02f86d01098459682f008505017ff70082ea60946f4e688a151dfa05b20cb3151e6066d9fd5d7b3280b844095ea7b30000000000000000000000001f2c73a2578b3d49843c9a40f473ef6768f6d6a3000000000000000000000000000000000000000000000036385ea9431f162000c0"
    }
  },
  "checks": {
    "credits": {
      "token": "0x6f4e688a151dfa05b20cb3151e6066d9fd5d7b32",
      "required": "1000.18605",
      "available": "2000",
      "sufficient": true
    },
    "balance": {
      "token": "0x6f4e688a151dfa05b20cb3151e6066d9fd5d7b32",
      "required": "1000.18605",
      "available": "2000",
      "sufficient": true
    },
    "allowance": {
      "token": "0x6f4e688a151dfa05b20cb3151e6066d9fd5d7b32",
      "spender": "0x1f2c73a2578b3d49843c9a40f473ef6768f6d6a3",
      "required": "1000.18605",
      "available": "0",
      "sufficient": false
    },
    "liquidity": {
      "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "required": "1000",
      "available": "250000",
      "sufficient": true
    }
  },
  "quote": {
    "amountIn": "995.21",
    "amountOut": "1000"
  },
  "expiresAt": "2026-12-01T15:50:00Z"
}
```

The bound applies `slippageBps` to the quote: for exact \$TSY in, the minimum USDC is the quote's USDC output less `slippageBps`, rounded down and at least 0.000001 USDC; for exact USDC out, the maximum \$TSY is the quote's \$TSY input plus `slippageBps`, rounded up.

| Response field | Description |
| - | - |
| `redemption` | The redemption to send back with the signature, unchanged: the values of `typedData.message`, with the input's IDs named `assetInId`, `assetOutId`, and `stablecoinDelegateId`, and the signed amounts `assetInAmt` and `assetOutAmt` in base units |
| `typedData` | `domain`, `types`, `primaryType`, and `message`, ready to sign |
| `approval` | The \$TSY approval to the Treasury delegate, for the most \$TSY the redemption can spend: a `description` and the unsigned `transaction`, like a [swap build's](https://docs.multiliquid.xyz/api-reference/swap/quote-and-build.md#transactions-on-evm). `null` when the allowance already covers it. Submit it alone to [`POST /v1/submissions`](https://docs.multiliquid.xyz/api-reference/swap/submissions), or send it from a wallet that can only broadcast, and wait until it is confirmed before you submit the redemption. |
| `checks` | What intake checks, read at the quote's block; see [Checks](#checks) |
| `quote` | The quote the bound was derived from: `amountIn` (\$TSY) and `amountOut` (USDC), in whole tokens, for the full amount at the depositor's own rate, even when the credits fall short. An exact-input redemption's interest accrual before settlement can raise its USDC output. |
| `expiresAt` | Ten minutes before the deadline. Intake accepts the signed redemption only before this time. |

A preparation answers `200` whatever its checks say, including for a wallet with too few Treasury credits or none, as [Too few credits](#too-few-credits) shows. It answers `422` with:

* `INVALID_BODY` for an unknown or invalid field, such as an invalid or zero address, a `user` that is the redemption operator, a `slippageBps` above 5,000, or a deadline after the year 9999; for a body that names neither or both of `amountIn` and `amountOut`; for a zero amount, a JSON number, or a string that is not a decimal with at most 6 decimal places; or for an amount too small to redeem, such as `amountIn is too small to redeem: its quote rounds to zero`. `details.field` names the field.
* `DEADLINE_TOO_SOON` for a deadline ten minutes away or less.
* `NO_QUOTE` when the Treasury capital provider's quote reverts for a reason other than the depositor's credits. `details.providers` names the capital provider and the decoded `error`, and the message reads as a swap quote's:

```json theme={null}
{
  "error": "no capital provider can quote this swap: 0x780a0ed07e618523cabd294ee648537f4d185a074f97ecd50188d7f394e1e927: the contract is paused (EnforcedPause)",
  "status": 422,
  "code": "NO_QUOTE",
  "details": {
    "providers": [
      {
        "capitalProvider": {
          "id": "0x780a0ed07e618523cabd294ee648537f4d185a074f97ecd50188d7f394e1e927",
          "name": "Uniform Labs",
          "address": "0x1f2c73a2578b3d49843c9a40f473ef6768f6d6a3"
        },
        "error": {
          "name": "EnforcedPause",
          "message": "the contract is paused"
        }
      }
    ]
  },
  "requestId": "req_019a5c1e8f3b7c2d9e4f6a1b2c3d4e5f"
}
```

### Checks

A failing check never fails the preparation; it tells you what intake would reject now. Each check has `token`, `required` and `available` in whole tokens of it, and `sufficient`. `credits`, `balance`, and `allowance` are in \$TSY, and `liquidity` in USDC:

| Check | Description |
| - | - |
| `credits` | The depositor's Treasury credits against the most \$TSY the redemption can spend. Instant redemptions need the same credits. |
| `balance` | The depositor's balance of `token`, the \$TSY address, against the same amount |
| `allowance` | The depositor's allowance of `token` to `spender`, the Treasury delegate, against the same amount. `approval` covers a shortfall. |
| `liquidity` | `required` is the quoted USDC output plus, for exact \$TSY in, an execution reserve of 1 basis point of it, and `available` is the most USDC Multiliquid can pay out now. `sufficient` is intake's own decision for this redemption, so rely on it rather than comparing the two. |

### Too few credits

Preparation still answers `200` when the depositor's Treasury credits fall short of the redemption, or are zero. `checks.credits` fails, and `quote`, the signed bound, and `checks.liquidity.required` still cover the whole amount at the depositor's own rate. A wallet without credits is priced as a wallet with no accrued yield would be. For a wallet with no credits and no \$TSY, the request above quotes about 999.92 \$TSY, signs a maximum of about 1,004.92 \$TSY, and fails `checks.credits` and `checks.balance` with an `available` of `0`.

Intake rejects the redemption until the credits cover it: with `INSUFFICIENT_CREDITS` when its quote prices the signed amounts, and otherwise with `NO_QUOTE`, as for exact USDC out or a wallet without credits.

## What the depositor signs

The authorization is a Multiliquid swap permit: the `SwapBatchApproval` EIP-712 message for the `MultiliquidSwap` contract, with exactly one leg from \$TSY to USDC. A redemption names its amounts as a swap does: `inputToken` is \$TSY, `outputToken` is USDC, and `swapType` says which amount is exact. A response carries the exact amount and the signed bound on the other one:

| `swapType` | Route | `assetInAmt` | `assetOutAmt` | In responses |
| - | - | - | - | - |
| `exactIn` | `6` | The exact \$TSY to redeem | The minimum USDC to receive | `amountIn` and `bound.minAmountOut` |
| `exactOut` | `7` | The maximum \$TSY to spend | The exact USDC to receive | `amountOut` and `bound.maxAmountIn` |

* The operator is the redemption operator, which preparation fills in. A permit that names any other operator is rejected with `409` and code `OPERATOR_MISMATCH`, whose `details.expected` is the redemption operator.
* The nonce is the depositor's current swap nonce, which preparation fills in.
* The deadline must be more than ten minutes in the future when the request arrives; otherwise the request is rejected with `DEADLINE_TOO_SOON`.

## Signing

`typedData` is in the `eth_signTypedData_v4` form: `types` includes `EIP712Domain`, with one member per `domain` field, in the order `name` and `version` as `string`, `chainId` as `uint256`, and `verifyingContract` as `address`. Custody platforms, go-ethereum, MetaMask's `eth-sig-util`, and viem sign it as it is.

> [!WARNING]
>
> ethers rejects `EIP712Domain` in `types`. With ethers, delete `types.EIP712Domain` before signing; the signature is the same.

## Submission

`POST /v1/redemptions` takes `{"redemption": ..., "signature": "0x..."}`: the prepared `redemption`, unchanged, and the signature of `typedData`, before `expiresAt`.

The body is limited to 4 KiB with exactly one leg, and the signature to 1 KiB. [Lifecycle](https://docs.multiliquid.xyz/api-reference/treasury/lifecycle.md) describes what intake checks, what it returns, and how a redemption settles.

## Limits

Preparation is in the write allowance of [Rate limits](https://docs.multiliquid.xyz/api-reference/guides/rate-limits.md), and its body is limited to 1 KiB. When the service is busy, it answers `429` with code `RATE_LIMITED` and `Retry-After`.


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