# 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 |
| `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. |
| `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.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"
      }
    ],
    "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.