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 |
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
| 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 | buildIds 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"
}
],
"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"
}
]
}
}
Request
Responses
- 200
- 400
- 429
- 500
- 502
Cross-chain swap build with the permit embedded
Validation error
Rate limited. Unauthenticated callers share a per-IP budget; send an x-api-key header to lift it. Retry with exponential backoff.
Unexpected server error. Safe to retry with 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.