# Cross-chain swap (submit signed permits)

Endpoint reference for the 1delta API. Index: https://docs.1delta.io/llms.txt · every endpoint: https://docs.1delta.io/llms-full.txt

---

### POST /v1/actions/swap/x-chain

- operationId: `cross-chain-swap-submit-signed-permits`
- docs: https://docs.1delta.io/1delta-api/cross-chain-swap-submit-signed-permits/
- markdown: https://docs.1delta.io/1delta-api/cross-chain-swap-submit-signed-permits.md
- tags: Swap

Cross-chain swap (submit signed permits)

Same parameters as GET. The JSON body carries `permits` (signed offers from a previous response). The endpoint re-quotes with the permit legs riding INSIDE the composed calldata — safe on value because this endpoint is EXACT_INPUT only — and answers with `permitApplied: true` on every route whose assembled bytes actually carry the leg (verified, never assumed); those routes need no approve. Router-spender routes are untouched. On the same-chain spot fallback, `builds` from the previous response are honoured too (spliced without re-quoting).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `fromChainId` | query | string | yes | Source chain ID |
| `toChainId` | query | string | yes | Destination chain ID |
| `tokenIn` | query | string | yes | Input token address on the source chain |
| `tokenOut` | query | string | yes | Output token address on the destination chain |
| `amount` | query | string | yes | Input amount in wei |
| `slippage` | query | number | yes | Slippage tolerance (basis points) |
| `account` | query | string | no | Account address on the source chain |
| `receiver` | query | string | no | Receiver address on the destination chain |
| `order` | query | "CHEAPEST" \| "FASTEST" | no | Route preference |
| `bridges` | query | string | no | Comma-separated bridge filter |
| `destinationGas` | query | string | no | Native gas to deliver on the DESTINATION with the transfer — a decimal in the destination's native units (`0.005` = 0.005 SOL, `0.0003` = 0.0003 ETH) or `auto` (Solana only: 0.005 SOL). Each quote row then carries `destinationGas: { amount, decimals, mode, paidFrom, cost? }` (base units). `mode: 'native-drop'`: the bridge drops it inside the route's own transaction — Mayan and Relay (EVM destinations; Relay's `topupGas`) out of the bridged amount (`paidFrom: 'output'`, Relay's `cost.usd`), LayerZero OFT and Stargate Fast (taxi) via an executor drop priced into `msg.value` (`paidFrom: 'value'`, `cost` = the extra value; every LayerZero executor caps a drop per destination, e.g. 1.01 PLUME into Plume, and a larger request drops those routes). `mode: 'batch'`: every other route carries a gas LEG beside it, bought with the source native — a NEAR Intents EXACT_OUTPUT deposit (`orderId` = its status key for `/v1/data/bridge/status?bridge=NEAR Intents`), or, where NEAR Intents serves neither chain (Plume), a Gas.zip deposit sized to at least that amount (`bridge: 'GasZip'`, status by its tx hash) — `paidFrom: 'gas-leg'`, `cost` incl. `usd`, whose transaction is `destinationGas.transaction` — send it with the route's transaction in one EIP-5792 `wallet_sendCalls`, or right after it. **From Solana** the leg's SOL transfer is appended to the route's own transaction instead (`bundled: true`, no `destinationGas.transaction`) — one signature; where that cannot be built (a second signer, over the size limit) the leg rides beside it as above. **On EVM** a route that runs through the 1delta composer carries a NEAR Intents leg inside its own transaction too (`bundled: true` — a native sweep to the deposit address prepended to the composer program, its value added to `tx.value`); routes that call their own router (Squid's own, Relay, LI.FI …) are never wrapped, since the router would see the composer as the sender and a depositor-refund would land there. A drop bridge that does not commit to the amount, and every other route when the gas leg cannot be quoted, is dropped rather than ranked. With gas requested, rows are ranked by `tradeOutputNetOfGas`: `tradeOutput` minus what the gas costs ON TOP of it (a gas leg, a `msg.value` drop), converted at current prices — an `output` drop is already inside `tradeOutput`. Without a price the order is by `tradeOutput`. Independently of gas, every EVM row with a transaction reports `nativeFee: { amount, decimals, usd? }` (source gas coin base units) when its `tx.value` exceeds the native input — Axelar execution gas on Squid, LayerZero messaging fees, Fly's fee — which `tradeInput` does not include; the ranking deducts it too (`tradeOutputNetOfGas`), and a client sending a native Max must leave it in the wallet. On Solana the minimum is 0.00089088 SOL, the rent-exempt balance a new wallet must receive. The gas goes to `receiver` (the end user). |
| `permit` | query | "off" \| "auto" \| "required" | no | Permit mode |

