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.
Asynchronous alternatives (Solana). For USDC ↔ a Nest RWA share (nALPHA, nTBILL, nOPAL, …) the response may carry asyncAlternatives[] BESIDE quotes[]: Nest's own mint (CCTP → Plume → LayerZero, ~2 min) or async redemption request. They do not settle in the signed transaction, are never ranked against quotes[], carry atomic: false and a settlement (etaSeconds, statusUrl), and their transactions are partially signed by Nest.
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 |
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. |
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.asyncAlternatives | object[] | Solana only, present only when non-empty: routes that do NOT settle in the signed transaction (Nest RWA shares: USDC → share mints over CCTP → Plume → LayerZero; share → USDC queues Nest's async redemption). Never part of quotes[] and never ranked against it — a client must show settlement before offering one. See NEST_SOLANA.md. |
data.asyncAlternatives[].aggregator | Nest | |
data.asyncAlternatives[].action | mint, redeem-request | |
data.asyncAlternatives[].atomic | False | |
data.asyncAlternatives[].tradeInput | number | |
data.asyncAlternatives[].tradeOutput | number | Indicative: priced when the deposit / redemption executes on Plume. No slippage bound applies. |
data.asyncAlternatives[].settlement | object | |
data.asyncAlternatives[].settlement.kind | async-crosschain | |
data.asyncAlternatives[].settlement.etaSeconds | integer | Indicative; null when an operator fulfils it (a redemption request). |
data.asyncAlternatives[].settlement.statusUrl | string | Replace {signature} with the Solana transaction signature. |
data.asyncAlternatives[].settlement.via | string[] | |
data.asyncAlternatives[].fees | object[] | |
data.asyncAlternatives[].fees[].asset | string | |
data.asyncAlternatives[].fees[].amount | string | Raw units |
data.asyncAlternatives[].fees[].kind | string | |
data.asyncAlternatives[].note | string | |
data.asyncAlternatives[].buildError | object | The quote stands but the issuer refused to build (e.g. OWNER_TOKEN_ACCOUNT_NOT_FOUND). |
data.asyncAlternatives[].buildError.code | string | |
data.asyncAlternatives[].buildError.message | string | |
data.asyncAlternatives[].tx | object | Partially signed by Nest: add the wallet signature, never recompile the message. |
data.asyncAlternatives[].tx.chainType | svm | |
data.asyncAlternatives[].tx.transaction | string | Base64 v0 transaction |
data.asyncAlternatives[].tx.lastValidBlockHeight | integer | |
data.asyncAlternatives[].tx.partiallySigned | True | |
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. |
Example response
{
"success": true,
"data": {
"currencyIn": {},
"currencyOut": {},
"quotes": [
{
"aggregator": "string",
"tradeInput": 1.0,
"tradeOutput": 1.0
}
],
"asyncAlternatives": [
{
"aggregator": "Nest",
"action": "mint",
"atomic": false,
"tradeInput": 1.0,
"tradeOutput": 1.0,
"settlement": {
"kind": "async-crosschain",
"etaSeconds": 1,
"statusUrl": "string",
"via": [
"string"
]
},
"fees": [
{
"asset": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"amount": "1000000000000000000",
"kind": "string"
}
],
"note": "string",
"buildError": {
"code": "string",
"message": "string"
},
"tx": {
"chainType": "svm",
"transaction": "string",
"lastValidBlockHeight": 1,
"partiallySigned": true
}
}
]
},
"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
Spot swap quote or full build
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.