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.

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

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.asyncAlternativesobject[]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[].aggregatorNest
data.asyncAlternatives[].actionmint, redeem-request
data.asyncAlternatives[].atomicFalse
data.asyncAlternatives[].tradeInputnumber
data.asyncAlternatives[].tradeOutputnumberIndicative: priced when the deposit / redemption executes on Plume. No slippage bound applies.
data.asyncAlternatives[].settlementobject
data.asyncAlternatives[].settlement.kindasync-crosschain
data.asyncAlternatives[].settlement.etaSecondsintegerIndicative; null when an operator fulfils it (a redemption request).
data.asyncAlternatives[].settlement.statusUrlstringReplace {signature} with the Solana transaction signature.
data.asyncAlternatives[].settlement.viastring[]
data.asyncAlternatives[].feesobject[]
data.asyncAlternatives[].fees[].assetstring
data.asyncAlternatives[].fees[].amountstringRaw units
data.asyncAlternatives[].fees[].kindstring
data.asyncAlternatives[].notestring
data.asyncAlternatives[].buildErrorobjectThe quote stands but the issuer refused to build (e.g. OWNER_TOKEN_ACCOUNT_NOT_FOUND).
data.asyncAlternatives[].buildError.codestring
data.asyncAlternatives[].buildError.messagestring
data.asyncAlternatives[].txobjectPartially signed by Nest: add the wallet signature, never recompile the message.
data.asyncAlternatives[].tx.chainTypesvm
data.asyncAlternatives[].tx.transactionstringBase64 v0 transaction
data.asyncAlternatives[].tx.lastValidBlockHeightinteger
data.asyncAlternatives[].tx.partiallySignedTrue
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.

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​

Spot swap quote or full build