Spot swap (submit signed permits)

POST 
/v1/actions/swap/spot

Same parameters as GET. The JSON body carries the two-call permit contract: permits (signed offers from a previous response) and optionally builds (the previous response's buildIds, spliced without re-quoting).

Permit flow (permit=auto): the response additionally carries actions.signatures[] (an EIP-712 permit to sign instead of the approve — the spot spender is always the 1delta composer, so ONE signature covers every alternative) and a buildId per quote row. Sign, then POST the same endpoint with {permits: [{permitId, signature}], builds: [buildId]} — the cached builds are re-headed with the permit and answered without re-quoting; the approve permission disappears. BUILD_EXPIRED (builds live ~3 min) means re-quote and resubmit the SAME signature. Without builds, a POST with permits re-quotes and threads the permit into the fresh calldata.

Plain-text reference — POST /v1/actions/swap/spot

Parameters

Parameter	In	Type	Required	Description
chainId	query	string	yes	Chain ID See the ChainId schema for the full set of supported chains.
tokenIn	query	string	yes	Input token address
tokenOut	query	string	yes	Output token address
amount	query	string	yes	Amount in wei
slippage	query	number	yes	Slippage tolerance (basis points)
account	query	string	no	Account address. Include to build transaction, omit for quote-only.
receiver	query	string	no	Receiver address
tradeType	query	0, 1	no	Trade type (0=EXACT_INPUT, 1=EXACT_OUTPUT)
usePendleMintRedeem	query	boolean	no	Use Pendle mint/redeem
permit	query	off, auto, required	no	Permit mode: 'off' (default) approve-only; 'auto' additionally offers a permit signature when the token supports one; 'required' fails with PERMIT_UNAVAILABLE when none exists.

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	Full build response for spot swap (account provided).
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
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.
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")

Example response

{
  "success": true,
  "data": {
    "currencyIn": {},
    "currencyOut": {},
    "quotes": [
      {
        "aggregator": "string",
        "tradeInput": 1.0,
        "tradeOutput": 1.0,
        "tx": {
          "chainType": "evm",
          "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
          "data": "0x617ba037000000000000000000000000c02aaa39b2",
          "value": "0",
          "description": "string"
        },
        "buildId": "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

200

Spot swap build with the permit spliced in

400

Validation error

429

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

500

Unexpected server error. Safe to retry with backoff.

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.