Meta aggregator

Unsigned transaction on any chain: Chord first, a fallback only when it fails

The same answer as /meta/quote with a taker required: an UNSIGNED transaction, simulated as the taker. Chord never signs and never holds funds.

Send the pair and amount, or the quoteId of a /meta/quote answer from the last 2 minutes. The policy runs again at the current state, so provider can differ from the quote's: compare before you sign.

Before signing

  • approval not null: send token.approve(spender, amount) first. spender is tx.to. With approval.resetFirst: true (USDT on Ethereum, a left-over allowance) send approve(spender, 0) before it.
  • When provider is not chord, tx.to is that aggregator's router. Show the user which provider it is.

Policy

  1. Chord's own router is always asked first, with its normal budget.
  2. A fallback is asked only when Chord fails: the engine timed out, errored or is down; there is no route; Chord refuses the route itself (value guard, taxed token, stale bonding-curve route); the chain's router is not live; or the built transaction fails simulation. A better price elsewhere is not a reason. A user error (unknown token, bad amount) never falls back.
  3. Fallbacks are tried in the chain's order (GET /meta/providers); the first answer that passes every check wins. Per provider 4 s, whole request 9 s, a circuit breaker per provider and chain.

Safety, on every fallback answer

  • The transaction target and the approval spender must be on Chord's allowlist for that provider and chain, and deployed there.
  • minAmountOut comes from your slippage; a provider minimum below it is refused.
  • The value guard of /quote applies: an output worth 30 % less than the input at Chord's prices is refused. An unpriced token gets a security scan (safety); a honeypot is refused.
  • With taker, the transaction is simulated as that wallet and must deliver at least minAmountOut. A fallback transaction that cannot be simulated is never returned.
  • Without taker, a fallback price is shown only after the provider BUILT the route and it was simulated for a placeholder wallet (PRICE_CHECKED); a provider that prices a size but will not build it is skipped. The placeholder's transaction is never returned.
  • An input the simulation cannot supply (a balance that is not a plain storage mapping, e.g. rebasing shares) while the taker does not hold it: HTTP 422 INPUT_NOT_SIMULATABLE — hold the input and ask again.
post/meta/swap

Request

  • Base URL: https://api.getchord.xyz/v1
  • URL: https://api.getchord.xyz/v1/meta/swap
  • Auth: none declared

Request body

chainstring

Chain id or key.

tokenInstring

EVM address, hex, case-insensitive.

tokenOutstring

EVM address, hex, case-insensitive.

amountstring

Amount in the token's smallest unit, as a decimal string. Never a float.

slippageBpsinteger
takerstring required

The wallet that signs and receives.

quoteIdstring

Instead of chain / tokens / amount: the id of a /meta/quote answer (valid 2 minutes).

Response

Sign tx with any wallet library and submit it to the chain in tx.chainId.

chaininteger

Chain id.

tokenInstring

EVM address, hex, case-insensitive.

tokenOutstring

EVM address, hex, case-insensitive.

amountInstring

Amount in the token's smallest unit, as a decimal string. Never a float.

takerstring nullable

The wallet the transaction was built and simulated for; null on a price-only quote.

slippageBpsinteger

The slippage minAmountOut reflects.

providerstring nullable

Who answered: chord (Chord's own router), kyberswap, monorail, lifi, relay. null = no provider has a route.

fallbackReasonstring nullable

null when Chord answered. Otherwise why it did not: no_route, insufficient_liquidity, engine_error, engine_timeout, engine_down, value_guard, taxed_token, route_stale, chain_not_live, build_failed, simulation_failed.

amountOutstring

What the taker receives after every fee, smallest unit of tokenOut. (/quote's outputAmount is before Chord's fee; this is after.)

minAmountOutstring

The minimum the transaction enforces, from the slippage you asked for.

priceImpactPctstring nullable

Percent, when the provider states one.

valueLossPctnumber nullable

Output value against input value at Chord's own prices, percent (negative = worth more). null when Chord has no reliable price for a side: see safety and warnings.

feeBpsinteger

Chord path: Chord's protocol fee on the output. Fallback: the integrator fee Chord added (0 today); the provider's own fees are already inside amountOut.

feeRecipientstring nullable

EVM address, hex, case-insensitive.

warningsstring[]

INSUFFICIENT_BALANCE, UNPRICED, OUTPUT_WRAPPED, NO_ROUTE, and on a price-only fallback PRICE_CHECKED (built and simulated for a placeholder wallet) or UNVERIFIED_PRICE (built, not simulatable) — each followed by a sentence.

quoteIdstring

Pass to POST /meta/swap within 2 minutes.

expiresAtinteger

Unix time, seconds, UTC.

Changes

No recorded changes to this operation across all 1 revision of this API.