**Request body** (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `permits` | object[] | no | Signed permits from a previous response of the SAME endpoint. |
| `permits[].permitId` | string | yes | The `permitId` from `signatures[]` |
| `permits[].signature` | string | yes | The `eth_signTypedData_v4` signature (0x-hex) |
| `builds` | string[] | no | `buildId`s from the previous response's quote rows. When present alongside `permits`, the cached builds are re-headed with the permit — no re-quote, the price you saw is the price you execute. Builds expire after ~3 minutes; a `BUILD_EXPIRED` error means re-quote and resubmit the SAME signature (the permit binds token/spender/value, not the route). |

**Example request body**

```json
{
  "permits": [
    {
      "permitId": "string",
      "signature": "string"
    }
  ],
  "builds": [
    "string"
  ]
}
```

**Response `200`** — Cross-chain swap build with the permit embedded

| Field | Type | Description |
| --- | --- | --- |
| `success` | true |  |
| `data` | object | Informational data (quotes, simulation results, etc.) |
| `data.currencyIn` | object | Input currency info (source chain) |
| `data.currencyOut` | object | Output currency info (destination chain) |
| `data.quotes` | object[] | Candidate routes, best output first. Execute exactly one. |
| `data.quotes[].bridge` | string |  |
| `data.quotes[].tradeInput` | number |  |
| `data.quotes[].tradeOutput` | number |  |
| `data.quotes[].estimatedDuration` | number | Estimated bridging duration in seconds |
| `data.quotes[].approvalTarget` | string | This bridge's deposit contract — the ERC-20 approve spender |
| `data.quotes[].approvalRequired` | boolean | False when the existing on-chain allowance already covers the input amount — or when a submitted permit is embedded in this route's calldata |
| `data.quotes[].permitApplied` | boolean | True when the submitted permit rides inside this route's calldata (verified against the assembled bytes): no approve needed for this route |
| `data.quotes[].tx` | object | An EVM transaction ready to sign and broadcast. Send `to`, `data` and `value` as-is; do not re-encode them. |
| `data.quotes[].tx.chainType` | "evm" | Which VM executes this step. ABSENT means `evm`, which is the only value any endpoint returns today — every EVM response is unchanged. A non-EVM chain would return a different shape (a serialized, PERISHABLE transaction rather than `to`/`data`/`value`) carrying its own `chainType`, so a client that wants to stay forward-compatible should branch on this field rather than assume `to` is present. |
| `data.quotes[].tx.to` | string | Target contract address |
| `data.quotes[].tx.data` | string | Encoded calldata |
| `data.quotes[].tx.value` | string | ETH value to send with the transaction |
| `data.quotes[].tx.description` | string | Human-readable label. For `alternatives`, this is the aggregator name (e.g. "Paraswap"). For `transactions`, describes the setup action (e.g. "Switch e-mode to 1"). |
| `data.permissionTxns` | object[] | ERC-20 approves per bridge deposit contract; each is labeled with the bridge name — execute only the one matching the chosen quote |
| `data.permissionTxns[].to` | string | Target contract address |
| `data.permissionTxns[].data` | string | Encoded calldata |
| `data.permissionTxns[].value` | string | ETH value |
| `data.permissionTxns[].description` | string | Human-readable description of the approval (e.g. "Approve borrow for AAVE_V3", "Approve ERC20") |
| `data.permissionTxns[].spender` | string | ERC-20 approve spender (x-chain permissions). Match it against the selected quote's `approvalTarget` — several bridges can share one spender, so do not match by description. |
| `data.permissionTxns[].type` | "ERC20" \| "Lender" | What kind of grant this is. A `signatures[]` offer names the `type` it replaces via its `replaces` field. |
| `data.quotes[].aggregator` | string |  |
| `data.quotes[].buildId` | string | Present when `permit=auto\|required` produced a signature offer. Send it back in the POST body (`builds[]`) together with the signed permit to splice this exact build — no re-quote. Expires after ~3 minutes. |
| `data.asyncAlternatives` | object[] | Solana only, present only when non-empty: routes that do NOT settle in the signed transaction (Nest RWA shares: USDC → share mints over CCTP → Plume → LayerZero; share → USDC queues Nest's async redemption). Never part of `quotes[]` and never ranked against it — a client must show `settlement` before offering one. See NEST_SOLANA.md. |
| `data.asyncAlternatives[].aggregator` | "Nest" |  |
| `data.asyncAlternatives[].action` | "mint" \| "redeem-request" |  |
| `data.asyncAlternatives[].atomic` | false |  |
| `data.asyncAlternatives[].tradeInput` | number |  |
| `data.asyncAlternatives[].tradeOutput` | number | Indicative: priced when the deposit / redemption executes on Plume. No slippage bound applies. |
| `data.asyncAlternatives[].settlement` | object |  |
| `data.asyncAlternatives[].settlement.kind` | "async-crosschain" |  |
| `data.asyncAlternatives[].settlement.etaSeconds` | integer | Indicative; null when an operator fulfils it (a redemption request). |
| `data.asyncAlternatives[].settlement.statusUrl` | string | Replace `{signature}` with the Solana transaction signature. |
| `data.asyncAlternatives[].settlement.via` | string[] |  |
| `data.asyncAlternatives[].fees` | object[] |  |
| `data.asyncAlternatives[].fees[].asset` | string |  |
| `data.asyncAlternatives[].fees[].amount` | string | Raw units |
| `data.asyncAlternatives[].fees[].kind` | string |  |
| `data.asyncAlternatives[].note` | string |  |
| `data.asyncAlternatives[].buildError` | object | The quote stands but the issuer refused to build (e.g. OWNER_TOKEN_ACCOUNT_NOT_FOUND). |
| `data.asyncAlternatives[].buildError.code` | string |  |
| `data.asyncAlternatives[].buildError.message` | string |  |
| `data.asyncAlternatives[].tx` | object | Partially signed by Nest: add the wallet signature, never recompile the message. |
| `data.asyncAlternatives[].tx.chainType` | "svm" |  |
| `data.asyncAlternatives[].tx.transaction` | string | Base64 v0 transaction |
| `data.asyncAlternatives[].tx.lastValidBlockHeight` | integer |  |
| `data.asyncAlternatives[].tx.partiallySigned` | true |  |
| `actions` | object | Transaction calldata and approvals. Null for quote-only responses (no account provided). |
| `actions.transactions` | object[] | Pre-trade setup transactions (e.g. e-mode switch, collateral enable). Execute these before the main swap. Empty when no setup is needed. |
| `actions.transactions[].chainType` | "evm" | Which VM executes this step. ABSENT means `evm`, which is the only value any endpoint returns today — every EVM response is unchanged. A non-EVM chain would return a different shape (a serialized, PERISHABLE transaction rather than `to`/`data`/`value`) carrying its own `chainType`, so a client that wants to stay forward-compatible should branch on this field rather than assume `to` is present. |
| `actions.transactions[].to` | string | Target contract address |
| `actions.transactions[].data` | string | Encoded calldata |
| `actions.transactions[].value` | string | ETH value to send with the transaction |
| `actions.transactions[].description` | string | Human-readable label. For `alternatives`, this is the aggregator name (e.g. "Paraswap"). For `transactions`, describes the setup action (e.g. "Switch e-mode to 1"). |
| `actions.alternatives` | object[] | DEX aggregator swap transactions sorted by best output (descending). Each entry's `description` is the aggregator name. The client should pick one to execute. Present on loop action endpoints. |
| `actions.alternatives[].chainType` | "evm" | Which VM executes this step. ABSENT means `evm`, which is the only value any endpoint returns today — every EVM response is unchanged. A non-EVM chain would return a different shape (a serialized, PERISHABLE transaction rather than `to`/`data`/`value`) carrying its own `chainType`, so a client that wants to stay forward-compatible should branch on this field rather than assume `to` is present. |
| `actions.alternatives[].to` | string | Target contract address |
| `actions.alternatives[].data` | string | Encoded calldata |
| `actions.alternatives[].value` | string | ETH value to send with the transaction |
| `actions.alternatives[].description` | string | Human-readable label. For `alternatives`, this is the aggregator name (e.g. "Paraswap"). For `transactions`, describes the setup action (e.g. "Switch e-mode to 1"). |
| `actions.permissions` | object[] | Approval/delegation transactions that must execute before both `transactions` and `alternatives`. Includes ERC20 allowances (targeting the composer contract) and lender borrow/withdrawal delegations (targeting the lending protocol contract directly). Filtered against on-chain state so only missing approvals are returned. Null when no approvals are needed. |
| `actions.permissions[].to` | string | Target contract address |
| `actions.permissions[].data` | string | Encoded calldata |
| `actions.permissions[].value` | string | ETH value |
| `actions.permissions[].description` | string | Human-readable description of the approval (e.g. "Approve borrow for AAVE_V3", "Approve ERC20") |
| `actions.permissions[].spender` | string | ERC-20 approve spender (x-chain permissions). Match it against the selected quote's `approvalTarget` — several bridges can share one spender, so do not match by description. |
| `actions.permissions[].type` | "ERC20" \| "Lender" | What kind of grant this is. A `signatures[]` offer names the `type` it replaces via its `replaces` field. |
| `actions.signatures` | object[] | EIP-712 payloads the user can sign INSTEAD of sending the corresponding `permissions` entry. Only present when the caller opted in with `permit=auto\|required` and a permit path exists. Sign with `eth_signTypedData_v4`, then POST the same endpoint with `{permits: [{permitId, signature}]}` (plus `builds` where the response issued buildIds) — the permit executes inside the main transaction. |
| `actions.signatures[].permitId` | string | Opaque, self-describing handle for this permit. Round-trip it verbatim: POST `{permits: [{permitId, signature}]}` back to the same endpoint. |
| `actions.signatures[].kind` | "erc2612" \| "dai" \| "permit2" \| "aaveCredit" \| "morphoAuth" \| "cometAuth" | Permit flavour |
| `actions.signatures[].typedData` | object | Ready for `eth_signTypedData_v4` (domain, types incl. EIP712Domain, primaryType, message). All numeric fields are decimal strings. |
| `actions.signatures[].replaces` | string | Which `permissions` entry this signature replaces (`ERC20` \| `Lender`) |
| `actions.signatures[].spender` | string | Who the signature authorises. Match against the permission / quote (`approvalTarget`) it replaces — on multi-spender responses (x-chain) only routes whose approvalTarget equals this spender are covered by the signature. |
| `actions.signatures[].description` | string | Human-readable label for this entry. |
| `actions.signatures[].unscoped` | boolean | True when the grant is NOT amount-scoped (full position control until revoked) — surface this to the user. |
| `actions.signatures[].deadline` | string | Unix seconds after which the signature is worthless (default: 30 minutes). |
| `actions.signs` | object[] | Messages that MUST be signed before anything can be sent (unlike `signatures`, which are optional permit offers). When non-empty, `transactions` and `alternatives` are EMPTY: sign `typedData` with `eth_signTypedData_v4` (or, for `format: personal_sign`, `message` with `personal_sign`), then call `submit` with the signature under `submit.signatureField`, and execute what that answers. `permissions` may still be present and can be sent before or after signing. Produced by Inverse FiRM loops (`/loop/leverage`, `/loop/close`), Morpho Midnight make, Term order-sign and the Lista leg of `/rewards/claim`. |
| `actions.signs[].purpose` | "authorize-action" \| "publish-order" \| "authenticate" | `authorize-action`: the signature authorises an on-chain action and `submit` answers its transaction (Inverse ALE loops). `publish-order`: the signature makes an off-chain order and `submit` publishes it (Midnight make, Term order-sign). `authenticate`: the signature is a LOGIN to a third-party API that serves the data the transaction needs (Lista reward proofs); it authorises nothing on-chain. |
| `actions.signs[].format` | "eip712" \| "personal_sign" | `eip712`: sign `typedData` with `eth_signTypedData_v4`. `personal_sign`: sign the UTF-8 `message` with `personal_sign`. |
| `actions.signs[].typedData` | object | `format: eip712` only. Ready for `eth_signTypedData_v4`. All numeric fields are decimal strings. |
| `actions.signs[].message` | string | `format: personal_sign` only. The exact text to sign; send it back verbatim (it is part of `submit.params`). |
| `actions.signs[].signer` | string | The address that must sign. The server recovers the signer and refuses any other. |
| `actions.signs[].deadline` | string | Unix seconds after which the signature is worthless. |
| `actions.signs[].spender` | string | Who the signature authorises. |
| `actions.signs[].description` | string | Human-readable label for this entry. |
| `actions.signs[].submit` | object |  |
| `actions.signs[].submit.method` | "GET" \| "POST" |  |
| `actions.signs[].submit.endpoint` | string | Path on this API, e.g. `/v1/actions/loop/leverage`. |
| `actions.signs[].submit.params` | object | GET: the complete query to send — the original request plus the handle the signature is for (`permitId`). Replay verbatim. |
| `actions.signs[].submit.body` | object | POST: the JSON body to send, verbatim. |
| `actions.signs[].submit.signatureField` | string | The query param (GET) or body field (POST) that carries the signature. |
| `actions.permitSkipped` | object[] | Why a permit was NOT offered for a permission, when one was asked for (`permit=auto\|required`). The corresponding approve transaction stands. |
| `actions.permitSkipped[].replaces` | string | Which permission kind stays a transaction (`ERC20` \| `Lender`) |
| `actions.permitSkipped[].reason` | string |  |

**Example response**

```json
{
  "success": true,
  "data": {
    "currencyIn": {},
    "currencyOut": {},
    "quotes": [
      {
        "bridge": "string",
        "tradeInput": 1,
        "tradeOutput": 1,
        "estimatedDuration": 1,
        "approvalTarget": "string",
        "approvalRequired": true,
        "permitApplied": true,
        "tx": {
          "chainType": "evm",
          "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
          "data": "0x617ba037000000000000000000000000c02aaa39b2",
          "value": "0",
          "description": "string"
        }
      }
    ],
    "permissionTxns": [
      {
        "to": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string",
        "spender": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "type": "ERC20"
      }
    ]
  },
  "actions": {
    "transactions": [
      {
        "chainType": "evm",
        "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string"
      }
    ],
    "alternatives": [
      {
        "chainType": "evm",
        "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string"
      }
    ],
    "permissions": [
      {
        "to": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string",
        "spender": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "type": "ERC20"
      }
    ],
    "signatures": [
      {
        "permitId": "string",
        "kind": "erc2612",
        "typedData": {},
        "replaces": "string",
        "spender": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "description": "string",
        "unscoped": true,
        "deadline": "string"
      }
    ],
    "signs": [
      {
        "purpose": "authorize-action",
        "format": "eip712",
        "typedData": {},
        "message": "string",
        "signer": "string",
        "deadline": "string",
        "spender": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "description": "string",
        "submit": {
          "method": "GET",
          "endpoint": "string",
          "params": {},
          "body": {},
          "signatureField": "string"
        }
      }
    ],
    "permitSkipped": [
      {
        "replaces": "string",
        "reason": "string"
      }
    ]
  }
}
```

**Response `400`** — Validation error

**Response `429`** — Rate limited. Unauthenticated callers share a per-IP budget; send an `x-api-key` header to lift it. Retry with exponential backoff.

**Response `500`** — Unexpected server error. Safe to retry with backoff.

**Response `502`** — An upstream data source or protocol origin failed (`error.code` is `ORIGIN_FAILED`). `error.details` carries the per-origin status. This is also what a missing or malformed required parameter currently returns, rather than a 400.
