Spot swap (meta-aggregator)

GET 
/v1/actions/swap/spot

Execute a spot swap via the meta-aggregator. Omit account for quote-only. Include account to build full transaction calldata.

Plain-text reference — GET /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

Response 200

Field	Type	Description
success	True
data	object	Informational data (quotes, simulation results, etc.)
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.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.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[]	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.
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[].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[].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

Example response

{
  "success": true,
  "data": {
    "currencyIn": {},
    "currencyOut": {},
    "quotes": [
      {
        "aggregator": "string",
        "tradeInput": 1.0,
        "tradeOutput": 1.0
      }
    ]
  },
  "actions": {
    "transactions": [
      {
        "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string"
      }
    ],
    "alternatives": [
      {
        "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string"
      }
    ],
    "permissions": [
      {
        "to": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string",
        "spender": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
      }
    ]
  }
}

Request

Responses

200

Spot swap quote or full build

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.