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

# API conventions

> The names and shapes that are the same on every route.

The API names a concept the same way on every route, gives it the same shape, and answers the same condition the same way. Code that handles a token object, a `state`, or a repeated request on one route handles it on all of them. A field that departs from a convention is described on its route's page.

## Names

| Concept | Convention |
| - | - |
| State | The field you poll is `state`, a `camelCase` value such as `pending`, `processing`, or `completed`, and a list that filters by it takes `state`. |
| IDs | A resource's own ID is `submissionId`, `orderId`, or `redemptionId`, in its body and as its path parameter, as in `GET /v1/submissions/{submissionId}`. |
| Transaction identifier | `transactionId`: the transaction hash on EVM, the signature on Solana. The explorer templates of `GET /v1/networks` use the same name, `{transactionId}`. The [Data API](https://docs.multiliquid.xyz/api-reference/data/endpoints.md) (`/v1/info`, `/v1/transactions`, `/v1/volume`) predates these conventions and departs from them where its page says, for example `transactionHash`, a block `timestamp` in Unix seconds, and the `lpAddress` filter. |
| Block numbers | Decimal strings: `blockNumber` on EVM and `slot` on Solana. A field that serves both runtimes is `blockNumber`, which holds the slot on Solana. |
| Parties | `user` is the wallet that signs and pays, `receiver` the wallet that receives the output, `operator` the wallet that a signed order or redemption authorizes to execute it, and `capitalProvider` the capital provider. Responses and list filters use the same names. A `capitalProvider` parameter, filter, or top-level error detail takes a capital provider ID, the `id` of the capital provider object; each entry of `NO_QUOTE`'s `details.providers` carries the object itself. |
| Amounts | Whole tokens as decimal strings, such as `"1500.25"` USDC, named `amountIn` and `amountOut`; [Amounts](#amounts) gives the rules. `swapType` is `exactIn` or `exactOut` and says which amount is exact, and the signed bound on the other one is `minAmountOut` or `maxAmountIn`. The token is named beside the amount, as `inputToken` and `outputToken`. A prepared order or redemption that you send back keeps the amount names it is signed under, `assetInAmt` and `assetOutAmt`, in base units, but names its IDs `assetInId`, `assetOutId`, and `stablecoinDelegateId`, where the typed data names them `assetInID`, `assetOutID`, and `stablecoinDelegateID`. Send it back exactly as prepared. |
| Percentages | Whole basis points, as a JSON integer whose name ends in `Bps`, such as `slippageBps` and `rateBps`. `10` is 0.1%. |
| Timestamps | Names end in `At`, such as `createdAt` and `settledAt`, and the value is RFC 3339 in UTC with whole seconds, such as `2026-11-09T21:00:00Z`. A value that a wallet signs, such as `deadline` or a batch order cancellation's `expiresAt`, is Unix seconds as a decimal string, and `deadlineAt` repeats a redemption's deadline as a time. |
| Network | `network`, a runtime-prefixed [network key](https://docs.multiliquid.xyz/api-reference/guides/network-keys.md) such as `evm-mainnet`. A `GET` or `DELETE` route takes it in the query string, and a `POST` or `PUT` route in the JSON body. A prepared object that you send back carries it too, as a batch order's `order.network` does. A redemption's `network` is optional and defaults to `evm-mainnet`. |

## Amounts

Every token amount the API takes or returns is in whole tokens, as a decimal string: `"1500.25"` is 1,500.25 USDC. The API converts it with the token's `decimals`, so you never scale an amount yourself.

* **In a request**, an amount has at most 6 decimal places, and no more than the token's decimals. It is a JSON string, never a JSON number, with digits and at most one `.` between them: no sign, exponent, separators, or spaces. Any other value is rejected with `INVALID_BODY`, or `INVALID_REQUEST` in a query string, and `details.field` names it.
* **In a response**, an amount is exact, up to the token's decimals, without trailing zeros or an exponent, so an 18-decimal token such as \$TSY can show 18 decimal places: `"995.210000000000000001"`. Store it as a string or a decimal type, not a floating-point number.
* **Unknown decimals.** An amount whose token's decimals Multiliquid cannot resolve is `null`, never base units: a batch order's amounts and its settlement legs' when the network no longer lists the token (a submission's settlement keeps the decimals it recorded, so its amounts are `null` only when the token cannot be resolved at all), a batch requirement's totals when its `token` is `null`, an amount in [transaction history](https://docs.multiliquid.xyz/api-reference/data/endpoints.md#transaction-history) whose asset is not listed, and a [decoded](https://docs.multiliquid.xyz/api-reference/swap/quote-and-build.md#decode) effect whose token is not listed, unless a Solana `TransferChecked` or `ApproveChecked` states its decimals.
* **Errors.** The amounts in an error's `details` and message, such as `required`, `available`, `bound`, and `quoted`, are whole tokens too.
* **Network fees.** A submission's `inclusion.fee` is whole ETH on Ethereum and whole SOL on Solana. Gas stays in gas units, and gas prices in wei.

What the user signs, or what you send back unchanged, keeps the on-chain base units, so that it matches the signature:

* EIP-712 `typedData`, and the prepared batch order `order` and redemption `redemption` that you send back, including the body of `POST /v1/redemptions`;
* a built or prepared transaction's `data`, `value`, `gas`, fees, and `serialized` bytes, and the arguments of a decoded call or instruction;
* a capital provider's released order payloads, which the operator executes.

The redemption fields that older SDK versions read, such as `signedTsyBound` and `actualUsdcOut`, also keep base units. The [interactive reference](https://api.multiliquid.xyz/scalar) marks each one deprecated.

## Shared objects

A response that describes one of these uses the same object on every route.

| Object | Fields |
| - | - |
| Token | `address`, `symbol`, `name`, `decimals`, `kind` (`stablecoin` or `rwa`), and `issuer`. An error's `details.token` and a check's `token` are the address alone. |
| Capital provider | `id`, `address`, and `name`. The `id` is the stablecoin delegate ID on EVM and the capital provider's wallet on Solana. |
| Fees | `fees` lists one entry per fee: `type`, `amount`, `token` (a token object), and `paidBy`, which names whose amounts the fee reduces. |
| Settlement | What changed hands: `inputToken` and `outputToken` (token objects), `amountIn`, `amountOut`, and `fees` where the on-chain event reports them. |

Each settlement also names its transaction:

| Settlement of | Fields |
| - | - |
| A submission of kind `swap`, or a batch order | `transactionId`, `blockNumber`, `settledAt`, and `legs`, each with `legIndex`, `inputToken`, `outputToken`, `amountIn`, `amountOut`, and `fees` |
| A redemption | `transactionId`, `blockNumber`, `settledAt`, `inputToken`, `outputToken`, `amountIn`, and `amountOut` |

In a submission's or batch order's settlement, `blockNumber` and `settledAt` are `null` when not recorded, and a submission's `settledAt` always is. A leg's `inputToken`, `outputToken`, or `fees` is `null` when the token cannot be resolved, and so is its `amountIn` or `amountOut` in that token. A settlement token's `symbol`, `name`, and `kind` are `null` for a token Multiliquid does not configure.

An object whose form depends on the network carries `runtime`, `evm` or `svm`, which names its form.

## Absent values

A field that does not apply to a form of an object is omitted: a Solana submission has no `nonce`, and a Solana build's checks have no `allowance`. A field that applies but has no value, or none yet, is present and `null`: a token's `issuer`, a capital provider's `name`, a pending submission's `inclusion`, and a redemption's `settlement` before it completes. A field your credential may not read, such as a redemption's `receiver`, is omitted.

## Lists

A paginated list returns `nextCursor`, `null` on the last page. Pass it back as `cursor` to the same route, with the same network and filters, and, for a list of your organization's records, with a credential of the same organization. Another `limit` is fine. A cursor sent with anything else is a `400` with code `INVALID_REQUEST`, `details.field` `cursor`, and `details.location` `query`.

## Address casing

An EVM address or hex ID in a response is lowercase `0x` hex, so one token, capital provider, or wallet reads the same on every route: in token and capital provider objects, in `user`, `receiver`, and `operator`, in check and error-detail values such as `token`, `spender`, and `expected`, and in a message that names an address. A request accepts an address in lowercase, in uppercase, or in EIP-55 mixed case, and a mixed-case address must carry a valid checksum.

EIP-712 `typedData`, and a prepared `order` or `redemption` that you sign and post back, keep the casing they are signed in. Solana addresses and signatures are base58.

## Repeated requests

An identical repeat of a signed request answers `2xx` with the resource and `replayed: true`, and a first acceptance carries `replayed: false`. `POST /v1/submissions` sets `replayed` on each entry of `submissions`. `POST /v1/redemptions` answers this way too, except that repeating a failed redemption whose `failure.resubmittable` is `true` restarts it, with `200` and `replayed: false`.

Batch order intake is the exception. It never returns an existing order as a success, and answers `409` with code `DUPLICATE_ORDER` and the accepted order in `details.orderId`. [Retries and idempotency](https://docs.multiliquid.xyz/api-reference/guides/idempotency.md) covers each route.

## One status per condition

* **A conflict with current state** is `409` on every route. `NONCE_ALREADY_USED` and `PREPARED_ORDER_STALE` always are.
* **A signed operator that is not the one required** is `OPERATOR_MISMATCH`, a `409` whose `details.expected` is the operator to sign for, or `null` when there is none.
* **A shortfall** reports `required` and `available` in `details`, in whole tokens, with `token` where a token is involved; `INSUFFICIENT_CREDITS` is always \$TSY and `INSUFFICIENT_LIQUIDITY` always USDC, and they name none.
* **A network that the API does not serve** answers `503` with code `NETWORK_NOT_ACTIVE` and `details.network` on a route that needs the network, such as a quote, a build, or a submit. Sending the request again cannot succeed. A route that only reads stored records, such as listing or reading submissions, answers for every known network.
* **An unknown network key** is a validation error on every route, and a transient outage is `SERVICE_UNAVAILABLE`.
* **An unknown query parameter** is a `400` with code `INVALID_REQUEST` on every route in the OpenAPI document, a route that takes a JSON body included, so a misspelled filter or a credential in the query string is never ignored.
* **A rejected value** is named: an `INVALID_REQUEST` or `INVALID_BODY` error gives `details.field` when one parameter or field is at fault, and `details.location` (`query`, `path`, or `body`) when the place of the rejected value is known. A conflict between values, such as `createdAfter` at or after `createdBefore`, gives only its location, and a rejection that cannot name the value at fault, such as a value the service cannot store, has no `details`.

## Related

> [card] [Errors](https://docs.multiliquid.xyz/api-reference/guides/errors.md)
>
> The error body and every error code.

> [card] [Network keys](https://docs.multiliquid.xyz/api-reference/guides/network-keys.md)
>
> Network names and the networks each route serves.


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