Cross-chain swap (submit signed permits)

POST /v1/actions/swap/x-chain

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

Plain-text reference — POST /v1/actions/swap/x-chain

Parameters

Parameter	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

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

Response 200

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.currencyIn`	object	Input currency info
`data.currencyOut`	object	Output currency info
`data.quotes`	object[]	Candidate routes, best output first. Execute exactly one.
`data.quotes[].aggregator`	string
`data.quotes[].tradeInput`	number
`data.quotes[].tradeOutput`	number
`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.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.permissionTxns`	object[]	Approvals needed for this specific quote. Most integrators should use the deduplicated envelope-level `actions.permissions` instead.
`data.permissionTxns[].to`	string	Target contract address

Example response

{
  "success": true,
  "data": {
    "currencyIn": {},
    "currencyOut": {},
    "quotes": [
      {
        "bridge": "string",
        "tradeInput": 1.0,
        "tradeOutput": 1.0,
        "estimatedDuration": 1.0,
        "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"
      }
    ]
  }
}

Request

Responses

Cross-chain swap build with the permit embedded

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

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.

Cross-chain swap (submit signed permits)

/v1/actions/swap/x-chain

Request​

Responses​

Request

Responses