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

# Submissions

> How Multiliquid relays a build's signed transactions, their states, and the realized settlement.

`POST /v1/submissions` relays the transactions of one swap build that the user signed, or on its own the `approval` that a batch order or redemption preparation returns. Multiliquid decodes them, checks that they are Multiliquid transactions, simulates and broadcasts the first, sends the second once the first is confirmed, and tracks each until it is final. Multiliquid never pays a fee: each signed transaction pays its own.

| Method | Path | What it does | Credential |
| - | - | - | - |
| `POST` | `/v1/submissions` | Validates a build's signed transactions, or a preparation's approval, relays the first, and queues the second | None; a key needs `trade` |
| `GET` | `/v1/submissions/{submissionId}` | Returns one submission | None |
| `GET` | `/v1/submissions` | Lists the credential's organization's submissions on one network | Required; a key needs `read` |

## Submitting

The body is `{"network": "...", "signedTransactions": [...]}`, with the transactions in signing order: one transaction, or a build's two, its `approval` then its `swap` on EVM, or its `accountCreation` then its `swap` on Solana. The `approval` of a [batch order](https://docs.multiliquid.xyz/api-reference/swap/place-batch-order.md#2-approve) or a [redemption](https://docs.multiliquid.xyz/api-reference/treasury/redeem-at-size.md#2-approve) preparation is submitted alone. Send a signed EVM transaction as `0x`-prefixed EIP-2718 hex, and a signed Solana transaction as base64 wire bytes.

