Skip to main content

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.

Uncurated tokens. tokenIn / tokenOut need not be in the chain's curated token list: a missing leg is resolved on-chain (name/symbol/decimals, the same lookup as /v1/data/token/metadata), so a token nobody has curated still quotes and builds. Such a leg carries no USD price (its assetGroup is deliberately absent — contract-supplied symbols must never join to a real asset's price), which has one consequence: tradeType=1 (EXACT_OUTPUT) sizes the input from the USD ratio of the two legs and is refused when either leg is unpriced — use EXACT_INPUT. An address that is not an ERC-20 on the chain answers Unknown Token: <address>, naming the leg.

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 — GET /v1/actions/swap/spot

Parameters

ParameterInTypeRequiredDescription
chainIdquerystringyesChain ID See the ChainId schema for the full set of supported chains.
tokenInquerystringyesInput token address
tokenOutquerystringyesOutput token address
amountquerystringyesAmount in wei
slippagequerynumberyesSlippage tolerance (basis points)
accountquerystringnoAccount address. Include to build transaction, omit for quote-only.
receiverquerystringnoReceiver address
tradeTypequery0, 1noTrade type (0=EXACT_INPUT, 1=EXACT_OUTPUT)
usePendleMintRedeemquerybooleannoUse Pendle mint/redeem
permitqueryoff, auto, requirednoPermit mode: 'off' (default) approve-only; 'auto' additionally offers a permit signature when the token supports one; 'required' fails with PERMIT_UNAVAILABLE when none exists.

Response 200

FieldTypeDescription
successTrue
dataobjectInformational data (quotes, simulation results, etc.)
data.currencyInobjectInput currency info
data.currencyOutobjectOutput currency info
data.quotesobject[]Candidate routes, best output first. Execute exactly one.
data.quotes[].aggregatorstring
data.quotes[].tradeInputnumber
data.quotes[].tradeOutputnumber
data.currencyInobjectInput currency info
data.currencyOutobjectOutput currency info
data.quotesobject[]Candidate routes, best output first. Execute exactly one.
data.quotes[].aggregatorstring
data.quotes[].tradeInputnumber
data.quotes[].tradeOutputnumber
data.quotes[].txobjectAn EVM transaction ready to sign and broadcast. Send to, data and value as-is; do not re-encode them.
data.quotes[].tx.chainTypeevmWhich 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.tostringTarget contract address
data.quotes[].tx.datastringEncoded calldata
data.quotes[].tx.valuestringETH value to send with the transaction
data.quotes[].tx.descriptionstringHuman-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[].buildIdstringPresent 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.permissionTxnsobject[]Approvals needed for this specific quote. Most integrators should use the deduplicated envelope-level actions.permissions instead.
data.permissionTxns[].tostringTarget contract address
data.permissionTxns[].datastringEncoded calldata
data.permissionTxns[].valuestringETH value
data.permissionTxns[].descriptionstringHuman-readable description of the approval (e.g. "Approve borrow for AAVE_V3", "Approve ERC20")
data.permissionTxns[].spenderstringERC-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[].typeERC20, LenderWhat kind of grant this is. A signatures[] offer names the type it replaces via its replaces field.
actionsobjectTransaction calldata and approvals. Null for quote-only responses (no account provided).
actions.transactionsobject[]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[].chainTypeevmWhich 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[].tostringTarget contract address
actions.transactions[].datastringEncoded calldata
actions.transactions[].valuestringETH value to send with the transaction
actions.transactions[].descriptionstringHuman-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.alternativesobject[]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[].chainTypeevmWhich 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[].tostringTarget contract address
actions.alternatives[].datastringEncoded calldata
actions.alternatives[].valuestringETH value to send with the transaction

Example response

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

Spot swap quote or full build