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

# Batch operations

> Every batch route a capital provider uses, with its scope and rules.

Each route on this page takes a capital provider credential: an API key with the route's scope, or a signed-in account session of a member with the route's role. A route with a JSON body takes `network` in the body, and a `GET` or `DELETE` route takes it in the query string. Every route serves the four [network keys](https://docs.multiliquid.xyz/api-reference/guides/network-keys.md), except `nonce-accounts`, which serves only `svm-mainnet` and `svm-devnet`.

A route names a capital provider by its `id`, the same `capitalProvider.id` that pairs, quotes, and batch orders carry: the stablecoin delegate ID on Ethereum, the capital provider's wallet on Solana. A capital provider of another organization answers `403` with code `FORBIDDEN`, and an ID that is not a batch order capital provider on the network, such as a delegate whose batch orders were never turned on, answers `404` with code `NOT_FOUND`. An `orderId` is a lowercase UUID. A list's `cursor` continues only the listing it was issued for: the same route, network, and filters, with a credential of your organization; another `limit` is fine.

| Method | Path | What it does | Scope | Role |
| - | - | - | - | - |
| `GET` | `/v1/batch-orders/capital-providers` | Lists your capital providers with their operator and capacity | `read` | Member or admin |
| `PUT` | `/v1/batch-orders/capital-providers/{capitalProviderId}/capacity` | Sets a capital provider's posted capacity of one token for one batch | `cp:operate` | Member or admin |
| `PUT` | `/v1/batch-orders/capital-providers/{capitalProviderId}/operator` | Selects the operator wallet that executes the capital provider's orders | `cp:admin` | Admin |
| `DELETE` | `/v1/batch-orders/capital-providers/{capitalProviderId}/operator` | Clears the operator, so the capital provider takes no new orders | `cp:admin` | Admin |
| `GET` | `/v1/batch-orders/batches/{batchId}/requirements` | Totals what a batch needs: output and protocol fees by capital provider, operator, and token | `read` | Member or admin |
| `GET` | `/v1/batch-orders/payloads` | Released orders with their complete signed authorizations, for the operator to execute | `read` | Member or admin |
| `POST` | `/v1/batch-orders/{orderId}/reports` | Records your report of an order's outcome | `cp:operate` | Member or admin |
| `GET` | `/v1/batch-orders/capital-providers/orders` | Lists your orders with the operator each one signed and its deadline | `read` | Member or admin |
| `GET` | `/v1/batch-orders/{orderId}/attempts` | Returns an order's on-chain execution attempts | `read` | Member or admin |
| `POST` | `/v1/batch-orders/nonce-accounts` | Registers a Solana durable nonce account for an operator | `cp:operate` | Member or admin |

The public order reads, `GET /v1/batch-orders/{orderId}` and `GET /v1/batch-orders?user=`, return the same order for every caller, as [Batch orders](https://docs.multiliquid.xyz/api-reference/swap/batch-orders.md#tracking-an-order) describes.

## Your capital providers

`GET /v1/batch-orders/capital-providers?network=` lists your organization's capital providers whose batch orders are on for the network. The response holds the `network`, the `batch`, the `capitalProviders`, and `nextCursor`. It takes `batchId`, `limit`, and `cursor` as [batch info](https://docs.multiliquid.xyz/api-reference/swap/batch-orders.md#batch-info) does, but neither route continues the other's cursor. An empty list means your organization has no such capital provider on the network, as [Get set up](https://docs.multiliquid.xyz/api-reference/capital-providers/overview.md#get-set-up) explains. Each entry has:

| Field | Description |
| - | - |
| `capitalProvider` | `id`, `name`, and `address` |
| `operator` | The operator that new orders name and that executes them; `null` when none is selected |
| `acceptingOrders` | Whether it takes orders now: it has an operator and, on Ethereum, its delegate is swappable, or on Solana it has no Treasury enabled |
| `capacity` | One entry per token it can post capacity in: the `token`, its `status`, and `posted`, `reserved`, and `available`, in whole tokens. `status` is `active` when the capital provider swaps the token now: on Ethereum, its stablecoin or an RWA its delegate whitelists; on Solana, every pair mint. An `inactive` token keeps its capacity, but orders for it fail. |

## Capacity

`PUT /v1/batch-orders/capital-providers/{capitalProviderId}/capacity` sets the posted total of one token for one batch, and returns the token's capacity. It needs `cp:operate`.

```bash theme={null}
curl -X PUT "https://api.multiliquid.xyz/v1/batch-orders/capital-providers/0x58e27f2731863499e6a23a1662ebeed9041d6b40996ea9ca7f4ebc54201823b4/capacity" \
  -H "Authorization: Bearer $MULTILIQUID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "evm-mainnet",
    "batchId": "'"$BATCH_ID"'",
    "token": "0x43415eb6ff9db7e26a15b704e7a3edce97d31c4e",
    "posted": "250000"
  }'
```

```json Response theme={null}
{
  "token": {
    "address": "0x43415eb6ff9db7e26a15b704e7a3edce97d31c4e",
    "symbol": "USTB",
    "name": "Invesco Short Duration US Government Securities Fund",
    "decimals": 6,
    "kind": "rwa",
    "issuer": "Superstate"
  },
  "status": "active",
  "posted": "250000",
  "reserved": "95.238095",
  "available": "249904.761905"
}
```

* `batchId` names the batch by its New York release date, from `2000-01-01` through `9999-12-29`; a date outside that range is rejected with `422` and `INVALID_BODY`. A batch takes capacity until its cut-off whatever its `intakeOpen`, which is about users' orders only.
* `token` is the token's address: on Ethereum, the capital provider's stablecoin or any RWA the network lists, including one its delegate does not whitelist, which is posted as `inactive`; on Solana, a mint of one of its pairs. Any other token is rejected with `422` and `INVALID_BODY`, with `details.field` `token`, and on Ethereum a capital provider the network no longer lists with `422` and `UNSUPPORTED_ROUTE`.
* `posted` is the absolute total in whole tokens, not an increment: a decimal string from `0`, with at most 6 decimal places and no more than the token's decimals. Any other value is rejected with `422` and `INVALID_BODY`, with `details.field` `posted`. You can post for the current batch until its 4:30 PM cut-off and for later batches in advance.
* Accepted orders reserve capacity as they arrive. A total below what they already reserve is rejected with `409` and `CAPACITY_BELOW_RESERVED`, whose `details.reserved` is the floor, in whole tokens.
* On `evm-mainnet`, a nonzero RWA total requires the capital provider's custody to pass the RWA's whitelist adapter; otherwise, or when the RWA has no adapter, the update is rejected with `409` and `CUSTODY_NOT_WHITELISTED`. A zero total skips the check, so unreserved capacity can always be withdrawn.
* An update after the cut-off is rejected with `INTAKE_CLOSED`, and one for a capital provider whose batch orders are off with `BATCH_ORDERS_DISABLED`.

The body is limited to 256 bytes.

## Operator

`PUT /v1/batch-orders/capital-providers/{capitalProviderId}/operator` with `{"network": "...", "operator": "..."}` selects or replaces the wallet that executes the capital provider's orders: an address on Ethereum, a base58 key on Solana. `DELETE` on the same path, with `network` in the query string, clears it. Both return `204` and need `cp:admin`, which only an admin holds and only an admin can grant to a key.

* A capital provider without an operator takes no new orders, and preparation answers `OPERATOR_NOT_SELECTED`.
* Orders are signed for the operator that was current when they were prepared. After a change, a new order signed for the old operator is rejected with `OPERATOR_MISMATCH`, whose `details.expected` names the new one, or is `null` after the operator is cleared. Orders accepted before the change keep their signed operator, which the order list shows and the requirements show beside the current one.
* Clearing an operator leaves the capital provider's capacity stored. Repeating it changes nothing.

The body is limited to 128 bytes.

## Funding requirements

`GET /v1/batch-orders/batches/{batchId}/requirements?network=` totals the accepted, uncanceled orders of one batch by capital provider, signed operator, and token, so you can fund your custody before the release. `batchId` is the release date in `YYYY-MM-DD` form. It needs `read`, filters by `operator` and `capitalProvider`, and pages with `limit` and `cursor`.

| Field | Description |
| - | - |
| `capitalProvider` | `id`, `name`, and `address` |
| `operator` | The operator the orders were signed for, which must execute them |
| `currentOperator` | The capital provider's operator now; `null` when it has none |
| `token` | The token paid out; `null` when the network no longer lists it. On Solana it includes the fee mint, whose `protocolFeeAmount` funds the capital provider's fee vault. |
| `outputAmount` | The orders' total output in the token, in whole tokens; `null` when `token` is `null` |
| `protocolFeeAmount` | The protocol fees you pay in the token, in whole tokens; `null` when `token` is `null` |
| `orderCount` | How many orders the totals cover |

The totals are what you pay out, never netted against what you receive.

## Released payloads

`GET /v1/batch-orders/payloads?network=` returns your organization's orders once their batch is released at 5:00 PM, with what the operator executes. Without `batchId` or `orderId`, it returns the latest released batch. It needs `read`, filters by `operator`, including your earlier operators, and `capitalProvider`, and pages with `limit` and `cursor`. Canceled orders never appear.

Each payload has `runtime`, `orderId`, `batchId`, `acceptedAt`, and `releasedAt`, and:

* on Ethereum, `authorization`, the complete signed authorization: `chainId`, `verifyingContract`, `user`, `operator`, `receiver`, `inputs`, with their signed amounts in base units, `unordered` (always `true`), `nonce`, `deadline`, and the user's `signature`;
* on Solana, the user-signed `transaction` in base64 with the operator's signature slot empty, the `operator`, `nonceAccount`, `nonceValue`, and `deadline`.

Payloads are the only responses that return signatures and executable authorizations, and only to the organization whose capital provider accepted the order. A payload grants no execution rights: only its signed operator can execute it.

## Reports

`POST /v1/batch-orders/{orderId}/reports` records your report of one released order's outcome. It needs `cp:operate`.

```bash theme={null}
curl -X POST "https://api.multiliquid.xyz/v1/batch-orders/019a5c1e-8f3b-7c2d-9e4f-6a1b2c3d4e5f/reports" \
  -H "Authorization: Bearer $MULTILIQUID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "evm-mainnet",
    "status": "success",
    "reason": "Executed in one transaction.",
    "transactionId": "0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  }'
```

`status` says what happened to the order:

| `status` | Report it when | What it does to the order |
| - | - | - |
| `success` | Your operator executed the order | `completed` once Multiliquid verifies the execution. If it is not verified when reports close, the order is `underReview` until Multiliquid resolves it. |
| `userFailure` | A condition on the user's side prevented execution, such as the user's balance, allowance, or eligibility | The order stays `processing` until its deadline, then becomes `failed`, unless Multiliquid verifies an execution |
| `capitalProviderFailure` | You could not execute the order | The same as `userFailure` |

An order you never report is treated as a failure report, and a verified execution makes the order `completed` whatever you report.

* `reason` is required. `transactionId` is optional: the transaction hash on Ethereum or the signature on Solana. It points Multiliquid's search for the execution but is not itself evidence of it.
* Reports are accepted from the batch's release, at or just after 5:00 PM (the payloads' `releasedAt`), until its 5:30 PM close, and never for canceled orders. A report outside that window is rejected with `409` and `REPORTING_CLOSED`.
* Each accepted report adds a revision and returns `201` with it: `revision`, `authorUserId`, `receivedAt`, `status`, `reason`, and `transactionId`. The latest revision counts. A report filed with an organization key has a `null` `authorUserId`.

A report is a claim. Multiliquid assigns each order's state from verified on-chain execution: an order whose reported success it has not verified is `underReview`, as [Batch orders](https://docs.multiliquid.xyz/api-reference/swap/batch-orders.md#tracking-an-order) describes. The body is limited to 4 KiB.

## Your orders

`GET /v1/batch-orders/capital-providers/orders?network=` lists the uncanceled orders of your organization's capital providers, newest first. Each entry has the `order`, as `GET /v1/batch-orders/{orderId}` returns it, with the `operator` it signed, the only wallet that can execute it, and its signed `deadline` in Unix seconds. It needs `read`, filters by `user` and `capitalProvider`, and pages with `limit` and `cursor`.

`GET /v1/batch-orders/{orderId}/attempts?network=` returns up to 100 of an order's Ethereum execution attempts, newest first, each with `transactionId`, `blockNumber`, `observedAt`, and `state`: `confirmed`, `reverted`, `unresolved`, or `orphaned` when a chain reorganization removed it. Solana orders return an empty list. It reads only your organization's uncanceled orders.

## Solana nonce accounts

`POST /v1/batch-orders/nonce-accounts` with `{"network": "svm-mainnet", "address": "<base58>"}` adds a durable nonce account to an operator's pool, and returns `200` with its `address`, `operator`, and `nonceValue`. It needs `cp:operate`. The account must be an initialized nonce account whose authority is an operator that your organization selected on the network:

* an address that is not an initialized nonce account answers `422` with `INVALID_BODY`;
* an account whose authority is not one of your selected operators answers `403` with `FORBIDDEN`;
* an account that holds another operator's order answers `409` with `CONFLICT`.

Each prepared Solana order uses one idle account from its operator's pool, and preparation answers `NONCE_ACCOUNT_UNAVAILABLE` when the pool has none. Each open order holds its account until it executes, expires, or is canceled, so the pool's size limits the operator's open orders. You never advance the nonces: once a released order's deadline passes with its nonce unchanged, Multiliquid records the order as not executed and returns the account to the pool. The body is limited to 128 bytes.

## Errors

| Code | Status | Route |
| - | - | - |
| `INVALID_REQUEST` | 400 | Any route: an invalid or unknown query parameter, or a cursor issued for another listing (`details.field` `cursor`, `details.location` `query`) |
| `UNAUTHORIZED` | 401 | Any route: no credential, or one that is invalid, expired, or revoked |
| `INSUFFICIENT_SCOPE` | 403 | Any route, when the API key lacks its scope |
| `ORGANIZATION_NOT_SELECTED` | 403 | Any route, for an account session that selects no organization |
| `FORBIDDEN` | 403 | Capacity and operator: a capital provider of another organization. Operator: an account session of a member who is not an admin. Nonce accounts: an authority that is not your selected operator. |
| `NOT_FOUND` | 404 | Capacity and operator: an ID that is not a batch order capital provider on the network. Attempts: an order that is not yours, is canceled, or does not exist. |
| `CAPACITY_BELOW_RESERVED` | 409 | Capacity |
| `CUSTODY_NOT_WHITELISTED` | 409 | Capacity |
| `INTAKE_CLOSED` | 409 | Capacity |
| `BATCH_ORDERS_DISABLED` | 409 | Capacity |
| `REPORTING_CLOSED` | 409 | Reports |
| `NOT_FOUND` | 404 | Reports: a canceled order, another organization's order, or an order on another network |
| `INVALID_BODY` | 422 | Any route with a body: an unknown, missing, or invalid field (`details.location` `body`, and `details.field` when known). Capacity: a token the capital provider cannot post (`details.field` `token`). Nonce accounts: an address that is not an initialized nonce account. |
| `UNSUPPORTED_ROUTE` | 422 | Capacity: on Ethereum, a capital provider the network no longer lists |
| `CONFLICT` | 409 | Nonce accounts: an account that holds another operator's order |
| `NETWORK_NOT_ACTIVE` | 503 | Nonce-account registration, and on Solana the capital provider listing when it lists one, on a network where batch orders are not active |

[Errors](https://docs.multiliquid.xyz/api-reference/guides/errors.md#batch-order-codes) gives each code's remedy.


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