An EVM transaction that a build or preparation returns is complete, with its [nonce, gas, and fees](https://docs.multiliquid.xyz/api-reference/swap/quote-and-build.md#transactions-on-evm) filled in: the wallet signs it as returned. Two EVM transactions come from one wallet with consecutive nonces, as a build's approval and swap do. If the wallet sent another transaction after the build, its nonce is used, and submission answers `409` with `NONCE_ALREADY_USED`: build again and sign the new transactions.

```bash theme={null}
curl -X POST "https://api.multiliquid.xyz/v1/submissions" \
  -H "Content-Type: application/json" \
  -d '{ "network": "evm-mainnet", "signedTransactions": ["0x02f8…", "0x02f8…"] }'
```

A `signedTransactions` that holds no transaction or more than two, or a `network` the API does not know, answers `422` with code `INVALID_BODY` and `details.field`. A network that the API does not serve answers `503` with code `NETWORK_NOT_ACTIVE` and `details.network`. Neither reads a transaction. Otherwise Multiliquid checks every transaction before it sends any, in this order, and rejects the request with the first failing code, with `422` unless noted. For `INVALID_TRANSACTION` and `UNSUPPORTED_TRANSACTION`, `details.field` names the transaction, such as `signedTransactions[1]`. A rejected request stores nothing.

1. **Decoding and signatures** (`INVALID_TRANSACTION`). EVM accepts legacy (EIP-155), EIP-2930, and EIP-1559 transactions for the network's chain, of at most 8,192 bytes, and no contract creation. Solana accepts legacy and version 0 transactions, including version 0 transactions with address lookup tables, of at most 1,232 bytes, with every required signature present and valid; version 1 transactions are not accepted. Two EVM transactions must have one sender and consecutive nonces, and two Solana transactions one fee payer and different signatures.
2. **Multiliquid transactions** (`UNSUPPORTED_TRANSACTION`). On EVM, a call with no ETH value to the network's swap contract or a listed stablecoin delegate, or an ERC-20 `approve` of a listed token whose spender is one of them. On Solana, a transaction with at least one swap or Treasury program instruction whose other instructions are compute-budget, associated-token-account, SPL Token, or Token-2022 instructions, or a build's `accountCreation`. A Solana durable-nonce transaction, which starts with a System Program instruction, is rejected here. Two transactions must be a build's `approval` or `accountCreation` followed by its `swap`.
3. **Nonce or blockhash.** On EVM, a nonce the sender already used is a `409` with code `NONCE_ALREADY_USED`. On Solana, a blockhash the network no longer accepts is `INVALID_TRANSACTION`, and the transactions are built again.
4. **Simulation** (`SIMULATION_FAILED`) of the first transaction at the latest block or slot. The message names the decoded revert or program error.
5. **Broadcast** of the first transaction. A node that refuses it rejects the request with `TRANSACTION_REJECTED`. A broadcast that does not reach the node is a `503` with code `SERVICE_UNAVAILABLE`.

The second transaction is stored as `queued`. Once the first is `confirmed`, Multiliquid simulates the second and broadcasts it, and it becomes `pending`. If the first fails or expires, the second becomes `failed` without being sent, with `error.code` `PREVIOUS_TRANSACTION_FAILED`. If it fails in simulation, or the node refuses it, when its turn comes, it becomes `failed` with `SIMULATION_FAILED` or `TRANSACTION_REJECTED`. If by then another transaction used its nonce (EVM) or its blockhash expired (Solana), it becomes `expired`.

The response is `{"submissions": [...]}`, a submission for each transaction in the request's order, each with `replayed`. It is `202` when any submission is new, with `replayed: false` on each new one. Here the approval is broadcast and the swap waits behind it:

```json Response expandable theme={null}
{
  "submissions": [
    {
      "submissionId": "019a5c1e-8f3b-7c2d-9e4f-6a1b2c3d4e5e",
      "network": "evm-mainnet",
      "transactionId": "0x4f1b9e2a6c8d0e3f5a7b9c1d2e4f6a8b0c2d4e6f8a0b1c3d5e7f9a1b3c5d7e9f",
      "state": "pending",
      "kind": "approval",
      "user": "0x2222222222222222222222222222222222222222",
      "to": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "nonce": "7",
      "inclusion": null,
      "error": null,
      "confirmedAt": null,
      "finalizedAt": null,
      "explorerUrl": "https://etherscan.io/tx/0x4f1b9e2a6c8d0e3f5a7b9c1d2e4f6a8b0c2d4e6f8a0b1c3d5e7f9a1b3c5d7e9f",
      "settlement": null,
      "createdAt": "2026-11-06T17:18:40Z",
      "updatedAt": "2026-11-06T17:18:40Z",
      "replayed": false
    },
    {
      "submissionId": "019a5c1e-8f3b-7c2d-9e4f-6a1b2c3d4e5f",
      "network": "evm-mainnet",
      "transactionId": "0x0e9ac6a2aa581b0283547ceb6a370f56fa64ee032144c32d06c47f1372571934",
      "state": "queued",
      "kind": "swap",
      "user": "0x2222222222222222222222222222222222222222",
      "to": "0xd66211cf522ba23b59789fff6524c1f03e13e20c",
      "nonce": "8",
      "inclusion": null,
      "error": null,
      "confirmedAt": null,
      "finalizedAt": null,
      "explorerUrl": "https://etherscan.io/tx/0x0e9ac6a2aa581b0283547ceb6a370f56fa64ee032144c32d06c47f1372571934",
      "settlement": null,
      "createdAt": "2026-11-06T17:18:40Z",
      "updatedAt": "2026-11-06T17:18:40Z",
      "replayed": false
    }
  ]
}
```

Each transaction hash or Solana signature identifies its submission, so sending a transaction again returns its existing submission, as it stands, with `replayed: true`, and a request whose transactions were all submitted before returns `200`. A transaction submitted alone and then again with the one after it is a replay, and the later one queues behind it. A transaction that already landed, as when a broadcast's response was lost, is accepted without being simulated or broadcast again.

> [!WARNING]
>
> After a `503` with code `SERVICE_UNAVAILABLE` from `POST /v1/submissions`, the broadcast may or may not have reached the network. Send the same request again, which returns the same submissions, rather than signing new transactions. A newly signed transaction is a different submission, and both could land. A `503` with code `NETWORK_NOT_ACTIVE` is not retried: nothing was read or broadcast, and sending it again fails the same way.

## A submission

`GET /v1/submissions/{submissionId}` returns one submission to any caller. `submissionId` is a UUID; any other value answers `400`, and an unknown one `404`. Once the swap above is final, it reads:

```json Response expandable theme={null}
{
  "submissionId": "019a5c1e-8f3b-7c2d-9e4f-6a1b2c3d4e5f",
  "network": "evm-mainnet",
  "transactionId": "0x0e9ac6a2aa581b0283547ceb6a370f56fa64ee032144c32d06c47f1372571934",
  "state": "finalized",
  "kind": "swap",
  "user": "0x2222222222222222222222222222222222222222",
  "to": "0xd66211cf522ba23b59789fff6524c1f03e13e20c",
  "nonce": "8",
  "inclusion": {
    "runtime": "evm",
    "blockNumber": "26184577",
    "blockHash": "0x53d9d12cbe05a79a7a3fd270aabde576730690ab30b01c63dff81d5467c9b7df",
    "gasUsed": "302417",
    "effectiveGasPrice": "2565960649",
    "fee": "0.000775990121588633",
    "finalized": true
  },
  "error": null,
  "confirmedAt": "2026-11-06T17:19:04Z",
  "finalizedAt": "2026-11-06T17:31:52Z",
  "explorerUrl": "https://etherscan.io/tx/0x0e9ac6a2aa581b0283547ceb6a370f56fa64ee032144c32d06c47f1372571934",
  "settlement": {
    "transactionId": "0x0e9ac6a2aa581b0283547ceb6a370f56fa64ee032144c32d06c47f1372571934",
    "blockNumber": "26184577",
    "settledAt": null,
    "legs": [
      {
        "legIndex": 0,
        "inputToken": {
          "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "symbol": "USDC",
          "name": "USD Coin",
          "decimals": 6,
          "kind": "stablecoin",
          "issuer": "Circle"
        },
        "outputToken": {
          "address": "0x1fecf3d9d4fee7f2c02917a66028a48c6706c179",
          "symbol": "WTGXX",
          "name": "WisdomTree Government Money Market Digital Fund",
          "decimals": 18,
          "kind": "rwa",
          "issuer": "WisdomTree"
        },
        "amountIn": "1",
        "amountOut": "0.9999",
        "fees": [
          {
            "type": "issuer",
            "amount": "0",
            "token": {
              "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
              "symbol": "USDC",
              "name": "USD Coin",
              "decimals": 6,
              "kind": "stablecoin",
              "issuer": "Circle"
            },
            "paidBy": "capitalProvider"
          },
          {
            "type": "spread",
            "amount": "0.0001",
            "token": {
              "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
              "symbol": "USDC",
              "name": "USD Coin",
              "decimals": 6,
              "kind": "stablecoin",
              "issuer": "Circle"
            },
            "paidBy": "user"
          },
          {
            "type": "capitalProvider",
            "amount": "0",
            "token": {
              "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
              "symbol": "USDC",
              "name": "USD Coin",
              "decimals": 6,
              "kind": "stablecoin",
              "issuer": "Circle"
            },
            "paidBy": "user"
          }
        ]
      }
    ]
  },
  "createdAt": "2026-11-06T17:18:40Z",
  "updatedAt": "2026-11-06T17:31:52Z"
}
```

| Field | Description |
| - | - |
| `submissionId` | The submission ID, which `GET /v1/submissions/{submissionId}` takes |
| `network` | The network key |
| `transactionId` | The transaction hash on EVM, the fee payer's signature on Solana |
| `state` | See [States](#states) |
| `kind` | `approval` (an EVM ERC-20 `approve` of a Multiliquid contract), `accountCreation` (a Solana build's `accountCreation`), `swap` (a transaction that performs exactly one swap: an EVM call of the swap contract's `swap` with one leg, or a Solana transaction with exactly one `swap` instruction of the swap program), or `other` (any other relayed transaction, such as an EVM stablecoin delegate administration call, a Solana pair or liquidity administration transaction, or a transaction that carries several swaps) |
| `user` | The wallet that signed and pays for the transaction: the EVM sender or the Solana fee payer |
| `to` | The contract the transaction calls on EVM; on Solana, the swap or Treasury program, or the associated token account program for an account creation |
| `nonce` | EVM only: the sender's nonce, as a decimal string. A Solana submission has no `nonce` field. |
| `inclusion` | `null` until the transaction is included. Then on EVM (`runtime: evm`) `blockNumber`, `blockHash`, `gasUsed` in gas units, `effectiveGasPrice` in wei, `fee` in whole ETH (`gasUsed` × `effectiveGasPrice`, which is in wei, divided by 10^18), and `finalized`; on Solana (`runtime: svm`) `slot`, `fee` in whole SOL, `computeUnits` (`null` when the node did not report them), and `finalized` |
| `error` | For a `failed` submission, why it failed: `code`, `name`, and `message`; `null` otherwise. See [Errors](#errors). |
| `confirmedAt` | When Multiliquid recorded the current inclusion as `confirmed` (see [Confirmation](#confirmation)), whether it succeeded or failed; `null` until then |
| `finalizedAt` | When Multiliquid recorded the inclusion's block or slot as finalized; `null` until then |
| `explorerUrl` | The transaction on a public block explorer: the network's `transactionUrl` from `GET /v1/networks` with the `transactionId` in its placeholder |
| `settlement` | For a `confirmed` or `finalized` submission of kind `swap`: what it realized on chain; `null` for every other submission; see [Settlement](#settlement) |
| `createdAt`, `updatedAt` | When the submission was stored and when its state or inclusion last changed |

The four timestamps are RFC 3339 in UTC with whole seconds, such as `2026-11-06T17:19:04Z`. A value that a submission does not have yet, such as the `inclusion` of a pending one, is present and `null`.

### States

| State | Meaning |
| - | - |
| `queued` | The second transaction of a request, waiting for the first to be `confirmed` |
| `pending` | Broadcast and not yet `confirmed` |
| `confirmed` | Included and successful: on Ethereum, in one block; on Solana, at `confirmed` commitment. See [Confirmation](#confirmation). |
| `finalized` | Included and successful in a finalized block or slot. It never changes. |
| `failed` | Included and reverted, or on Solana landed with an error; or, for a queued transaction, never sent. An included one is final once `finalizedAt` is set; one never sent is final at once. |
| `expired` | Never included: on Solana its blockhash expired; on EVM the sender's nonce was used by another transaction. It never changes. |

### Confirmation

`confirmed` means the transaction is in the chain, not that it is final:

* **On Ethereum**, a submission is `confirmed` as soon as its receipt is in a block, with no further blocks after it. It becomes `finalized` when that block is finalized, about 13 minutes later.
* **On Solana**, it is `confirmed` at the `confirmed` commitment, when a supermajority of validators has voted on its slot. It becomes `finalized` at the `finalized` commitment, about 13 seconds later.

The second transaction of a request is sent as soon as the first is `confirmed`. If a reorganization then removes the first, the second can fail.

A chain reorganization on EVM, or a dropped fork on Solana, that removes an inclusion returns a `confirmed` or `failed` submission to `pending` and clears its `inclusion`, `error`, `confirmedAt`, `finalizedAt`, and `settlement`. Multiliquid tracks it again, and it can be included in another block or slot. Act on `confirmed` only where a reversal is acceptable, and on `finalized` otherwise.

### Errors

A `failed` submission's `error` says why:

| `code` | Meaning |
| - | - |
| `TRANSACTION_FAILED` | The transaction was included and failed. `name` is the decoded revert or program error, such as `AmountOutTooLow`. On EVM, `error` stays `null` when Multiliquid cannot recover the revert. |
| `PREVIOUS_TRANSACTION_FAILED` | A queued transaction was never sent, because the one before it failed or expired |
| `SIMULATION_FAILED` | A queued transaction was never sent, because it failed in simulation when its turn came |
| `TRANSACTION_REJECTED` | A queued transaction was never sent, because the node refused it when its turn came |

A transaction that was never sent has no `name`.

You don't need to rebroadcast. While a submission is pending, Multiliquid rebroadcasts an EVM transaction at most once a minute until its nonce is used, and a Solana transaction every two seconds until its blockhash expires.

### Polling

Multiliquid observes submissions at a fixed pace, so polling faster returns the same answer and only spends the [rate allowance](https://docs.multiliquid.xyz/api-reference/guides/rate-limits.md):

| Runtime | While `queued` or `pending` | While `confirmed`, or `failed` without `finalizedAt` |
| - | - | - |
| EVM | Every 4 seconds | Every 12 seconds, about one block |
| Solana | Every 2 seconds | Every 4 seconds |

Stop polling at `finalized`, at `expired`, and at `failed` once `finalizedAt` is set, or at once when it has no `inclusion`.

### Settlement

A `confirmed` or `finalized` swap carries `settlement`, the realized swap decoded from its own on-chain event when Multiliquid records the inclusion. It is the same object a batch order's settlement is: `transactionId`, `blockNumber` (a decimal string, the slot on Solana), `settledAt`, and `legs`. A submission's `settledAt` is `null`, because Multiliquid does not record the block's time; `confirmedAt` is when it observed the inclusion. The one leg, `legIndex` `0`, has `inputToken` and `outputToken` as token objects, the realized `amountIn` and `amountOut` in whole tokens, and `fees`, each `{type, amount, token, paidBy}` with `amount` in whole tokens of `token`:

* On EVM, the swap contract's event for the swap's single leg, with the issuer, spread, and capital provider fees in the capital provider's stablecoin.
* On Solana, the swap program's event, with one `protocol` fee in the global fee token: the issuer fee and the spread, which the program transfers together. Its `paidBy` is `capitalProvider`, which describes the issuer share; the spread share and the pair fee are already reflected in the amounts.

A settlement is never estimated. A submission's `kind` is `swap` only when its transaction swaps exactly once, so its inclusion is one settlement. A `confirmed` or `finalized` swap has a `null` settlement only when:

* Multiliquid could not decode its on-chain evidence;
* on EVM, Multiliquid could not read the tokens the swap contract registered for its assets within about half an hour of confirmation; or
* it was relayed or finalized before Multiliquid recorded settlements.

A token that the network does not list keeps its address and decimals, with a `null` `symbol`, `name`, and `issuer`, and on Solana a `null` `kind`. A leg's `amountIn` or `amountOut` is `null` only when its token, and so its decimals, cannot be resolved. The [interactive reference](https://api.multiliquid.xyz/scalar) gives the exact `fees` fields of each runtime.

## Organization submissions

A submission made with a credential belongs to the credential's organization. A submission made without one belongs to the organization of the first credential that submits the same signed transaction again, and a submission keeps the first organization it belongs to.

`GET /v1/submissions?network=` lists the organization's submissions on one network, newest first, in the same form as a single submission. It requires a credential and answers `401` without one, and `403` with code `INSUFFICIENT_SCOPE` for an API key without the `read` scope. The list reads stored submissions only, so it answers for every network key, whether or not the API currently serves the network.

| Parameter | Required | Description |
| - | - | - |
| `network` | Yes | A canonical network key, matched exactly |
| `user` | No | Only submissions of this user: the EVM sender or the Solana fee payer |
| `state` | No | Only submissions in this state |
| `kind` | No | Only submissions of this kind |
| `limit` | No | Page size from 1 to 100; defaults to 50 |
| `cursor` | No | The previous page's `nextCursor`, with the same network and filters and a credential of the same organization |

```bash theme={null}
curl "https://api.multiliquid.xyz/v1/submissions?network=evm-mainnet&state=pending" \
  -H "Authorization: Bearer $MULTILIQUID_API_KEY"
```

The response holds `submissions` and `nextCursor`, which is `null` on the last page. A submission that belongs to no organization is never listed.

A `limit` outside 1 to 100, an invalid `user`, an unknown `network`, or a `cursor` that is malformed or was issued for another network, other filters, or another organization answers `400` with code `INVALID_REQUEST`, `details.field` naming the parameter, and `details.location` `query`. An unknown query parameter is also a `400`.

## Limits

The body is limited to 40 KiB, with one or two signed transactions, each of at most 8,192 bytes on EVM or 1,232 bytes (1,644 base64 characters) on Solana. `POST /v1/submissions` is in the anonymous write allowance, and both `GET` routes in the read allowance, of [Rate limits](https://docs.multiliquid.xyz/api-reference/guides/rate-limits.md).

## Related

> [card] [Quotes and builds](https://docs.multiliquid.xyz/api-reference/swap/quote-and-build.md)
>
> The transactions a build returns for the wallet to sign.

> [card] [Retries and idempotency](https://docs.multiliquid.xyz/api-reference/guides/idempotency.md)
>
> Safe retries after a timeout or a `503`.


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