{ "openapi": "3.1.0", "info": { "title": "Chord API", "version": "2026-10-05", "summary": "Trade, data and agent endpoints for eight EVM chains (Ethereum 1, Arbitrum One 42161, Base 8453, BNB Chain 56, Avalanche 43114, Monad 143, Arc 5042, Robinhood Chain 4663) and Solana (data and swaps).", "description": "Chord is a non-custodial trading app and on-chain data index. The API has three kinds of endpoint:\n\n- **Trade**: `/quote` finds the best route across every venue on the chain; `/swap` turns it into a transaction you sign yourself. Chord never holds funds or keys.\n- **Read**: every swap on the chain, rolled up by token, venue and hour, from Chord's own index — tokens, launches, holders, top wallets, portfolio PnL, liquidity positions and pools. No key needed. Avalanche, Base, BNB Chain, Arbitrum One and Ethereum have the same rollups under `/chains/{chain}/*`; Solana has its own data family under `/chains/solana/*` (base58 addresses, case-sensitive) and its swaps under `/sol/trade/*`.\n- **Agent**: the analyst (`/ask`) and the streams.\n\nAmounts are decimal strings in the token's smallest unit. Timestamps are Unix seconds unless the field is `updatedAt` (milliseconds). Reads answer anonymous callers at 60 requests a minute per IP; an `X-API-Key` header raises that to your plan. Every non-2xx body is `{ error, message }`.", "contact": { "name": "Chord", "url": "https://getchord.xyz/developer" }, "x-logo": { "url": "https://getchord.xyz/chord/pwa-192x192.png" } }, "servers": [ { "url": "https://api.getchord.xyz/v1", "description": "Production" } ], "tags": [ { "name": "Quote and swap", "description": "Best-route quotes across every venue on the chain, and the unsigned transaction to execute them." }, { "name": "Agents and status", "description": "What an agent starts from: the chain directory (which capability lives on which route, per chain), the hosted MCP server, per-chain health, the public status history, and how much agent traffic each chain sees." }, { "name": "Meta aggregator", "description": "One quote and one unsigned transaction on any Chord chain, for agents. Chord's own router answers first; a third-party aggregator (KyberSwap, Monorail, LI.FI, Relay) only when Chord fails, never for a better price. Every answer names the provider, and a fallback transaction is returned only when its router is on Chord's allowlist and it passed a simulation run as the taker." }, { "name": "Arc data", "description": "Arc (chain 5042): chain totals, every token traded, launches, launchers, holders — from Chord's own rollup and index tables." }, { "name": "Tokens and charts", "description": "Curated lists, candles, trade tapes, windowed stats and logos. Address-keyed routes serve both chains." }, { "name": "Top wallets", "description": "Wallets ranked from the tape by a skill-adjusted score, with routers and bots removed." }, { "name": "Portfolio", "description": "Average-cost PnL, trade history and a daily calendar for any wallet." }, { "name": "Liquidity", "description": "Liquidity: events, pools ranked for providers, positions valued live, LP leaderboard, range planning and backtests, alerts." }, { "name": "Points", "description": "The Chord points program on Arc." }, { "name": "Ask agent", "description": "The analyst agent over the Arc index, its picks and research notes." }, { "name": "Bridge", "description": "Circle CCTP fast transfer to Arc, and LI.FI routes from 60+ chains." }, { "name": "Robinhood Chain data", "description": "Robinhood Chain (chain 4663): chain totals, tokens and tokenized stocks from the rollup tables." }, { "name": "Avalanche, Base, BNB Chain", "description": "Avalanche C-Chain (43114), Base (8453), BNB Chain (56), Arbitrum One (42161) and Ethereum (1): chain totals, the 24-hour token board, prints, one token's tape, venue share and a wallet's PnL, from Chord's own index of every swap on those chains. One set of routes, the chain in the path." }, { "name": "Solana data", "description": "Solana, read-only: chain totals, the 24-hour token board, search, one token's stats, prints, candles and traders, the day's trader board, a wallet's PnL, and liquidity (LP pools, positions, events, LP wallets on Meteora DLMM / DAMM v2, Raydium CLMM and PumpSwap), from Chord's own tape of the swap events of 11 Solana venues (PumpSwap, pump.fun, Meteora, Raydium, Orca). Prop AMMs and order books are not read. Addresses are base58 and case-sensitive; the path segment is the literal `solana`. Read the notes on each operation before comparing these numbers with an all-market source." }, { "name": "Solana swaps", "description": "Solana swaps, open to everyone: every quote builds Chord's own route (Raydium, Orca, Meteora, pump.fun, PumpSwap) and Jupiter's for the wallet, simulates them, and returns the one that leaves the wallet with the most; you sign and send it back." }, { "name": "Backtests", "description": "Bar-close strategy backtests over Chord's stored candles: any Hyperliquid perp, 13 FX pairs and metals. Simulated, nothing is traded." }, { "name": "Streaming", "description": "Server-sent events and the public WebSocket." }, { "name": "Account and health", "description": "Your key, and the service's own health." } ], "paths": { "/quote": { "get": { "tags": [ "Quote and swap" ], "operationId": "getQuote", "summary": "Best route for a swap", "description": "Quotes every venue on the chain in parallel, splits the order across venues when that improves the output, composes a two-hop route through the chain's anchors when no direct pool wins, and returns the best.\n\n**Use it for**: a price before a trade, a route card, an agent deciding whether to buy, a bot comparing venues.\n\n**Notes**\n- Amounts are strings in the token's smallest unit. On Arc the USDC predeploy has 6 decimals, native USDC 18 — send the predeploy address `0x3600…0000` (the zero address is an alias for it on 5042).\n- A quote is a live read of the venues and is good for about 30 seconds. Re-quote before you build if you waited longer.\n- `fast=1` returns a single-hop answer in about 400 ms marked `preliminary`; run the full quote alongside and replace it.\n- `only=` pins one venue and bypasses the routing safety gates — it needs an API key.\n- An empty `routePlan` is a real answer (no route at this size); read `noRouteReason`.", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 5042, 4663, 143, 43114, 8453, 56, 42161, 1 ], "default": 143 }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad · `43114` Avalanche C-Chain · `8453` Base · `56` BNB Chain · `42161` Arbitrum One · `1` Ethereum. Omitted = 143. Always pass it." }, { "name": "inputMint", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "Token you sell. The zero address means the native unit (an alias for the USDC predeploy on Arc; ETH on Robinhood Chain)." }, { "name": "outputMint", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "Token you buy." }, { "name": "amount", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "description": "Input amount, smallest unit." }, { "name": "slippageBps", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 50 }, "description": "Slippage tolerance in basis points; sets `otherAmountThreshold`." }, { "name": "fast", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "1 = progressive first frame (single-hop, ~400 ms, `preliminary: true`)." }, { "name": "only", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z0-9_]+$" }, "description": "Debug: restrict routing to one venue id. Requires `X-API-Key`." } ], "responses": { "200": { "description": "The best route. `routePlan` empty + `outputAmount` \"0\" = no route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" }, "example": { "inputMint": "0x3600000000000000000000000000000000000000", "outputMint": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0", "inputAmount": "5000000", "outputAmount": "465", "otherAmountThreshold": "460", "slippageBps": 100, "priceImpactPct": "92.51", "routePlan": [ { "percent": 100, "swapInfo": { "dex": "uniswap_v4", "pool": "0xdd9da42901118c475e6efb78117100e611c675e2c53bc801c4d2bfdd504b2e8d", "inputMint": "0x3600000000000000000000000000000000000000", "outputMint": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0", "inputAmount": "5000000", "outputAmount": "465", "adapter": "0xd1d86d370f40471B79D9938B27F6ea040EbD6888", "extraData": "0x000000000000000000000000171a4217b86a807a64eb94757db6849fb4bdbaa00000000000000000000000003600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000017700000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000000" } } ], "gasEstimate": "318189", "gasCostUSD": "0", "blockNumber": 21808240, "timeTaken": 0.643, "feeBps": 25, "feeAmount": "1", "feeMint": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0", "feeTier": "meme" } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The routing engine or an upstream did not answer (`ENGINE_ERROR`, `ROUTE_ERROR`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/swap": { "post": { "tags": [ "Quote and swap" ], "operationId": "buildSwap", "summary": "Build an unsigned swap transaction", "description": "Turns a quote into a transaction against the Chord router. You sign it and broadcast it; Chord never sees a key and never holds funds.\n\n**Notes**\n- Send the `/quote` body back unmodified. `chain` must match the quote.\n- For an ERC-20 input, approve the router (`transaction.to`) for at least `inputAmount` first — or run `/swap/simulate` and let it tell you.\n- `slippageBps` is a consistency check only: the signed minimum output is the quote's `otherAmountThreshold`. A different value is refused with `SLIPPAGE_MISMATCH` — re-quote at the slippage you want.\n- On Arc the native sentinel aliases to the USDC predeploy: a \"native\" input is pulled by `transferFrom`, a \"native\" output is delivered as the predeploy, and `value` is always 0.\n- `batch: \"7702\"` is Monad-only (EIP-7702 one-signature approve+swap); it is ignored on every other chain.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteResponse": { "$ref": "#/components/schemas/QuoteResponse" }, "userPublicKey": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Wallet that signs and receives the output." }, "chain": { "type": "integer", "enum": [ 5042, 4663, 143, 43114, 8453, 56, 42161, 1 ], "default": 143, "description": "Must match the quote." }, "slippageBps": { "type": "integer", "minimum": 1, "maximum": 5000, "description": "Optional consistency check — same value the quote was requested with." }, "feeAccount": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Referrer credited with the referral share of the protocol fee." }, "wrapUnwrapMON": { "type": "boolean", "default": true, "description": "Wrap / unwrap the native unit around the swap where the chain has a wrapped native (not Arc)." }, "usePermit2": { "type": "boolean", "default": false }, "batch": { "type": "string", "enum": [ "7702" ] } }, "required": [ "quoteResponse", "userPublicKey" ] }, "example": { "quoteResponse": { "…": "the /v1/quote body" }, "userPublicKey": "0xb145400da27a2497d9fc2cd5621f2bfd37617af4", "chain": 5042 } } } }, "responses": { "200": { "description": "Sign `transaction` with any wallet library and submit it to the chain in `chainId`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction": { "$ref": "#/components/schemas/SwapTx" }, "lastValidBlockHeight": { "type": "integer", "description": "Block after which the quote should be considered stale." }, "batch7702": { "type": "object", "additionalProperties": true, "description": "Monad only — the one-signature approve+swap plan." } } }, "example": { "transaction": { "to": "0x1b1fee89a381e595fe6536b99ba91f3e16e9601a", "data": "0xdc72a437…", "value": "0", "gasLimit": "1500000", "chainId": 5042 }, "lastValidBlockHeight": 21808340 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The routing engine or an upstream did not answer (`ENGINE_ERROR`, `ROUTE_ERROR`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/swap/calldata": { "get": { "tags": [ "Quote and swap" ], "operationId": "swapCalldata", "summary": "Quote and build in one call", "description": "For contracts and bots that call the router directly: routes and encodes in a single request. The output goes to `msg.sender`; the caller approves the router for `tokenIn` and sends the calldata.", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 5042, 4663, 143, 43114, 8453, 56, 42161, 1 ], "default": 143 }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad · `43114` Avalanche C-Chain · `8453` Base · `56` BNB Chain · `42161` Arbitrum One · `1` Ethereum. Omitted = 143." }, { "name": "tokenIn", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "Token the caller approves and sends." }, { "name": "tokenOut", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "Token returned to msg.sender." }, { "name": "amountIn", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "description": "" }, { "name": "slippageBps", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 100 }, "description": "Sets `minOut` on the returned calldata." } ], "responses": { "200": { "description": "Router call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "data": { "type": "string", "description": "" }, "value": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "minOut": { "type": "string", "description": "Minimum output, human units." }, "expectedOut": { "type": "string", "description": "Quoted output, human units." }, "gasLimit": { "type": "string", "description": "" } } }, "example": { "to": "0x1b1fee89a381e595fe6536b99ba91f3e16e9601a", "data": "0x…", "value": "0", "minOut": "0.0942", "expectedOut": "0.0951", "gasLimit": "1000000" } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing at this identity (`NOT_FOUND`, `UNKNOWN_TOKEN`, `NO_ROUTE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The routing engine or an upstream did not answer (`ENGINE_ERROR`, `ROUTE_ERROR`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/swap/simulate": { "post": { "tags": [ "Quote and swap" ], "operationId": "simulateSwap", "summary": "Simulate a built transaction before signing", "description": "`eth_call`s the built calldata from the user's address and estimates gas, so a revert is caught before the wallet opens. Known selectors are decoded (`NotRouter`, a paused Kuru market, allowance and balance errors). An allowance revert is advisory: approve first, then swap.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "enum": [ 5042, 4663, 143, 43114, 8453, 56, 42161, 1 ] }, "from": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "to": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "data": { "type": "string", "description": "Calldata from `/swap`." }, "value": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." } }, "required": [ "from", "to", "data", "value" ] }, "example": { "chain": 5042, "from": "0xb145400da27a2497d9fc2cd5621f2bfd37617af4", "to": "0x1b1fee89a381e595fe6536b99ba91f3e16e9601a", "data": "0xdc72a437…", "value": "0" } } } }, "responses": { "200": { "description": "`ok: true` with the simulated output and gas, or `ok: false` with the decoded revert.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "" }, "amountOut": { "type": [ "string", "null" ], "description": "Simulated output, smallest unit." }, "gas": { "type": [ "integer", "null" ], "description": "Estimated gas units." }, "revert": { "type": "string", "description": "Decoded reason (when `ok` is false)." }, "selector": { "type": [ "string", "null" ], "description": "4-byte error selector." } } }, "example": { "ok": true, "amountOut": "465", "gas": 318189 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/meta/quote": { "get": { "tags": [ "Meta aggregator" ], "operationId": "metaQuote", "summary": "Quote on any chain: Chord first, a fallback only when it fails", "description": "One call that ends in a route you can sign or an honest \"no route anywhere\". Without `taker` it is a price; with `taker` it also returns the unsigned transaction, the approval it needs and a simulation.\n\n**Policy**\n1. Chord's own router is always asked first, with its normal budget.\n2. 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.\n3. 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.\n\n**Safety, on every fallback answer**\n- The transaction target and the approval spender must be on Chord's allowlist for that provider and chain, and deployed there.\n- `minAmountOut` comes from your slippage; a provider minimum below it is refused.\n- 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.\n- 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.\n- 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.\n- 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.\n\n**Notes**\n- `provider: null` with HTTP 200 means every provider looked and none has a route. HTTP 503 `UNAVAILABLE` means nobody could answer right now: retry, do not conclude the pair is untradeable.\n- The answer is good until `expiresAt` (30 s). Quote again before signing if you waited.", "parameters": [ { "name": "chain", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Chain id or key: `143` monad · `4663` robinhood · `5042` arc · `43114` avalanche · `8453` base · `56` bnb · `42161` arbitrum · `1` ethereum." }, { "name": "tokenIn", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "Token you sell. The zero address = the chain's native asset (on Arc it aliases to the USDC predeploy). `inputMint` is accepted too." }, { "name": "tokenOut", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "Token you buy. `outputMint` is accepted too." }, { "name": "amount", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "description": "Input amount, smallest unit." }, { "name": "slippageBps", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 50 }, "description": "Sets `minAmountOut`." }, { "name": "taker", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "The wallet that signs and receives. With it the answer carries `tx`, `approval` and `simulation`. `userPublicKey` is accepted too." } ], "responses": { "200": { "description": "The quote. Read `provider` and `fallbackReason` before anything else.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaQuote" }, "example": { "chain": 8453, "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "tokenOut": "0x4200000000000000000000000000000000000006", "amountIn": "10000000", "taker": "0x00000000000000000000000000000000000c0ffe", "slippageBps": 50, "provider": "chord", "fallbackReason": null, "attempts": [ { "provider": "chord", "status": "ok", "ms": 222, "error": null } ], "amountOut": "3727897844407334", "minAmountOut": "3709258355185298", "priceImpactPct": "0.0000", "valueLossPct": -0.02, "feeBps": 0, "feeRecipient": "0x6c66229675fd9ceda9a9b2ea2bd983b3d8255834", "route": { "venues": [ "aerodrome_slipstream_3" ] }, "tx": { "to": "0x1b1fee89a381e595fe6536b99ba91f3e16e9601a", "data": "0xdc72a437…", "value": "0", "gas": "1000000", "chainId": 8453 }, "approval": { "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "spender": "0x1b1fee89a381e595fe6536b99ba91f3e16e9601a", "amount": "10000000" }, "simulation": { "ok": true, "amountOut": "3727897844407334", "gasUsed": 456590 }, "safety": null, "warnings": [ "INSUFFICIENT_BALANCE: the taker holds less than the input amount; the transaction was simulated with the input supplied." ], "quoteId": "8f722080-92a4-493d-aa16-a06f468a581e", "expiresAt": 1791055797 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request is valid but cannot be served as asked (`INPUT_NOT_SIMULATABLE` on `/meta/*`: a route exists, but the input token cannot be supplied in a simulation and the taker does not hold it — hold the input and ask again).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/meta/swap": { "post": { "tags": [ "Meta aggregator" ], "operationId": "metaSwap", "summary": "Unsigned transaction on any chain: Chord first, a fallback only when it fails", "description": "The same answer as `/meta/quote` with a `taker` required: an UNSIGNED transaction, simulated as the taker. Chord never signs and never holds funds.\n\nSend 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.\n\n**Before signing**\n- `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.\n- When `provider` is not `chord`, `tx.to` is that aggregator's router. Show the user which provider it is.\n\n**Policy**\n1. Chord's own router is always asked first, with its normal budget.\n2. 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.\n3. 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.\n\n**Safety, on every fallback answer**\n- The transaction target and the approval spender must be on Chord's allowlist for that provider and chain, and deployed there.\n- `minAmountOut` comes from your slippage; a provider minimum below it is refused.\n- 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.\n- 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.\n- 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.\n- 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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "description": "Chain id or key." }, "tokenIn": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenOut": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "slippageBps": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 50 }, "taker": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "The wallet that signs and receives." }, "quoteId": { "type": "string", "description": "Instead of chain / tokens / amount: the id of a `/meta/quote` answer (valid 2 minutes)." } }, "required": [ "taker" ] }, "example": { "chain": 8453, "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "tokenOut": "0x4200000000000000000000000000000000000006", "amount": "10000000", "slippageBps": 50, "taker": "0x00000000000000000000000000000000000c0ffe" } } } }, "responses": { "200": { "description": "Sign `tx` with any wallet library and submit it to the chain in `tx.chainId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaQuote" }, "example": { "chain": 8453, "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "tokenOut": "0x4200000000000000000000000000000000000006", "amountIn": "10000000", "taker": "0x00000000000000000000000000000000000c0ffe", "slippageBps": 50, "provider": "chord", "fallbackReason": null, "attempts": [ { "provider": "chord", "status": "ok", "ms": 222, "error": null } ], "amountOut": "3727897844407334", "minAmountOut": "3709258355185298", "priceImpactPct": "0.0000", "valueLossPct": -0.02, "feeBps": 0, "feeRecipient": "0x6c66229675fd9ceda9a9b2ea2bd983b3d8255834", "route": { "venues": [ "aerodrome_slipstream_3" ] }, "tx": { "to": "0x1b1fee89a381e595fe6536b99ba91f3e16e9601a", "data": "0xdc72a437…", "value": "0", "gas": "1000000", "chainId": 8453 }, "approval": { "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "spender": "0x1b1fee89a381e595fe6536b99ba91f3e16e9601a", "amount": "10000000" }, "simulation": { "ok": true, "amountOut": "3727897844407334", "gasUsed": 456590 }, "safety": null, "warnings": [ "INSUFFICIENT_BALANCE: the taker holds less than the input amount; the transaction was simulated with the input supplied." ], "quoteId": "8f722080-92a4-493d-aa16-a06f468a581e", "expiresAt": 1791055797 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No provider has a route for this pair and size (`NO_ROUTE`); the body carries `fallbackReason` and `attempts`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Unknown or expired `quoteId` (`QUOTE_EXPIRED`). Send the full params.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request is valid but cannot be served as asked (`INPUT_NOT_SIMULATABLE` on `/meta/*`: a route exists, but the input token cannot be supplied in a simulation and the taker does not hold it — hold the input and ask again).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/meta/providers": { "get": { "tags": [ "Meta aggregator" ], "operationId": "metaProviders", "summary": "Fallback order and breaker state per chain", "description": "Which aggregators stand behind Chord's router on each chain, in the order they are tried, and whether each one's circuit breaker is closed. `first` is always `chord`.", "responses": { "200": { "description": "Per chain.", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "type": "string", "description": "" }, "chains": { "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "key": { "type": "string", "description": "" }, "first": { "type": "string", "description": "Always `chord`." }, "fallbacks": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "description": "" }, "breaker": { "type": "string", "description": "`closed`, `open` (skipped for up to 60 s after 5 infrastructure failures in 2 minutes) or `half-open` (the next request probes it)." } } } } } } } } }, "example": { "policy": "Chord's router answers first; a fallback is used only when Chord fails, never for a better price.", "chains": [ { "chain": 143, "key": "monad", "first": "chord", "fallbacks": [ { "provider": "kyberswap", "breaker": "closed" }, { "provider": "monorail", "breaker": "closed" }, { "provider": "relay", "breaker": "closed" } ] }, { "chain": 4663, "key": "robinhood", "first": "chord", "fallbacks": [ { "provider": "kyberswap", "breaker": "closed" }, { "provider": "lifi", "breaker": "closed" }, { "provider": "relay", "breaker": "closed" } ] }, { "chain": 5042, "key": "arc", "first": "chord", "fallbacks": [ { "provider": "kyberswap", "breaker": "closed" }, { "provider": "lifi", "breaker": "closed" }, { "provider": "relay", "breaker": "closed" } ] }, { "chain": 43114, "key": "avalanche", "first": "chord", "fallbacks": [ { "provider": "kyberswap", "breaker": "closed" }, { "provider": "lifi", "breaker": "closed" }, { "provider": "relay", "breaker": "closed" } ] }, { "chain": 8453, "key": "base", "first": "chord", "fallbacks": [ { "provider": "kyberswap", "breaker": "closed" }, { "provider": "lifi", "breaker": "closed" }, { "provider": "relay", "breaker": "closed" } ] }, { "chain": 56, "key": "bnb", "first": "chord", "fallbacks": [ { "provider": "kyberswap", "breaker": "closed" }, { "provider": "lifi", "breaker": "closed" }, { "provider": "relay", "breaker": "closed" } ] } ] } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/arc/status": { "get": { "tags": [ "Arc data" ], "operationId": "arcStatus", "summary": "Index freshness and depth", "description": "Is the Arc rollup fresh, how far back it reaches, and the state of the pool index and the holder ledger. Check this before trusting a quiet number.\n\nServed from Chord's rollup and index tables (every swap on Arc summed by hour, token and venue), never from a raw scan — so calls are cheap and every answer carries its coverage. No key needed. `503 NOT_READY` until the rollup has run on the deployment.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "const": 5042 }, "enabled": { "type": "boolean", "description": "" }, "recentAt": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "staleSec": { "type": [ "integer", "null" ], "description": "" }, "floorHour": { "type": [ "integer", "null" ], "description": "" }, "genesisHour": { "type": [ "integer", "null" ], "description": "" }, "backfillComplete": { "type": "boolean", "description": "" }, "index": { "type": [ "object", "null" ], "properties": { "pools": { "type": "integer", "description": "V2 + V3 pools indexed." }, "v4Pools": { "type": "integer", "description": "" }, "cursor": { "type": "integer", "description": "Last block the pool crawler processed." }, "genesis": { "type": "boolean", "description": "Pool discovery reached genesis." } } }, "holders": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Holder-ledger lane state (tracked tokens, completed backfills, cursors)." }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "enabled": true, "recentAt": 1789891429, "staleSec": 423, "floorHour": 1780520400, "genesisHour": 1780520400, "backfillComplete": true, "index": { "pools": 30528, "v4Pools": 190394, "cursor": 21808222, "genesis": true }, "holders": { "enabled": true, "tracked": 1000, "complete": 225, "forwardCursor": 21808247, "from": 21273472, "backfilling": "0x3600000000000000000000000000000000000000" }, "updatedAt": 1789891853280 } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/arc/overview": { "get": { "tags": [ "Arc data" ], "operationId": "arcOverview", "summary": "Chain totals", "description": "Last 24 hours (volume, swaps, tokens), venue share, 24 hourly buckets and up to 30 daily rows. The numbers on Chord's landing page come from this call.\n\nServed from Chord's rollup and index tables (every swap on Arc summed by hour, token and venue), never from a raw scan — so calls are cheap and every answer carries its coverage. No key needed. `503 NOT_READY` until the rollup has run on the deployment.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "const": 5042 }, "last24h": { "type": "object", "properties": { "volUsd": { "type": "number", "description": "" }, "swaps": { "type": "integer", "description": "" }, "tokens": { "type": "integer", "description": "" }, "sinceHour": { "type": "integer", "description": "" } } }, "venues24h": { "type": "array", "items": { "type": "object", "properties": { "dex": { "type": "string", "description": "" }, "volUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "tokens": { "type": "integer", "description": "" }, "sharePct": { "type": "number", "description": "" } } }, "description": "Biggest first." }, "hourly24": { "type": "array", "items": { "type": "object", "properties": { "hour": { "type": "integer", "description": "" }, "volUsd": { "type": "number", "description": "" }, "swaps": { "type": "integer", "description": "" } } }, "description": "Oldest first." }, "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "integer", "description": "" }, "swaps": { "type": "integer", "description": "" }, "volUsd": { "type": "number", "description": "" }, "tokens": { "type": "integer", "description": "" }, "wallets": { "type": "integer", "description": "Attributed wallets only." }, "venues": { "type": "integer", "description": "" } } }, "description": "Up to 30 days." }, "coverage": { "$ref": "#/components/schemas/Coverage" }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "last24h": { "volUsd": 70377594.2336901, "swaps": 788926, "tokens": 6288, "sinceHour": 1789808400 }, "venues24h": [ { "dex": "uniswap_v4", "volUsd": 55014882.201828234, "trades": 683313, "tokens": 4059, "sharePct": 78.17101849084284 }, { "dex": "uniswap_v3", "volUsd": 12910961.69548591, "trades": 91957, "tokens": 2163, "sharePct": 18.345272861437724 } ], "hourly24": [ { "hour": 1789808400, "volUsd": 3234644.52212066, "swaps": 50225 }, { "hour": 1789812000, "volUsd": 2223745.3392903497, "swaps": 36071 } ], "daily": [ { "day": 1787356800, "swaps": 5712, "volUsd": 609934.6437347728, "tokens": 292, "wallets": 768, "venues": 4 }, { "day": 1787443200, "swaps": 3057, "volUsd": 241890.2647458107, "tokens": 274, "wallets": 508, "venues": 6 } ], "coverage": { "recentAt": 1789891429, "stale": false, "floorHour": 1780520400, "genesisHour": 1780520400, "backfillComplete": true }, "updatedAt": 1789891764243 } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/arc/venues": { "get": { "tags": [ "Arc data" ], "operationId": "arcVenues", "summary": "Venue share over a window", "description": "Per-venue volume, trades and share for 1–180 days, with a daily series per venue. Venue ids are listed under Resources → Venue ids.\n\nServed from Chord's rollup and index tables (every swap on Arc summed by hour, token and venue), never from a raw scan — so calls are cheap and every answer carries its coverage. No key needed. `503 NOT_READY` until the rollup has run on the deployment.", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 180, "default": 30 }, "description": "Window length." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "const": 5042 }, "days": { "type": "integer", "description": "" }, "since": { "type": "integer", "description": "Unix time, seconds, UTC." }, "venues": { "type": "array", "items": { "type": "object", "properties": { "dex": { "type": "string", "description": "" }, "volUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "sharePct": { "type": "number", "description": "" }, "series": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "integer", "description": "" }, "volUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "tokens": { "type": "integer", "description": "" } } } } } } }, "totals": { "type": "object", "properties": { "volUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" } } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "days": 2, "since": 1789776000, "venues": [ { "dex": "uniswap_v4", "volUsd": 68035852.94572023, "trades": 984421, "sharePct": 75.67924527197266, "series": [ { "day": 1789776000, "volUsd": 58377642.50907503, "trades": 798150, "tokens": 4499 }, { "day": 1789862400, "volUsd": 9658210.4366452, "trades": 186271, "tokens": 1536 } ] }, { "dex": "uniswap_v3", "volUsd": 18354272.62782195, "trades": 133374, "sharePct": 20.41625760314611, "series": [ { "day": 1789776000, "volUsd": 14284128.68933594, "trades": 103080, "tokens": 2418 }, { "day": 1789862400, "volUsd": 4070143.9384860075, "trades": 30294, "tokens": 728 } ] } ], "totals": { "volUsd": 89900279.3978931, "trades": 1135137 }, "updatedAt": 1789891853672 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/arc/tokens": { "get": { "tags": [ "Arc data" ], "operationId": "arcTokens", "summary": "Every token traded in the last 24 hours", "description": "The Markets board: price, change, volume split, trade counts, attributed traders, market cap, pool counts per venue and honesty flags for every token that traded on Arc in the last 24 hours — listed or not. Rows flagged `wash` or `impostor` sort below clean rows.\n\n**Use it for**: a markets table, a screener, \"what is moving on Arc\". For a single token use `/arc/token/{address}`; for search use `/arc/tokens/search`.\n\nServed from Chord's rollup and index tables (every swap on Arc summed by hour, token and venue), never from a raw scan — so calls are cheap and every answer carries its coverage. No key needed. `503 NOT_READY` until the rollup has run on the deployment.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 20000, "default": 0 }, "description": "" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "volume", "trades", "traders", "change", "mcap" ], "default": "volume" }, "description": "Descending." }, { "name": "includeUnlisted", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 }, "description": "1 = include tokens without curated metadata or a logo." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "const": 5042 }, "sinceHour": { "type": "integer", "description": "" }, "tradersSince": { "type": "integer", "description": "Start of the trader-count window." }, "sort": { "type": "string", "description": "" }, "offset": { "type": "integer", "description": "" }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/ArcTokenRow" } }, "total": { "type": "integer", "description": "" }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "sinceHour": 1789808400, "tradersSince": 1789776000, "sort": "volume", "offset": 0, "tokens": [ { "address": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0", "symbol": "cirBTC", "name": "cirBTC", "decimals": 8, "logoURI": "https://api.getchord.xyz/v1/logo/5042/0x171a4217b86a807a64eb94757db6849fb4bdbaa0", "tags": [], "listed": true, "priceUsd": 80423.22925858323, "change24hPct": -1.0826513878648192, "volume24h": 5689551.810770997, "buyVolume24h": 2765666.247710997, "sellVolume24h": 2923885.56306, "trades24h": 19472, "buys24h": 10554, "sells24h": 8918, "traders": 3203, "lastTradeTs": 1789891845, "totalSupply": 336.81495614, "marketCapUsd": 27087746.435366876, "pools": { "v3": 21, "v2": 5, "v4": 483, "byDex": { "uniswap_v3": 10, "v2fork_a2448256": 1, "slipstream_fork": 2, "v3fork_5bfbceb7": 6, "v3fork_bb74f231": 2, "v2fork_49aa1c63": 2, "v3fork_711492df": 1, "sushi_v2": 2, "uniswap_v4": 483 } }, "routable": true, "logoUriRaw": "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/bitcoin/info/logo.png" }, { "address": "0xece5ca8bf9220718e5727754026757512212cb3c", "symbol": "ARGUS", "name": "Argus", "decimals": 18, "logoURI": "https://api.getchord.xyz/v1/logo/5042/0xece5ca8bf9220718e5727754026757512212cb3c", "tags": [], "listed": true, "priceUsd": 0.01923385111168061, "change24hPct": 12.687321807963436, "volume24h": 4051551.451917998, "buyVolume24h": 2089331.6579039998, "sellVolume24h": 1962219.7940139996, "trades24h": 25479, "buys24h": 13716, "sells24h": 11763, "traders": 4549, "lastTradeTs": 1789891399, "totalSupply": 1000000000, "marketCapUsd": 19233851.11168061, "pools": { "v3": 15, "v2": 5, "v4": 1141, "byDex": { "uniswap_v3": 12, "v2fork_e64d552a": 1, "v2fork_a1a044ff": 1, "v3fork_cae668d0": 1, "uniswap_v2": 1, "v3fork_aa5865dc": 1, "synthra_v3": 1, "sushi_v2": 2, "uniswap_v4": 1141 } }, "routable": true, "logoUriRaw": "https://coin-images.coingecko.com/coins/images/102178392/large/argus-token.png?1789463380" } ], "total": 1528, "updatedAt": 1789891853851 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/arc/tokens/search": { "get": { "tags": [ "Arc data" ], "operationId": "arcSearch", "summary": "Search tokens", "description": "Symbol, name or address over every token traded in the last 24 hours. Exact symbol first, then prefix, then name, then substring; listed tokens and volume break ties so the real ARGUS outranks a same-named copy. A pasted contract address always returns that token, even with no 24-hour row. `coverage` says how many tokens have a resolved name yet (about a minute after a boot).", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Symbol, name or address fragment." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "const": 5042 }, "q": { "type": "string", "description": "" }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/ArcTokenRow" } }, "total": { "type": "integer", "description": "" }, "coverage": { "type": "object", "properties": { "resolved": { "type": "integer", "description": "" }, "total": { "type": "integer", "description": "" } } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "q": "argus", "tokens": [ { "address": "0xece5ca8bf9220718e5727754026757512212cb3c", "symbol": "ARGUS", "name": "Argus", "decimals": 18, "logoURI": "https://api.getchord.xyz/v1/logo/5042/0xece5ca8bf9220718e5727754026757512212cb3c", "tags": [], "listed": true, "priceUsd": 0.018829227933149367, "change24hPct": 10.31671479507974, "volume24h": 4045502.7263479983, "buyVolume24h": 2085285.1237909999, "sellVolume24h": 1960217.6025569995, "trades24h": 25431, "buys24h": 13691, "sells24h": 11740, "traders": 4548, "lastTradeTs": 1789890980, "totalSupply": null, "marketCapUsd": null, "pools": { "v3": 15, "v2": 5, "v4": 1141, "byDex": { "uniswap_v3": 12, "v2fork_e64d552a": 1, "v2fork_a1a044ff": 1, "v3fork_cae668d0": 1, "uniswap_v2": 1, "v3fork_aa5865dc": 1, "synthra_v3": 1, "sushi_v2": 2, "uniswap_v4": 1141 } }, "routable": true, "logoUriRaw": "https://coin-images.coingecko.com/coins/images/102178392/large/argus-token.png?1789463380" } ], "total": 1, "coverage": { "resolved": 240, "total": 6270 }, "updatedAt": 1789891854005 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/arc/trending": { "get": { "tags": [ "Arc data" ], "operationId": "arcTrending", "summary": "Movers of the last two hours", "description": "Tokens scored on volume and trade acceleration over the last two hours, from the hourly rollup. Each row is a full token row plus the score and its inputs.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "const": 5042 }, "window": { "type": "string", "const": "2h" }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/ArcTrendingRow" } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "window": "2h", "tokens": [ { "address": "0xc1347b8f2b79af2f150d26f350eb974cd7dab6f3", "symbol": "ARK", "name": "Ark", "decimals": 18, "logoURI": "https://api.getchord.xyz/v1/logo/5042/0xc1347b8f2b79af2f150d26f350eb974cd7dab6f3", "tags": [], "listed": true, "priceUsd": 0.000040595162215532016, "change24hPct": 293.1545690698809, "volume24h": 22263.892306000005, "buyVolume24h": 14913.083264000003, "sellVolume24h": 7350.809042000001, "trades24h": 443, "buys24h": 305, "sells24h": 138, "traders": 186, "lastTradeTs": 1789891841, "totalSupply": 1000000000, "marketCapUsd": 40595.162215532015, "pools": { "v3": 1, "v2": 0, "v4": 4, "byDex": { "uniswap_v3": 1, "uniswap_v4": 4 } }, "routable": true, "score": 14.783, "volNow": 17096.819990000004, "tradesNow": 328, "change1hPct": 16.748692419251164, "momentum": 33.1, "logoUriRaw": "https://ark-ai.xyz/api/uploads/578af1067cda7e6bd593deff82c2eb46.jpg" }, { "address": "0x11435e6c80944f8d8a5f34c3fabd5dd06e7c7367", "symbol": "MCAT", "name": "Stealth Cat", "decimals": 18, "logoURI": "https://api.getchord.xyz/v1/logo/5042/0x11435e6c80944f8d8a5f34c3fabd5dd06e7c7367", "tags": [], "listed": true, "priceUsd": 0.0015085540687515264, "change24hPct": 302.92128960120704, "volume24h": 44245.77249448278, "buyVolume24h": 26326.794866251035, "sellVolume24h": 17918.97762823173, "trades24h": 124, "buys24h": 74, "sells24h": 50, "traders": 38, "lastTradeTs": 1789887925, "totalSupply": 1000000000, "marketCapUsd": 1508554.0687515265, "pools": { "v3": 0, "v2": 0, "v4": 1, "byDex": { "uniswap_v4": 1 } }, "routable": false, "score": 14.154, "volNow": 43073.29349448278, "tradesNow": 119, "change1hPct": 302.92128960120704, "momentum": 18.4, "logoUriRaw": "https://ipfs.filebase.io/ipfs/QmcQFUJagLR9nUss299zLcy5HM3AKyUuNuKf5uFieitRNm" } ], "updatedAt": 1789891854247 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/arc/graduated": { "get": { "tags": [ "Arc data" ], "operationId": "arcGraduated", "summary": "New launches", "description": "Tokens whose first pool on Arc was created inside the window, routable by the engine today and screened: impostor symbols, launch farms (one creator, many pools), no-sell tokens and too few traders are removed and counted in `screened`. Newest first, with the launcher named where the registry knows it.\n\n**Use it for**: a \"new pairs\" feed, launch forensics, an agent watching launches.", "parameters": [ { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 168, "default": 48 }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "const": 5042 }, "hours": { "type": "integer", "description": "" }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/ArcGraduatedRow" } }, "total": { "type": "integer", "description": "" }, "screened": { "type": "object", "properties": { "not_routable": { "type": "integer", "description": "" }, "impostor": { "type": "integer", "description": "" }, "no_sells": { "type": "integer", "description": "" }, "few_traders": { "type": "integer", "description": "" }, "serial_creator": { "type": "integer", "description": "" }, "no_trades": { "type": "integer", "description": "" }, "no_symbol": { "type": "integer", "description": "" } }, "description": "How many launches each screen removed." }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "hours": 48, "tokens": [ { "address": "0xf31599ae7a1a2c7e3d99f2bf307c44a71196e987", "symbol": "DePIN", "name": "X DePIN", "decimals": 18, "logoURI": null, "tags": [], "listed": false, "priceUsd": 0.000011092869541991106, "change24hPct": null, "volume24h": 55.392897000000005, "buyVolume24h": 55.392897000000005, "sellVolume24h": 0, "trades24h": 2, "buys24h": 2, "sells24h": 0, "traders": 3, "lastTradeTs": 1789891653, "totalSupply": 1000000000, "marketCapUsd": 11092.869541991106, "pools": { "v3": 0, "v2": 1, "v4": 0, "byDex": { "uniswap_v2": 1 } }, "routable": true, "launchedAt": 1789891314, "launcher": "0x89e5db8b5aa49aa85ac63f691524311aeb649eba", "creator": "0xd4bd5a99286f728f9529dc8a1fc8b1c702c04497", "ageSec": 540, "launcherName": null }, { "address": "0xa210789b8b0666afa2d4ed00cf701083a2d72c52", "symbol": "RWA", "name": "X RWA", "decimals": 18, "logoURI": null, "tags": [], "listed": false, "priceUsd": 0.000011336625606769674, "change24hPct": null, "volume24h": 430.557449, "buyVolume24h": 430.557449, "sellVolume24h": 0, "trades24h": 17, "buys24h": 17, "sells24h": 0, "traders": 17, "lastTradeTs": 1789891140, "totalSupply": 1000000000, "marketCapUsd": 11336.625606769674, "pools": { "v3": 0, "v2": 1, "v4": 0, "byDex": { "uniswap_v2": 1 } }, "routable": true, "launchedAt": 1789890414, "launcher": "0x89e5db8b5aa49aa85ac63f691524311aeb649eba", "creator": "0xd4bd5a99286f728f9529dc8a1fc8b1c702c04497", "ageSec": 1440, "launcherName": null } ], "total": 85, "screened": { "not_routable": 2614, "impostor": 4, "no_sells": 13, "few_traders": 68, "serial_creator": 1615, "no_trades": 23098, "no_symbol": 0 }, "updatedAt": 1789891854594 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/arc/launchers": { "get": { "tags": [ "Arc data" ], "operationId": "arcLaunchers", "summary": "Who is creating pools", "description": "Launcher contracts on Arc (Uniswap V4 direct, Uniswap Liquidity Launcher, aka.fun, Argus, Minara.fun, Rapid Launch, …): the pool shapes each one creates, pools per hour and day, distinct creators, and 24-hour tape stats over the pools it created. The Launchpads section lists the named ones.", "parameters": [ { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 168, "default": 24 }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "const": 5042 }, "hours": { "type": "integer", "description": "" }, "launchers": { "type": "array", "items": { "$ref": "#/components/schemas/LauncherStat" } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "hours": 24, "launchers": [ { "launcher": "0x8366a39cc670b4001a1121b8f6a443a643e40951", "name": "Uniswap V4 PoolManager (direct)", "site": "https://app.uniswap.org", "logo": "/launchers/uniswap.png", "kinds": [ "v4" ], "shapes": [ { "hooks": "0x4d850668513130fda0dd37b9a905b5e393ede844", "fee": 0, "tickSpacing": 60, "pools": 3 }, { "hooks": "0x0000000000000000000000000000000000000000", "fee": 3000, "tickSpacing": 60, "pools": 3 } ], "pools1h": 4, "pools24h": 66, "creators24h": 56, "firstSeen": 1789474488, "lastSeen": 1789891301, "swaps24h": 12880, "volume24h": 24433932.86648278, "wallets24h": 649, "activePools24h": 96 }, { "launcher": "0x6049c9a0e26405c0985f9e3685c87d0ae917f82b", "name": "Uniswap Liquidity Launcher", "site": "https://github.com/Uniswap/sdks", "logo": "/launchers/uniswap.png", "kinds": [ "v4" ], "shapes": [ { "hooks": "0x0000000000000000000000000000000000000000", "fee": 10000, "tickSpacing": 200, "pools": 330 }, { "hooks": "0x0000000000000000000000000000000000000000", "fee": 2500, "tickSpacing": 50, "pools": 295 } ], "pools1h": 35, "pools24h": 2030, "creators24h": 935, "firstSeen": 1789481791, "lastSeen": 1789891349, "swaps24h": 431537, "volume24h": 18499363.187061056, "wallets24h": 5773, "activePools24h": 2065 } ], "updatedAt": 1789891854880 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/arc/attention": { "get": { "tags": [ "Arc data" ], "operationId": "arcAttention", "summary": "What people on Chord are looking at", "description": "Tokens ranked by attention on Chord itself — searches, token-page views, Ask questions and watchlist adds — over 1–7 days. A demand signal, not a price signal.", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 7, "default": 1 }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "const": 5042 }, "days": { "type": "integer", "description": "" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "score": { "type": "number", "description": "" }, "ask": { "type": "integer", "description": "" }, "search": { "type": "integer", "description": "" }, "view": { "type": "integer", "description": "" }, "watch": { "type": "integer", "description": "" } } } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "days": 1, "rows": [ { "token": "0xece5ca8bf9220718e5727754026757512212cb3c", "score": 8, "ask": 1, "search": 2, "view": 3, "watch": 0 }, { "token": "0x972b159ca91baec0ec88f2c114cf1d7aa5db240e", "score": 6, "ask": 0, "search": 0, "view": 6, "watch": 0 } ], "updatedAt": 1789891855038 } } } } } } }, "/arc/token/{address}": { "get": { "tags": [ "Arc data" ], "operationId": "arcToken", "summary": "One token: hourly tape and venue split", "description": "The token row plus an hourly series (1–720 hours) and the venue split for the window. Feeds Chord's token page header, volume bars and venue table. A token with no 24-hour row comes back as `{ address, listed: false }`.", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 720, "default": 168 }, "description": "Hourly buckets to return." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "const": 5042 }, "token": { "oneOf": [ { "$ref": "#/components/schemas/ArcTokenRow" }, { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "listed": { "type": "boolean", "const": false } } } ] }, "hours": { "type": "integer", "description": "" }, "series": { "type": "array", "items": { "type": "object", "properties": { "hour": { "type": "integer", "description": "" }, "volUsd": { "type": "number", "description": "" }, "buyUsd": { "type": "number", "description": "" }, "sellUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "buys": { "type": "integer", "description": "" }, "sells": { "type": "integer", "description": "" }, "priceLast": { "type": [ "number", "null" ], "description": "" } } }, "description": "Oldest first." }, "byDex": { "type": "array", "items": { "type": "object", "properties": { "dex": { "type": "string", "description": "" }, "volUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "sharePct": { "type": "number", "description": "" } } } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "token": { "address": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0", "symbol": "cirBTC", "name": "cirBTC", "decimals": 8, "logoURI": "https://api.getchord.xyz/v1/logo/5042/0x171a4217b86a807a64eb94757db6849fb4bdbaa0", "tags": [], "listed": true, "priceUsd": 80423.22925858323, "change24hPct": -1.0826513878648192, "volume24h": 5689551.810770997, "buyVolume24h": 2765666.247710997, "sellVolume24h": 2923885.56306, "trades24h": 19472, "buys24h": 10554, "sells24h": 8918, "traders": 3203, "lastTradeTs": 1789891845, "totalSupply": 336.81495614, "marketCapUsd": 27087746.435366876, "pools": { "v3": 21, "v2": 5, "v4": 483, "byDex": { "uniswap_v3": 10, "v2fork_a2448256": 1, "slipstream_fork": 2, "v3fork_5bfbceb7": 6, "v3fork_bb74f231": 2, "v2fork_49aa1c63": 2, "v3fork_711492df": 1, "sushi_v2": 2, "uniswap_v4": 483 } }, "routable": true, "logoUriRaw": "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/bitcoin/info/logo.png" }, "hours": 2, "series": [ { "hour": 1789887600, "volUsd": 109750.71408699999, "buyUsd": 59532.95500899996, "sellUsd": 50217.759078, "trades": 465, "buys": 247, "sells": 218, "priceLast": 80315.09208021293 }, { "hour": 1789891200, "volUsd": 14523.166291000001, "buyUsd": 13047.791779000001, "sellUsd": 1475.374512, "trades": 32, "buys": 23, "sells": 9, "priceLast": 80404.02465976504 } ], "byDex": [ { "dex": "uniswap_v3", "volUsd": 100905.00920399999, "trades": 460, "sharePct": 81.1956695140446 }, { "dex": "slipstream_fork", "volUsd": 23247.566194, "trades": 28, "sharePct": 18.706719483843752 } ], "updatedAt": 1789891855212 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/arc/token/{address}/pools": { "get": { "tags": [ "Arc data" ], "operationId": "arcTokenPools", "summary": "Every indexed pool for a token", "description": "V2 pairs, V3 pools and V4 pool ids (with hooks) that hold the token, with the creation block. For LP-oriented ranking use `/lp/token/{address}/pools`.", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "const": 5042 }, "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "pools": { "type": "array", "items": { "type": "object", "properties": { "pool": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "dex": { "type": "string", "description": "" }, "kind": { "type": "string", "enum": [ "clmm", "v2", "v4" ] }, "token0": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "token1": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "fee": { "type": [ "integer", "null" ], "description": "Fee in pips (100 = 0.01%)." }, "hooks": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "createdBlock": { "type": "integer", "description": "" } } } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "token": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0", "pools": [ { "pool": "0x82916bee18fcef517b26c72d7cb5f13694e1db41", "dex": "uniswap_v3", "kind": "clmm", "token0": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0", "token1": "0x3600000000000000000000000000000000000000", "fee": 100, "createdBlock": 21076890 }, { "pool": "0xecd988913031a292bcf0e4e07ccd5815c8969a48", "dex": "uniswap_v3", "kind": "clmm", "token0": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0", "token1": "0x3600000000000000000000000000000000000000", "fee": 3000, "createdBlock": 21081300 } ], "updatedAt": 1789891855402 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/arc/token/{address}/holders": { "get": { "tags": [ "Arc data" ], "operationId": "arcTokenHolders", "summary": "Holder ledger", "description": "Top balances from Chord's own Transfer-log ledger, each tagged wallet / pool / burn, with the holder count, the share of supply outside pools and burn sinks, and concentration (top 1 / 5 / 10 / 20 / 50 / 100). A token the ledger does not track yet is pinned for tracking and answers `503 HOLDERS_PENDING` — retry in a few minutes. A tracked token whose backfill has not reached its creation block answers 200 with `complete: false` (never a guess from the tape).", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Top rows." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "const": 5042 }, "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tracked": { "type": "boolean", "description": "" }, "complete": { "type": "boolean", "description": "Backfill reached the creation block — balances are the full ledger." }, "coverage": { "type": "object", "properties": { "addedBlock": { "type": [ "integer", "null" ], "description": "" }, "floorBlock": { "type": [ "integer", "null" ], "description": "" }, "backfillCursor": { "type": [ "integer", "null" ], "description": "" }, "forwardCursor": { "type": [ "integer", "null" ], "description": "" }, "logs": { "type": "integer", "description": "" } } }, "decimals": { "type": [ "integer", "null" ], "description": "" }, "totalSupply": { "type": [ "string", "null" ], "description": "Smallest unit." }, "holders": { "type": "integer", "description": "" }, "heldByWalletsPct": { "type": [ "number", "null" ], "description": "" }, "concentration": { "type": [ "object", "null" ], "properties": { "top1": { "type": "number", "description": "" }, "top5": { "type": "number", "description": "" }, "top10": { "type": "number", "description": "" }, "top20": { "type": "number", "description": "" }, "top50": { "type": "number", "description": "" }, "top100": { "type": "number", "description": "" } } }, "top": { "type": "array", "items": { "type": "object", "properties": { "holder": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "balance": { "type": "string", "description": "Smallest unit." }, "amount": { "type": [ "number", "null" ], "description": "Whole tokens." }, "sharePct": { "type": [ "number", "null" ], "description": "" }, "kind": { "type": "string", "enum": [ "wallet", "pool", "burn" ] } } } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "token": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0", "tracked": true, "complete": true, "coverage": { "addedBlock": 21273471, "floorBlock": 560194, "backfillCursor": 560194, "forwardCursor": 21808247, "logs": 68037 }, "decimals": 8, "totalSupply": "33681495614", "holders": 2599, "heldByWalletsPct": 96.0477, "concentration": { "top1": 63.64, "top5": 90.91, "top10": 90.91, "top20": 90.91, "top50": 90.91, "top100": 90.91 }, "top": [ { "holder": "0x34cd04070dd72b14e241112f6d83812df5af7fcd", "balance": "21451899028", "amount": 214.51899, "sharePct": 63.6904, "kind": "wallet" }, { "holder": "0x82916bee18fcef517b26c72d7cb5f13694e1db41", "balance": "6776124246", "amount": 67.761242, "sharePct": 20.1182, "kind": "pool" } ], "updatedAt": 1789891855690 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/arc/token/{address}/trades": { "get": { "tags": [ "Arc data" ], "operationId": "arcTokenTrades", "summary": "Latest prints", "description": "The last N swaps of one token straight from Chord's own Arc tape (newest first): venue, side, size, USD, price, wallet (`null` until resolved) and pool. Bounded and index-served — the mobile token page's Feed tab.", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Newest rows." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "const": 5042 }, "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "trades": { "type": "array", "items": { "type": "object", "properties": { "tx": { "type": "string", "description": "" }, "logIndex": { "type": "integer", "description": "" }, "dex": { "type": "string", "description": "" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "tokenAmt": { "type": "number", "description": "Whole tokens." }, "usd": { "type": "number", "description": "" }, "priceUsd": { "type": "number", "description": "" }, "ts": { "type": "integer", "description": "Unix time, seconds, UTC." }, "wallet": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "pool": { "type": "string", "description": "Pool address or V4 poolId." } } } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "token": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0", "trades": [ { "tx": "0xbebd037b84ae0fba9229fb3e01f983833cbd637983ba254d4dba71ddad861764", "logIndex": 22, "dex": "uniswap_v3", "side": "buy", "tokenAmt": 0.00000843, "usd": 0.70542, "priceUsd": 83679.71530249111, "ts": 1790709599, "wallet": "0x7fe73969faf9d867ac49add1860bc121ff199272", "pool": "0x82916bee18fcef517b26c72d7cb5f13694e1db41" }, { "tx": "0xbdd5f399dd4ead2281042560db54dbfa13c6b44c4ed873baad4daea84dfed472", "logIndex": 3, "dex": "uniswap_v3", "side": "buy", "tokenAmt": 0.003, "usd": 250.846064, "priceUsd": 83615.35466666667, "ts": 1790709590, "wallet": "0xee93f91e457522d89ee19c2affba87352c365465", "pool": "0x82916bee18fcef517b26c72d7cb5f13694e1db41" } ], "updatedAt": 1790709635583 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tokens": { "get": { "tags": [ "Tokens and charts" ], "operationId": "listTokens", "summary": "Curated token list", "description": "Metadata for the tokens Chord routes and labels: address, symbol, name, decimals, logo, tags. On Arc the list leads with the USDC predeploy (the gas token's ERC-20 face) and EURC; on Robinhood Chain with ETH, WETH, USDG and every tokenized stock. Read `decimals` here instead of assuming 18.", "parameters": [ { "name": "chain", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 5042, 4663, 143, 43114, 8453, 56, 42161, 1 ], "default": 143 }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad · `43114` Avalanche C-Chain · `8453` Base · `56` BNB Chain · `42161` Arbitrum One · `1` Ethereum. Omitted = 143." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "symbol": { "type": "string", "description": "" }, "name": { "type": "string", "description": "" }, "decimals": { "type": "integer", "description": "" }, "logoURI": { "type": [ "string", "null" ], "description": "" }, "logoUriRaw": { "type": [ "string", "null" ], "description": "" }, "verified": { "type": "boolean", "description": "" }, "tags": { "type": "array", "items": { "type": "string" } }, "liquidityUsd": { "type": [ "number", "null" ], "description": "" } } } } } }, "example": { "tokens": [ { "address": "0x3600000000000000000000000000000000000000", "symbol": "USDC", "name": "USD Coin", "decimals": 6, "logoURI": "https://api.nullterminal.xyz/v1/logo/5042/0x3600000000000000000000000000000000000000", "verified": true, "tags": [ "stablecoin" ], "logoUriRaw": "https://assets.coingecko.com/coins/images/6319/small/usdc.png" }, { "address": "0xbef5f6d51cb62b58e6a8f77868681825c6fe21c1", "symbol": "EURC", "name": "Euro Coin", "decimals": 6, "logoURI": "https://api.nullterminal.xyz/v1/logo/5042/0xbef5f6d51cb62b58e6a8f77868681825c6fe21c1", "verified": true, "tags": [ "stablecoin", "fx" ], "logoUriRaw": "https://assets.coingecko.com/coins/images/26045/small/euro.png" } ] } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tokens/market": { "get": { "tags": [ "Tokens and charts" ], "operationId": "marketMap", "summary": "Price map", "description": "Price, 24-hour change, volume and trade count for every priced token in Chord's index of the chain (thousands of rows, not just the curated list), in one call, keyed by lower-cased address.\n\n- `4663` Robinhood Chain: every row also carries a 24-point hourly `spark` and `liquidityUsd` where known; the answer has `updatedAt`, the time the live overlay was applied.\n- `5042` Arc: from the Arc hourly rollup. `change24h` and `liquidityUsd` appear only when known; no `spark`, no `updatedAt`.\n\nFor names, logos and honesty flags use `/arc/tokens` or `/rh/tokens`. Always pass `chain`: omitted, it answers for Monad.", "parameters": [ { "name": "chain", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 4663, 5042 ] }, "description": "Chain id: `4663` Robinhood Chain · `5042` Arc." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "market": { "type": "object", "properties": {}, "description": "address → market row", "additionalProperties": { "type": "object", "properties": { "priceUsd": { "type": "number", "description": "" }, "change24h": { "type": "number", "description": "Absent when there is no price 24 hours ago." }, "volume24h": { "type": "number", "description": "Includes trades the hourly rollup has not counted yet (4663)." }, "txns24h": { "type": "integer", "description": "" }, "liquidityUsd": { "type": "number", "description": "Absent when unknown." }, "spark": { "type": "array", "items": { "type": "number" }, "description": "4663 only: 24 hourly closes." } } } }, "updatedAt": { "type": "integer", "description": "4663 only. Server time (ms) the live overlay was applied; compare with a WebSocket `prices` frame's `at`." } } }, "example": { "market": { "0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec": { "priceUsd": 220.97, "change24h": -0.71, "volume24h": 34504046, "txns24h": 103172, "spark": [ 221.4, 221.1, 220.9 ] } }, "updatedAt": 1790708400000 } } } } } } }, "/tokens/search": { "get": { "tags": [ "Tokens and charts" ], "operationId": "searchTokens", "summary": "Search tokens on a chain", "description": "Symbol, name or address. What it searches depends on `chain`:\n\n- `4663` Robinhood Chain: the curated list (`verified: true`, stocks tagged `stock`) plus tokens that traded in the last 24 hours and are not on it (`verified: false`, no logo).\n- `5042` Arc: every token traded in the last 24 hours, the same index as `/arc/tokens/search`. `verified` is true for tokens on the curated Arc list.\n- `43114` / `8453` / `56` / `42161` / `1`: that chain's token list, all `verified: true`. A chain that is not public yet answers `404 CHAIN_NOT_PUBLIC` unless the request carries an `X-API-Key`.\n- no `chain`, or `143`: Monad off-list discovery. Tokens found through DexScreener that are **not** on the curated Monad list, with a logo and on-chain decimals, all `verified: false`. This mode answers `{ tokens }` only, returns up to 8 rows whatever `limit` says, and returns an empty list for a query under 2 characters.\n\nRanking: the exact address, then the exact symbol, a symbol prefix, a name prefix, then any substring; verified rows first within a rank, one row per address. A leading `$` is ignored. Treat `verified: false` as unvetted and check the address before trading it.\n\n**Arc**: `/arc/tokens/search` returns full board rows (price, volume, pools, flags) for the same query.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Symbol, name or address fragment." }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 4663, 5042, 43114, 8453, 56, 42161, 1, 143 ], "default": 143 }, "description": "Chain id: `4663` Robinhood Chain · `5042` Arc · `43114` Avalanche C-Chain · `8453` Base · `56` BNB Chain · `42161` Arbitrum One · `1` Ethereum · `143` Monad. Omitted = 143. Pass the chain you want: the default is Monad off-list discovery." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 8 }, "description": "Rows to return, clamped to 1–25. Ignored in Monad mode." } ], "responses": { "200": { "description": "Matches, best first. An empty `tokens` is a real answer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "The chain searched. Absent in Monad mode." }, "q": { "type": "string", "description": "The query as received. Absent in Monad mode." }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "symbol": { "type": "string", "description": "" }, "name": { "type": "string", "description": "" }, "decimals": { "type": [ "integer", "null" ], "description": "ERC-20 decimals. Null for an off-list token whose decimals are not resolved yet." }, "logoURI": { "type": [ "string", "null" ], "description": "Logo URL when known. Absent on off-list Robinhood Chain rows." }, "verified": { "type": "boolean", "description": "On the chain's curated list. False = found by the index or by discovery, not vetted." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "`stock`, `stablecoin`, … from the curated list (Robinhood Chain); `meme` in Monad mode. Absent when empty." }, "liquidityUsd": { "type": [ "number", "null" ], "description": "Monad mode only: liquidity of the deepest DexScreener pair." } }, "required": [ "address", "symbol", "name", "decimals", "verified" ] } } }, "required": [ "tokens" ] }, "example": { "chain": 4663, "q": "NVDA", "tokens": [ { "address": "0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC", "symbol": "NVDA", "name": "NVIDIA • Robinhood Token", "decimals": 18, "logoURI": "https://cdn.robinhood.com/ncw_assets/logos/0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec.png", "verified": true, "tags": [ "stock" ] } ] } } } }, "400": { "description": "`BAD_CHAIN` (a chain this route does not search) or `BAD_QUERY` (`q` empty or longer than 64 characters). Monad mode does not validate `q`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CHAIN_NOT_PUBLIC`: the chain is not public yet and the request has no `X-API-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tokens/chart/{address}": { "get": { "tags": [ "Tokens and charts" ], "operationId": "tokenChart", "summary": "Candles", "description": "OHLCV candles from Chord's own tape, address-keyed — one call serves Arc and Robinhood Chain tokens (addresses cannot collide). 200 candles per page; `before` pages backwards for unlimited history. A token that is not on a curated list and not a side of an indexed pool is `404 UNKNOWN_TOKEN`. For live candles subscribe on `/v1/ws/live` (see Streaming).", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" }, { "name": "tf", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1m", "5m", "15m", "1h", "4h", "1d", "1w" ], "default": "1h" }, "description": "Timeframe." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer", "description": "Unix time, seconds, UTC." }, "description": "Return the 200 candles before this time (paging)." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "candles": { "type": "array", "items": { "$ref": "#/components/schemas/Candle" }, "description": "Oldest first." }, "tf": { "type": "string", "description": "" }, "source": { "type": "string", "description": "`db` = Chord's tape." } } }, "example": { "candles": [ { "t": 1789520400, "o": 76161.46230007616, "h": 93752.28222071448, "l": 73286.91828508611, "c": 73301.06410779823, "v": 22676.53 }, { "t": 1789524000, "o": 73332.39663202444, "h": 75694.61170208515, "l": 73332.39663202444, "c": 75694.61170208515, "v": 173955.23 } ], "tf": "1h", "source": "db" } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing at this identity (`NOT_FOUND`, `UNKNOWN_TOKEN`, `NO_ROUTE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/candles": { "get": { "tags": [ "Tokens and charts" ], "operationId": "candles", "summary": "Candles (data API)", "description": "OHLCV for any token Chord indexes on Arc, Robinhood Chain, Avalanche, Base, BNB Chain, Arbitrum, Ethereum or Monad, built only from Chord's own index — never a third-party feed, so `source` is always `index`. 1m / 5m / 15m come from a 1-minute rollup that keeps history after raw trades are retired; 1h and above from the hourly rollup; the newest minutes straight from the tape. Each candle carries `n`, the trades in the bucket. Buckets without a trade are absent unless `fill=1`, which carries the previous close through them.\n\nPaging: the default window ends with the still-open bucket (`forming: true`) and holds `limit` buckets. A `from`–`to` range wider than `limit` keeps the newest buckets; ask for the previous page with `to` = this page's `from`. The token must trade on the chain you name — `404 UNKNOWN_TOKEN` says which chain it trades on when it is another one. The zero address stands for the chain's native asset (its wrapped twin, or the USDC predeploy on Arc). For live candles subscribe on `/v1/ws/live` (see Streaming).\n\n**Avalanche, Base, BNB Chain** (`43114`, `8453`, `56`): candles come from chain-keyed tables, so one address on two chains is two tokens, and `404 UNKNOWN_TOKEN` means no indexed trades on the chain you named. These chains answer once their tape runs and, until the chain is public, only to requests with an `X-API-Key` (`400 UNSUPPORTED_CHAIN` otherwise; all three are public today). Where the tape runs with an ingest floor (BNB Chain, $100 today) the response carries `ingestFloor`, and `v` and `n` count only trades at or above it.", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 5042, 4663, 43114, 8453, 56, 42161, 1, 143 ], "default": 143 }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `43114` Avalanche C-Chain · `8453` Base · `56` BNB Chain · `42161` Arbitrum One · `1` Ethereum · `143` Monad. Omitted = 143." }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "Token address." }, { "name": "tf", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1m", "5m", "15m", "1h", "4h", "1d", "1w" ], "default": "1h" }, "description": "Timeframe." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "integer", "description": "Unix time, seconds, UTC." }, "description": "Start, inclusive. Default: `to` minus `limit` buckets." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "integer", "description": "Unix time, seconds, UTC." }, "description": "End, exclusive, snapped up to a bucket edge. Default: the end of the open bucket." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 300 }, "description": "Buckets per page." }, { "name": "fill", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Carry the previous close through empty buckets (v = 0, n = 0)." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tf": { "type": "string", "description": "" }, "source": { "type": "string", "description": "Always `index`." }, "from": { "type": "integer", "description": "Unix time, seconds, UTC." }, "to": { "type": "integer", "description": "Unix time, seconds, UTC." }, "forming": { "type": "boolean", "description": "The last candle is the still-open bucket." }, "ingestFloor": { "$ref": "#/components/schemas/IngestFloor", "description": "Only on 43114 / 8453 / 56 when the tape runs with a floor (BNB Chain)." }, "candles": { "type": "array", "items": { "type": "object", "properties": { "t": { "type": "integer", "description": "Unix time, seconds, UTC." }, "o": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" }, "l": { "type": "number", "description": "" }, "c": { "type": "number", "description": "" }, "v": { "type": "number", "description": "USD volume in the bucket." }, "n": { "type": [ "integer", "null" ], "description": "Trades in the bucket." } } }, "description": "Oldest first." } } }, "example": { "chain": 5042, "token": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0", "tf": "1h", "source": "index", "from": 1790704800, "to": 1790712000, "forming": true, "candles": [ { "t": 1790704800, "o": 83084.16874661468, "h": 83761.32352941176, "l": 82504.09836065574, "c": 83716.00512163893, "v": 236698.5, "n": 976 }, { "t": 1790708400, "o": 83676.16747181964, "h": 83758.25396825396, "l": 82970.76923076923, "c": 83590.35733333333, "v": 28901.4, "n": 212 } ] } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing at this identity (`NOT_FOUND`, `UNKNOWN_TOKEN`, `NO_ROUTE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tokens/trades/{address}": { "get": { "tags": [ "Tokens and charts" ], "operationId": "tokenTrades", "summary": "Trade tape", "description": "Recent swaps of a token, newest first, with the venue, side, size, price and the attributed wallet. Filter by side, venue, minimum size or wallet; page with `page`. `stats24h` sums the day.", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" }, { "name": "side", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "buy", "sell" ] }, "description": "" }, { "name": "dex", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Venue id." }, { "name": "min", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Minimum USD." }, { "name": "wallet", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "trades": { "type": "array", "items": { "$ref": "#/components/schemas/TradeRow" } }, "total": { "type": "integer", "description": "" }, "page": { "type": "integer", "description": "" }, "pageSize": { "type": "integer", "description": "" }, "dexes": { "type": "array", "items": { "type": "string" }, "description": "Venues seen on this token." }, "stats24h": { "type": "object", "properties": { "buys": { "type": "integer", "description": "" }, "sells": { "type": "integer", "description": "" }, "buyUsd": { "type": "number", "description": "" }, "sellUsd": { "type": "number", "description": "" } } } } }, "example": { "trades": [ { "tx": "0x4e0bda6af0d4e75c98049cc7c64c5fb9112dcb7e397d68f851cfc01406df33db", "logIndex": 41, "dex": "uniswap_v3", "side": "buy", "tokenAmt": 0.00587394, "usd": 472.372001, "priceUsd": 80418.25435738193, "ts": 1789891817, "wallet": "0x0e177f6758872e474c8adb191fbd33352495911d" }, { "tx": "0xac5d6408c433ced6e93e0b5d4118f5f726511c0e0514f4ea6a9a7cb98552cde4", "logIndex": 3, "dex": "uniswap_v3", "side": "buy", "tokenAmt": 0.01154339, "usd": 928.183258, "priceUsd": 80408.20400246374, "ts": 1789891817, "wallet": "0x870c73c98a14b6956b79247e1a1cdc68ba0060ee" } ], "total": 2001, "page": 1, "pageSize": 2, "dexes": [ "slipstream_fork", "uniswap_v3" ], "stats24h": { "buys": 11127, "sells": 9332, "buyUsd": 2902488.248025012, "sellUsd": 3019938.981532 } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing at this identity (`NOT_FOUND`, `UNKNOWN_TOKEN`, `NO_ROUTE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tokens/stats/{address}": { "get": { "tags": [ "Tokens and charts" ], "operationId": "tokenStats", "summary": "Windowed stats", "description": "DexScreener-style windows (5 m, 1 h, 6 h, 24 h): change, transactions, buys/sells, buy/sell volume, makers, buyers, sellers — plus all-time high, 24-hour range, first trade, total transactions and the markets (pools) the token trades on. Cached with stale-while-revalidate, so it answers fast and refreshes in the background.", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "priceUsd": { "type": [ "number", "null" ], "description": "" }, "windows": { "type": "object", "properties": { "m5": { "$ref": "#/components/schemas/StatsWindow" }, "h1": { "$ref": "#/components/schemas/StatsWindow" }, "h6": { "$ref": "#/components/schemas/StatsWindow" }, "h24": { "$ref": "#/components/schemas/StatsWindow" } } }, "liquidityUsd": { "type": [ "number", "null" ], "description": "" }, "ath": { "type": [ "object", "null" ], "properties": { "priceUsd": { "type": "number", "description": "" }, "ts": { "type": "integer", "description": "Unix time, seconds, UTC." } } }, "range24h": { "type": [ "object", "null" ], "properties": { "high": { "type": "number", "description": "" }, "low": { "type": "number", "description": "" } } }, "firstTradeTs": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "totalTxns": { "type": "integer", "description": "" }, "markets": { "type": "array", "items": { "type": "object", "properties": { "dex": { "type": "string", "description": "" }, "pool": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "txns24h": { "type": "integer", "description": "" }, "vol24h": { "type": "number", "description": "" }, "makers24h": { "type": "integer", "description": "" } } } } } }, "example": { "priceUsd": 80418.25435738193, "windows": { "m5": { "change": 0, "txns": 26, "buys": 12, "sells": 14, "buyVol": 3176.8774229999995, "sellVol": 3214.276456, "makers": 16, "buyers": 10, "sellers": 8 }, "h1": { "change": 0.12, "txns": 405, "buys": 217, "sells": 188, "buyVol": 64728.724117999926, "sellVol": 46488.608315000005, "makers": 149, "buyers": 95, "sellers": 79 }, "h6": { "change": -0.81, "txns": 5797, "buys": 2956, "sells": 2841, "buyVol": 877524.8736700043, "sellVol": 985143.4303749993, "makers": 850, "buyers": 530, "sellers": 535 }, "h24": { "change": -0.87, "txns": 20459, "buys": 11127, "sells": 9332, "buyVol": 2902488.2480250364, "sellVol": 3019938.9815319907, "makers": 2942, "buyers": 2228, "sellers": 1933 } }, "liquidityUsd": null, "ath": { "priceUsd": 93752.28222071448, "ts": 1789520400 }, "range24h": { "high": 81967.21311475411, "low": 79796.7741935484 }, "firstTradeTs": 1789520400, "totalTxns": 78768, "markets": [ { "dex": "uniswap_v3", "pool": "0x82916bee18fcef517b26c72d7cb5f13694e1db41", "txns24h": 17884, "vol24h": 5118587.965404977, "makers24h": 2673 }, { "dex": "slipstream_fork", "pool": "0xd945caee4635bcd7fb8a9fa74dc1d0c4c1472782", "txns24h": 1744, "vol24h": 787999.6481669984, "makers24h": 347 } ] } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing at this identity (`NOT_FOUND`, `UNKNOWN_TOKEN`, `NO_ROUTE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/logo/{chain}/{address}": { "get": { "tags": [ "Tokens and charts" ], "operationId": "tokenLogo", "summary": "Token logo", "description": "A 128 px WebP of the token's logo, fetched once from the upstream source and cached on disk. A placeholder image (200) when there is none — never a 404, so an `` never breaks. Every `logoURI` in Arc rows points here.", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "integer", "enum": [ 5042, 4663, 143, 43114, 8453, 56, 42161, 1 ] }, "description": "" }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" } ], "responses": { "200": { "description": "`image/webp` (or the SVG placeholder).", "content": { "image/webp": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/smart-money/top": { "get": { "tags": [ "Top wallets" ], "operationId": "smartMoneyTop", "summary": "Wallets ranked by Smart Score", "description": "Which wallets make money on the chain, from the tape, ranked by a skill-adjusted score rather than raw profit (realized-weighted, luck-corrected, recency-decayed). Routers, executors and bots are removed before ranking (`botsRemoved` counts them). On Arc the board moves between rebuilds: a live delta of the last minutes' trades sits on top of the last roll (`live`).\n\n**Notes**: `source=onchain` is required on 5042 / 4663. The board is rebuilt on a schedule per window (15 min for 24h, hourly for 7d / 30d, 3 h for all) and served from cache in between. `503 CHAIN_NOT_ENABLED` until the board is published for the chain.", "parameters": [ { "name": "chain", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 5042, 4663, 143 ], "default": 143 }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad. Omitted = 143." }, { "name": "source", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "onchain", "nullterminal" ] }, "description": "`onchain` = every venue, from the tape. Required on 5042 and 4663." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "all" ], "default": "all" }, "description": "" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "memes", "majors" ], "default": "all" }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallets": { "type": "array", "items": { "$ref": "#/components/schemas/SmartWallet" } }, "totalWallets": { "type": "integer", "description": "Wallets that qualified after the bot passes." }, "window": { "type": "string", "description": "" }, "category": { "type": "string", "description": "" }, "chain": { "type": "integer", "description": "" }, "source": { "type": "string", "description": "" }, "indexedToBlock": { "type": "integer", "description": "The chain block the tape had reached when this board was built." }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." }, "live": { "type": "object", "additionalProperties": true, "description": "Arc only — the in-memory delta on top of the last roll." }, "botsRemoved": { "type": "object", "properties": { "cadence": { "type": "integer", "description": "" }, "nonceOrDenylist": { "type": "integer", "description": "" }, "behavior": { "type": "integer", "description": "" } } }, "note": { "type": "string", "description": "" } } }, "example": { "wallets": [ { "wallet": "0xb145400da27a2497d9fc2cd5621f2bfd37617af4", "pnlUsd": 85260.25886163529, "realizedUsd": 28166.924288181075, "unrealizedUsd": 57093.33457345421, "volumeUsd": 68986.38694614707, "trades": 49, "tokensTraded": 5, "winningTokens": 3, "winRate": 0.6, "topToken": { "symbol": "ARGUS", "pnlUsd": 85345.61369765387 }, "lastActiveTs": 1789890946, "pnlMeme": 85260.25886163529, "pnlMajor": 0, "memeVol": 68986.38694614707, "archetype": "degen", "memeShare": 1, "winRateAdj": 0.5294117647058824, "smartScore": 43067.763434718785 }, { "wallet": "0xf8218b98f49b86c7e491079591acc08ee4fd6e7e", "pnlUsd": 53891.271617383565, "realizedUsd": 26940.46261686956, "unrealizedUsd": 26950.809000514004, "volumeUsd": 150140.03604099998, "trades": 70, "tokensTraded": 11, "winningTokens": 9, "winRate": 0.8181818181818182, "topToken": { "symbol": "ARGUS", "pnlUsd": 22862.25828632662 }, "lastActiveTs": 1789890046, "pnlMeme": 53891.271617383565, "pnlMajor": 0, "memeVol": 150140.03604099998, "archetype": "degen", "memeShare": 1, "winRateAdj": 0.6521739130434783, "smartScore": 32966.26695083121 } ], "totalWallets": 92826, "window": "7d", "category": "all", "chain": 5042, "source": "onchain", "indexedToBlock": 21808217, "updatedAt": 1789891859855, "live": { "rollStamp": 1789891728, "buckets": 21, "rows": 253, "seen": 1261, "ingested": 1261, "skippedDup": 0, "computedAt": 0 }, "botsRemoved": { "cadence": 325, "nonceOrDenylist": 5, "behavior": 37 }, "note": "ranked by Smart Score — skill-adjusted, realized-weighted profit (est. at current prices)" } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/portfolio/{wallet}/pnl": { "get": { "tags": [ "Portfolio" ], "operationId": "walletPnl", "summary": "Realized and open PnL per token", "description": "Average-cost PnL for one wallet from the tape: realized on sells, unrealized on what is still held at current prices, ROI, and the untracked balance that arrived by transfer (no cost basis, excluded from PnL). Cached with stale-while-revalidate (a day-old answer beats a $0 skeleton).\n\nPortfolio routes answer an empty 200 shape rather than a 5xx when the tape read fails — treat an empty `tokens` list as \"nothing yet\" and retry later.", "parameters": [ { "name": "wallet", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "5042", "4663", "143", "all" ], "default": "all" }, "description": "One chain, or `all` to merge chains with a `byChain` breakdown." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/PnlToken" } }, "realized": { "type": "number", "description": "" }, "unrealized": { "type": "number", "description": "" }, "total": { "type": "number", "description": "" }, "exitedWithoutSale": { "type": "object", "additionalProperties": true, "description": "Present when bought quantity left the wallet with no sale on the tape (a transfer out, or a sale credited to another address): `{tokens, costUsd, top: [{symbol, costUsd}]}`. Its result is unknown and NOT in the PnL above." }, "byChain": { "type": "object", "additionalProperties": true, "description": "Only with `chain=all`." }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "tokens": [ { "token": "0xece5ca8bf9220718e5727754026757512212cb3c", "symbol": "ARGUS", "logo": "https://coin-images.coingecko.com/coins/images/102178392/large/argus-token.png?1789463380", "realizedUsd": 30462.864779627198, "unrealizedUsd": 11700.939232721703, "totalUsd": 42163.804012348905, "costRemaining": 1286.137220108177, "curValue": 12987.07645282988, "curAmount": 744055.9147763874, "avgCost": 0.0017285491514366933, "roiPct": 909.7737822825419, "untrackedAmount": 0, "untrackedValue": 0 }, { "token": "0x66927743a8a841ca09575a4ccdcd090c761adcec", "symbol": "HYCI", "logo": "https://ipfs.filebase.io/ipfs/bafybeiezh2g4uhqy2bzdq4elwkzek55q5ccs4gpyyki672a4i3olf3u224", "realizedUsd": 181.713005, "unrealizedUsd": 0, "totalUsd": 181.713005, "costRemaining": 0, "curValue": 0, "curAmount": 0, "avgCost": 0.000042576384935211256, "roiPct": null, "untrackedAmount": 0, "untrackedValue": 0 } ], "realized": 30488.101882774274, "unrealized": 11700.939232721703, "total": 42189.04111549597, "updatedAt": 1789809277093 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/wallet/{wallet}/balances": { "get": { "tags": [ "Portfolio" ], "operationId": "walletBalances", "summary": "Holdings on every chain", "description": "What a wallet holds right now on Chord's six chains (Monad, Robinhood Chain, Arc, Avalanche, Base, BNB Chain), read on-chain: the native coin plus every token on Chord's list for each chain, priced by Chord's own maps. `raw` is the exact balance in the token's smallest unit (use it for a Max button); `amount` is the same number in whole tokens. Each chain answers on its own deadline: a slow or failing chain comes back `unavailable` with a reason and the others still answer. Only listed tokens are seen; a token outside Chord's lists will not show. Cached 15 s per wallet and chain set.", "parameters": [ { "name": "wallet", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" }, { "name": "chains", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma list of chain ids (143, 4663, 5042, 43114, 8453, 56). Default: all six; unknown ids are ignored." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "totalUsd": { "type": "number", "description": "Sum of priced holdings." }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." }, "chains": { "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "name": { "type": "string", "description": "" }, "status": { "type": "string", "enum": [ "ok", "unavailable", "no_rpc" ] }, "reason": { "type": "string", "description": "Only when not ok." }, "totalUsd": { "type": "number", "description": "" }, "holdings": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string", "description": "" }, "name": { "type": [ "string", "null" ], "description": "" }, "address": { "type": [ "string", "null" ], "description": "Null for the native coin." }, "native": { "type": "boolean", "description": "" }, "decimals": { "type": "integer", "description": "" }, "raw": { "type": "string", "description": "Exact balance, smallest unit." }, "amount": { "type": "string", "description": "Whole tokens." }, "priceUsd": { "type": [ "number", "null" ], "description": "" }, "valueUsd": { "type": [ "number", "null" ], "description": "" }, "logoURI": { "type": [ "string", "null" ], "description": "" }, "stable": { "type": "boolean", "description": "" } } }, "description": "Highest value first." } } } } } }, "example": { "wallet": "0x0d36a315083033d3d097950c9e494acc04588f99", "chains": [ { "chain": 8453, "name": "Base", "status": "ok", "totalUsd": 1221.38, "holdings": [ { "symbol": "ETH", "name": null, "address": null, "native": true, "decimals": 18, "raw": "454663939527832318", "amount": "0.454663939527832318", "priceUsd": 2686.342436128022, "valueUsd": 1221.38, "logoURI": null, "stable": false }, { "symbol": "WETH", "name": null, "address": "0x4200000000000000000000000000000000000006", "native": false, "decimals": 18, "raw": "148044", "amount": "0.000000000000148044", "priceUsd": 2686.342436128022, "valueUsd": 0, "logoURI": null, "stable": false } ] } ], "totalUsd": 1221.38, "updatedAt": 1791052461304 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/portfolio/{wallet}/trades": { "get": { "tags": [ "Portfolio" ], "operationId": "walletTrades", "summary": "Trade history", "description": "The wallet's buys and sells on the chain, newest first — the markers on a portfolio chart.\n\nPortfolio routes answer an empty 200 shape rather than a 5xx when the tape read fails — treat an empty `tokens` list as \"nothing yet\" and retry later.", "parameters": [ { "name": "wallet", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 5042, 4663, 143 ], "default": 143 }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad. Omitted = 143." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "trades": { "type": "array", "items": { "type": "object", "properties": { "t": { "type": "integer", "description": "Unix time, seconds, UTC." }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "usd": { "type": "number", "description": "" }, "tokenAmt": { "type": "number", "description": "" }, "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "symbol": { "type": [ "string", "null" ], "description": "" }, "tx": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$", "description": "Transaction hash." } } } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "trades": [ { "t": 1789890946, "side": "buy", "usd": 198, "tokenAmt": 5293562.144446149, "token": "0x08adbf431569a1aacac2606d2adcd18f4ebf2a71", "symbol": "GLITCH", "tx": "0x25c5fd4de14a7592e39f0b803538cdbe1601a927f630da46fe9107c3afc89f83" }, { "t": 1789890762, "side": "buy", "usd": 297, "tokenAmt": 8471531.758406071, "token": "0x08adbf431569a1aacac2606d2adcd18f4ebf2a71", "symbol": "GLITCH", "tx": "0xf261bcb6c8d8bf3fe9debbd9f012396c8e025eafbcb047d40c5ee66013df9ef9" } ], "updatedAt": 1789891871018 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/portfolio/{wallet}/pnl-calendar": { "get": { "tags": [ "Portfolio" ], "operationId": "walletPnlCalendar", "summary": "Realized PnL by day", "description": "Day-by-day realized PnL (UTC days) with the trade count, from the same average-cost model as `/pnl`, so the day sums reconcile with `realized` by construction.\n\nPortfolio routes answer an empty 200 shape rather than a 5xx when the tape read fails — treat an empty `tokens` list as \"nothing yet\" and retry later.", "parameters": [ { "name": "wallet", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 5042, 4663, 143 ], "default": 143 }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad. Omitted = 143." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "YYYY-MM-DD" }, "realizedUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" } } } }, "firstDate": { "type": [ "string", "null" ], "description": "" }, "realizedTotal": { "type": "number", "description": "" }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "days": [ { "date": "2026-08-19", "realizedUsd": 0, "trades": 6 }, { "date": "2026-08-20", "realizedUsd": 0, "trades": 2 } ], "firstDate": "2026-08-19", "realizedTotal": 34046.5607144201, "updatedAt": 1789891871239 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lp/overview": { "get": { "tags": [ "Liquidity" ], "operationId": "lpOverview", "summary": "Liquidity headline", "description": "The pools page pulse: fees paid to LPs in 24 hours (top 100 pools by fees), the best real yield (≥ 25 traders, not suspect), dollars added and removed, volume, TVL and providers over pools with ≥ $10k TVL, the six hottest pools by fees and the three biggest net inflows. Memoised 30 s.", "parameters": [ { "name": "chain", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "pools24h": { "type": "integer", "description": "" }, "tvlUsd": { "type": "number", "description": "" }, "vol24hUsd": { "type": "number", "description": "" }, "fees24hUsd": { "type": "number", "description": "" }, "feesPoolsCounted": { "type": "integer", "description": "" }, "lpAdd24hUsd": { "type": "number", "description": "" }, "lpRemove24hUsd": { "type": "number", "description": "" }, "providers24h": { "type": "integer", "description": "" }, "best": { "type": [ "object", "null" ], "properties": { "pool": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "pair": { "type": "string", "description": "" }, "token0": { "$ref": "#/components/schemas/TokenLite" }, "token1": { "$ref": "#/components/schemas/TokenLite" }, "dex": { "type": "string", "description": "" }, "feeTvlPct": { "type": "number", "description": "" }, "aprPct": { "type": [ "number", "null" ], "description": "" }, "tvlUsd": { "type": [ "number", "null" ], "description": "" } } }, "hot": { "type": "array", "items": { "type": "object", "properties": { "pool": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "pair": { "type": "string", "description": "" }, "token0": { "$ref": "#/components/schemas/TokenLite" }, "token1": { "$ref": "#/components/schemas/TokenLite" }, "dex": { "type": "string", "description": "" }, "feeBps": { "type": [ "number", "null" ], "description": "" }, "fees24hUsd": { "type": "number", "description": "" }, "feeTvlPct": { "type": [ "number", "null" ], "description": "" }, "tvlUsd": { "type": [ "number", "null" ], "description": "" }, "vol24hUsd": { "type": "number", "description": "" }, "wallets24h": { "type": "integer", "description": "" } } } }, "inflow": { "type": "array", "items": { "type": "object", "properties": { "pool": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "pair": { "type": "string", "description": "" }, "token0": { "$ref": "#/components/schemas/TokenLite" }, "token1": { "$ref": "#/components/schemas/TokenLite" }, "dex": { "type": "string", "description": "" }, "netUsd": { "type": "number", "description": "" }, "tvlUsd": { "type": [ "number", "null" ], "description": "" } } } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "pools24h": 416, "tvlUsd": 59062379.766785584, "vol24hUsd": 32606366.761442985, "fees24hUsd": 108337.05880814306, "feesPoolsCounted": 31, "lpAdd24hUsd": 18682513.45246684, "lpRemove24hUsd": 26568879.80331895, "providers24h": 1750, "best": { "pool": "0xf53f02d9041d00bbd92235b4c902b9f350c554a8ed2dc64fa0a4585aac413f09", "pair": "USDC / MURMUR", "token0": { "address": "0x3600000000000000000000000000000000000000", "symbol": "USDC", "decimals": 6, "logo": "https://coin-images.coingecko.com/coins/images/6319/large/USDC.png?1769615602", "impostor": false }, "token1": { "address": "0x8faae5592b9acc27a79fca745c6b872adf514a5d", "symbol": "MURMUR", "decimals": 18, "logo": "https://cdn.dexscreener.com/cms/images/QUq-IqT1GLQNkxMx?width=800&height=800&quality=95&format=auto", "impostor": false }, "dex": "uniswap_v4", "feeTvlPct": 14.40921999562047, "aprPct": 5259.365298401472, "tvlUsd": 12650.66 }, "hot": [ { "pool": "0x6a3bacaa6493734c1ac221ebf42cf530a96c1e02", "pair": "USDC / ARGUS", "token0": { "address": "0x3600000000000000000000000000000000000000", "symbol": "USDC", "decimals": 6, "logo": "https://coin-images.coingecko.com/coins/images/6319/large/USDC.png?1769615602", "impostor": false }, "token1": { "address": "0xece5ca8bf9220718e5727754026757512212cb3c", "symbol": "ARGUS", "decimals": 18, "logo": "https://cdn.dexscreener.com/cms/images/0lkViejHOEfB3StE?width=800&height=800&quality=95&format=auto", "impostor": false }, "dex": "uniswap_v3", "feeBps": 100, "fees24hUsd": 21874.53260752, "feeTvlPct": 2.0870143590342853, "tvlUsd": 1048125.64, "vol24hUsd": 2187453.260752, "wallets24h": 598 }, { "pool": "0xb3f441e8871840ecfcb284e5cbb5b9c21a50e961e1c50109bdced25e429f00cc", "pair": "USDC / ARGUS", "token0": { "address": "0x3600000000000000000000000000000000000000", "symbol": "USDC", "decimals": 6, "logo": "https://coin-images.coingecko.com/coins/images/6319/large/USDC.png?1769615602", "impostor": false }, "token1": { "address": "0xece5ca8bf9220718e5727754026757512212cb3c", "symbol": "ARGUS", "decimals": 18, "logo": "https://cdn.dexscreener.com/cms/images/0lkViejHOEfB3StE?width=800&height=800&quality=95&format=auto", "impostor": false }, "dex": "uniswap_v4", "feeBps": 98.5, "fees24hUsd": 14338.80123860194, "feeTvlPct": 4.759044987124094, "tvlUsd": 301295.77, "vol24hUsd": 1455715.861786999, "wallets24h": 313 } ], "inflow": [ { "pool": "0xd945caee4635bcd7fb8a9fa74dc1d0c4c1472782", "pair": "cirBTC / USDC", "token0": { "address": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0", "symbol": "cirBTC", "decimals": 8, "logo": "https://coin-images.coingecko.com/coins/images/102172745/large/cirbtc.jpg?1775204071", "impostor": false }, "token1": { "address": "0x3600000000000000000000000000000000000000", "symbol": "USDC", "decimals": 6, "logo": "https://coin-images.coingecko.com/coins/images/6319/large/USDC.png?1769615602", "impostor": false }, "dex": "slipstream_fork", "netUsd": 44469.43327364928, "tvlUsd": 570213.05 }, { "pool": "0xa2ed014384e061ec2aaccea186d41798dcf4da29264c44a676d3006fdc252ae0", "pair": "USDC / ARCOON", "token0": { "address": "0x3600000000000000000000000000000000000000", "symbol": "USDC", "decimals": 6, "logo": "https://coin-images.coingecko.com/coins/images/6319/large/USDC.png?1769615602", "impostor": false }, "token1": { "address": "0x4621a0baa0b5d97aae77704cf2a84dabe78a4fed", "symbol": "ARCOON", "decimals": 18, "logo": "https://ipfs.filebase.io/ipfs/bafybeiecv2b5gkrr5q4cesftgirntp4roqixhcily6ynfjitgdcunxm3x4", "impostor": false }, "dex": "uniswap_v4", "netUsd": 24000.000013, "tvlUsd": 142471.24 } ], "updatedAt": 1789891860138 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lp/pools": { "get": { "tags": [ "Liquidity" ], "operationId": "lpPools", "summary": "Pools ranked for a liquidity provider", "description": "Every indexed pool with volume by window, fees (volume × the pool's fee tier), TVL, fee/TVL and an annualised yardstick, LP adds / removes / providers in 24 hours, trader counts, and a 0–100 health score. Pools under $10k TVL are hidden unless `small=1`; wash and launch-farm pools are hidden unless `flagged=1` (they come back with `suspect: true`). `category=stocks` keeps the pools with a tokenized stock or ETF on one side (Robinhood Chain only: `400 BAD_CATEGORY` elsewhere, `503 CATEGORY_UNAVAILABLE` while the token list cannot be read).\n\n**Use it for**: an LP screener, \"where are the fees on Arc\", a pool picker for a token.", "parameters": [ { "name": "chain", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "fee_tvl", "vol_24h", "vol_1h", "tvl", "fees_24h", "first_seen", "lp_net_24h", "trades_24h", "score" ], "default": "fee_tvl" }, "description": "" }, { "name": "interval", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1h", "6h", "24h" ], "default": "24h" }, "description": "Window the fee/TVL sort uses." }, { "name": "minTvl", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "Default 10000 unless `small=1`." }, { "name": "quote", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Anchor symbol filter (e.g. `USDC`)." }, { "name": "dex", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Venue id filter." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 }, "description": "Symbol or address." }, { "name": "small", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 }, "description": "1 = include pools under $10k TVL." }, { "name": "flagged", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 }, "description": "1 = include suspect pools." }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "stocks" ] }, "description": "Robinhood Chain (4663): pools with a tokenized stock or ETF on one side." }, { "name": "maxTvl", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "Range filters: every bound is inclusive, unset = off, and a row whose figure the index does not have fails a set bound." }, { "name": "minVol", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "Volume of the `interval`, dollars." }, { "name": "maxVol", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "" }, { "name": "minFees", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "Fees of the `interval`, dollars." }, { "name": "maxFees", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "" }, { "name": "minAgeH", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "Hours since the pool was created (since its first trade when the creation is unknown)." }, { "name": "maxAgeH", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "" }, { "name": "minFeePct", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 100 }, "description": "Fee tier in percent (0.3 = 30 bps)." }, { "name": "maxFeePct", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 100 }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 5000, "default": 0 }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "sort": { "type": "string", "description": "" }, "interval": { "type": "string", "description": "" }, "minTvl": { "type": "number", "description": "" }, "flagged": { "type": "boolean", "description": "" }, "category": { "type": "string", "description": "Present when the list was narrowed to a category." }, "hidden": { "type": "integer", "description": "Rows removed by the filters." }, "total": { "type": "integer", "description": "" }, "limit": { "type": "integer", "description": "" }, "offset": { "type": "integer", "description": "" }, "pools": { "type": "array", "items": { "$ref": "#/components/schemas/PoolListRow" } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "sort": "fee_tvl", "interval": "24h", "minTvl": 10000, "flagged": false, "hidden": 148, "total": 1207, "limit": 2, "offset": 0, "pools": [ { "pool": "0xf53f02d9041d00bbd92235b4c902b9f350c554a8ed2dc64fa0a4585aac413f09", "dex": "uniswap_v4", "kind": "v4", "feeBps": 98.8, "hooks": null, "lpAccess": "open", "tickSpacing": 99, "token0": { "address": "0x3600000000000000000000000000000000000000", "symbol": "USDC", "decimals": 6, "logo": "https://coin-images.coingecko.com/coins/images/6319/large/USDC.png?1769615602", "impostor": false }, "token1": { "address": "0x8faae5592b9acc27a79fca745c6b872adf514a5d", "symbol": "MURMUR", "decimals": 18, "logo": "https://cdn.dexscreener.com/cms/images/QUq-IqT1GLQNkxMx?width=800&height=800&quality=95&format=auto", "impostor": false }, "tokenSide": 1, "tvlUsd": 12650.66, "tvlSrc": "dexscreener", "tvlAt": 1789891603, "vol": { "h1": 176.542824, "h6": 38476.48885700001, "h24": 184500.14476700005, "d7": 279614.0964730001 }, "fees": { "h1": 1.74424310112, "h6": 380.1477099071601, "h24": 1822.8614302979606 }, "feeTvlPct": { "h1": 0.01378776365122452, "h6": 3.0049634557182006, "h24": 14.40921999562047 }, "aprPct": 5259.365298401472, "trades24h": 3050, "wallets24h": 131, "priceUsd": 0.0007671677499328048, "lpAdd24h": 10038.913414765322, "lpRemove24h": 7583.743885515528, "providers24h": 25, "firstSeenTs": 1789693200, "createdTs": 1789695461, "lastTradeHour": 1789891200, "turnover24h": 14.584230764798047, "suspect": false, "score": 54 }, { "pool": "0x5e794e5d3d01c045ddfb2448c4afd557ec297d1dee49b28923dc0ada3425f780", "dex": "uniswap_v4", "kind": "v4", "feeBps": 100, "hooks": "0x863233bec01b92f137677e0cdf69bce697a26044", "lpAccess": "open", "tickSpacing": 200, "token0": { "address": "0x3600000000000000000000000000000000000000", "symbol": "USDC", "decimals": 6, "logo": "https://coin-images.coingecko.com/coins/images/6319/large/USDC.png?1769615602", "impostor": false }, "token1": { "address": "0xb7c934ff18730c24e6113bb4bc5a68feef16fd29", "symbol": "ARCUS", "decimals": 18, "logo": "https://cdn.dexscreener.com/cms/images/5y5kHHeZlCoSxlaq?width=800&height=800&quality=95&format=auto", "impostor": false }, "tokenSide": 1, "tvlUsd": 67762.97, "tvlSrc": "dexscreener", "tvlAt": 1789891603, "vol": { "h1": 1737.729194, "h6": 98528.85847099999, "h24": 738635.9835579997, "d7": 1514816.5901679986 }, "fees": { "h1": 17.377291940000003, "h6": 985.2885847099998, "h24": 7386.359835579997 }, "feeTvlPct": { "h1": 0.025644230086137018, "h6": 1.454022137326625, "h24": 10.90028939932827 }, "aprPct": 3978.605630754819, "trades24h": 5942, "wallets24h": 353, "priceUsd": 0.0004984252802693936, "lpAdd24h": 960.0917324579016, "lpRemove24h": 872.6609130846944, "providers24h": 11, "firstSeenTs": 1789567200, "createdTs": 1789570672, "lastTradeHour": 1789891200, "turnover24h": 10.900289399328273, "suspect": false, "score": 62 } ], "updatedAt": 1789891860349 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lp/pools/{pool}": { "get": { "tags": [ "Liquidity" ], "operationId": "lpPool", "summary": "One pool", "description": "The pool row plus its hourly series (the last 168 hours by default; `hours` up to 720), the top providers over 7 days, the health score with its parts and reasons, launch facts (who launched it, how much of the liquidity the launcher holds and has pulled), and `mint` — what a wallet needs to add liquidity here (the position manager, the pool key, Permit2, tick spacing).", "parameters": [ { "name": "pool", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "description": "" }, { "name": "chain", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad." }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "description": "" }, "description": "Hours of the hourly series, 24 to 720 (default 168)" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PoolListRow" }, { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "hourly": { "type": "array", "items": { "type": "object", "properties": { "hour": { "type": "integer", "description": "" }, "vol": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "price": { "type": [ "number", "null" ], "description": "" } } } }, "topLps": { "type": "array", "items": { "type": "object", "properties": { "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "addUsd": { "type": "number", "description": "" }, "removeUsd": { "type": "number", "description": "" }, "netUsd": { "type": "number", "description": "" }, "events": { "type": "integer", "description": "" }, "lastTs": { "type": "integer", "description": "Unix time, seconds, UTC." } } } }, "health": { "type": "object", "properties": { "score": { "type": "integer", "description": "" }, "parts": { "type": "object", "properties": { "traders": { "type": "number", "description": "" }, "tvl": { "type": "number", "description": "" }, "yieldSanity": { "type": "number", "description": "" }, "lpFlow": { "type": "number", "description": "" }, "age": { "type": "number", "description": "" }, "penalties": { "type": "number", "description": "" } } }, "reasons": { "type": "array", "items": { "type": "string" } } } }, "launch": { "type": [ "object", "null" ], "properties": { "launcher": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "launcherName": { "type": [ "string", "null" ], "description": "" }, "creator": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "hooks": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "launchedTs": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "launcherLpAddedUsd": { "type": "number", "description": "" }, "totalLpAddedUsd": { "type": "number", "description": "" }, "launcherSharePct": { "type": [ "number", "null" ], "description": "" }, "launcherLastRemoveTs": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "launcherRemovedUsd": { "type": "number", "description": "" } } }, "mint": { "type": [ "object", "null" ], "properties": { "kind": { "type": "string", "description": "" }, "manager": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "permit2": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "token0": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "token1": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "feePips": { "type": [ "integer", "null" ], "description": "" }, "tickSpacing": { "type": [ "integer", "null" ], "description": "" }, "hooks": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "feeRaw": { "type": [ "integer", "null" ], "description": "V4 dynamic-fee pools carry the 0x800000 flag." }, "nativeCurrency0": { "type": "boolean", "description": "" } } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } } ] }, "example": { "chain": 5042, "pool": "0xf53f02d9041d00bbd92235b4c902b9f350c554a8ed2dc64fa0a4585aac413f09", "dex": "uniswap_v4", "kind": "v4", "feeBps": 98.8, "hooks": null, "lpAccess": "open", "tickSpacing": 99, "token0": { "address": "0x3600000000000000000000000000000000000000", "symbol": "USDC", "decimals": 6, "logo": "https://coin-images.coingecko.com/coins/images/6319/large/USDC.png?1769615602", "impostor": false }, "token1": { "address": "0x8faae5592b9acc27a79fca745c6b872adf514a5d", "symbol": "MURMUR", "decimals": 18, "logo": "https://cdn.dexscreener.com/cms/images/QUq-IqT1GLQNkxMx?width=800&height=800&quality=95&format=auto", "impostor": false }, "tokenSide": 1, "tvlUsd": 12650.66, "tvlSrc": "dexscreener", "tvlAt": 1789891603, "vol": { "h1": 176.542824, "h6": 38476.48885700001, "h24": 184500.14476700005, "d7": 279614.0964730001 }, "fees": { "h1": 1.74424310112, "h6": 380.1477099071601, "h24": 1822.8614302979606 }, "feeTvlPct": { "h1": 0.01378776365122452, "h6": 3.0049634557182006, "h24": 14.40921999562047 }, "aprPct": 5259.365298401472, "trades24h": 3050, "wallets24h": 131, "priceUsd": 0.0007671677499328048, "lpAdd24h": 8037.861902775549, "lpRemove24h": 7583.743885515529, "providers24h": 25, "firstSeenTs": 1789693200, "createdTs": 1789695461, "lastTradeHour": 1789891200, "turnover24h": 14.584230764798047, "suspect": false, "hourly": [ { "hour": 1789693200, "vol": 398.305695, "trades": 24, "price": 0.00008817848931962542 }, { "hour": 1789696800, "vol": 1958.7937559999996, "trades": 77, "price": 0.00010307489720874844 } ], "topLps": [ { "wallet": "0x25cacb704ed0852428e7cc0687bca45ee8c21848", "addUsd": 5763.889211498252, "removeUsd": 0, "netUsd": 5763.889211498252, "events": 1, "lastTs": 1789695461 }, { "wallet": "0x5db28691cbfc2ceeca1d919f0749b64013c25432", "addUsd": 3885.2424150632846, "removeUsd": 1296.008402, "netUsd": 2589.2340130632847, "events": 254, "lastTs": 1789886789 } ], "health": { "score": 34, "parts": { "traders": 17.6, "tvl": 13.7, "yieldSanity": 4, "lpFlow": 15, "age": 3.2, "penalties": 20 }, "reasons": [ "the launcher holds 100% of the liquidity added", "fee/TVL over 10 %/day: volume is not organic or TVL is not the whole picture" ] }, "launch": { "launcher": "0x6049c9a0e26405c0985f9e3685c87d0ae917f82b", "launcherName": "Uniswap Liquidity Launcher", "creator": "0x25cacb704ed0852428e7cc0687bca45ee8c21848", "hooks": null, "launchedTs": 1789695461, "launcherLpAddedUsd": 15907.554822267326, "totalLpAddedUsd": 15907.554822267326, "launcherSharePct": 100, "launcherLastRemoveTs": 1789888952, "launcherRemovedUsd": 7697.230608504608 }, "mint": { "kind": "v4", "manager": "0x6049c9a0e26405c0985f9e3685c87d0ae917f82b", "permit2": "0x000000000022d473030f116ddee9f6b43ac78ba3", "token0": "0x3600000000000000000000000000000000000000", "token1": "0x8faae5592b9acc27a79fca745c6b872adf514a5d", "feePips": 9880, "tickSpacing": 99, "hooks": "0x0000000000000000000000000000000000000000", "feeRaw": 9880, "nativeCurrency0": false }, "updatedAt": 1789891869303 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing at this identity (`NOT_FOUND`, `UNKNOWN_TOKEN`, `NO_ROUTE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lp/pools/{pool}/positions": { "get": { "tags": [ "Liquidity" ], "operationId": "lpPoolPositions", "summary": "Open positions in a pool", "description": "Managed positions (V3 NPM / V4 PositionManager NFTs) open in the pool, largest first, valued live.", "parameters": [ { "name": "pool", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "description": "" }, { "name": "chain", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "pool": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/LpPosition" } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "pool": "0xf53f02d9041d00bbd92235b4c902b9f350c554a8ed2dc64fa0a4585aac413f09", "positions": [ { "manager": "0x6049c9a0e26405c0985f9e3685c87d0ae917f82b", "tokenId": "187740", "pool": "0xf53f02d9041d00bbd92235b4c902b9f350c554a8ed2dc64fa0a4585aac413f09", "dex": "uniswap_v4", "kind": "v4", "owner": "0x25cacb704ed0852428e7cc0687bca45ee8c21848", "token": "0x8faae5592b9acc27a79fca745c6b872adf514a5d", "anchor": "0x3600000000000000000000000000000000000000", "tickLower": 331254, "tickUpper": 375408, "symbol": "MURMUR", "anchorSymbol": "USDC", "logo": "https://cdn.dexscreener.com/cms/images/QUq-IqT1GLQNkxMx?width=800&height=800&quality=95&format=auto", "inUsd": 5763.889211498252, "outUsd": 0, "feesUsd": 0, "adds": 1, "removes": 0, "collects": 0, "openedTs": 1789695461, "lastTs": 1789695461, "closedTs": null, "burned": false, "status": "open", "valueUsd": 5408.735694717618, "uncollectedUsd": 2141.275199916123, "inRange": true, "edgePct": 427.51, "pnlUsd": 1786.1216831354886, "pnlPct": 30.988133491053144, "ageHours": 54.55777777777778, "jit": false, "unreconciled": false }, { "manager": "0x6049c9a0e26405c0985f9e3685c87d0ae917f82b", "tokenId": "223792", "pool": "0xf53f02d9041d00bbd92235b4c902b9f350c554a8ed2dc64fa0a4585aac413f09", "dex": "uniswap_v4", "kind": "v4", "owner": "0x2e41ff7889197ceab7ca505fe08fb54a9da07ab8", "token": "0x8faae5592b9acc27a79fca745c6b872adf514a5d", "anchor": "0x3600000000000000000000000000000000000000", "tickLower": 336204, "tickUpper": 357291, "symbol": "MURMUR", "anchorSymbol": "USDC", "logo": "https://cdn.dexscreener.com/cms/images/QUq-IqT1GLQNkxMx?width=800&height=800&quality=95&format=auto", "inUsd": 797.4331141591955, "outUsd": 0, "feesUsd": 0, "adds": 1, "removes": 0, "collects": 0, "openedTs": 1789888226, "lastTs": 1789888226, "closedTs": null, "burned": false, "status": "open", "valueUsd": 752.4410624979616, "uncollectedUsd": 5.447723353719422, "inRange": true, "edgePct": 156.14, "pnlUsd": -39.544328307514434, "pnlPct": -4.958952369216512, "ageHours": 1.0119444444444445, "jit": false, "unreconciled": false } ], "updatedAt": 1789891870022 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lp/pools/{pool}/lps": { "get": { "tags": [ "Liquidity" ], "operationId": "lpPoolLps", "summary": "A pool's providers by profit", "description": "The wallets that provided to one pool, most profitable first. Profit is the wallet board's: value out + fees − value in on closed positions, plus the fees of open ones. Scored like the board: positions of `minIn` dollars or more, none that opened and closed inside a minute, none the tape could not reconcile. `total` counts the wallets with a scored position in the pool.\n\n**Use it for**: \"who earns in this pool\", a provider table on a pool page.", "parameters": [ { "name": "pool", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "description": "" }, { "name": "chain", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Out of range is `400 BAD_LIMIT`." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "pool": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "minIn": { "type": "number", "description": "Dollars in under this are not scored." }, "total": { "type": "integer", "description": "Wallets with a scored position in the pool." }, "rows": { "type": "array", "items": { "type": "object", "properties": { "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "positions": { "type": "integer", "description": "" }, "open": { "type": "integer", "description": "" }, "closed": { "type": "integer", "description": "" }, "wins": { "type": "integer", "description": "" }, "winRatePct": { "type": [ "number", "null" ], "description": "Null with no closed position." }, "profitUsd": { "type": "number", "description": "" }, "feesUsd": { "type": "number", "description": "" }, "inUsd": { "type": "number", "description": "Dollars the wallet put into the pool, summed over its positions." }, "avgAgeHours": { "type": [ "number", "null" ], "description": "" }, "lastTs": { "type": "integer", "description": "Unix time, seconds, UTC." } } } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "pool": "0xf53f02d9041d00bbd92235b4c902b9f350c554a8ed2dc64fa0a4585aac413f09", "minIn": 20, "total": 60, "rows": [ { "wallet": "0x5db28691cbfc2ceeca1d919f0749b64013c25432", "positions": 2, "open": 0, "closed": 2, "wins": 1, "winRatePct": 50, "profitUsd": 898.4072651256388, "feesUsd": 1473.5195824012221, "inUsd": 4971.427097120565, "avgAgeHours": 85.54625, "lastTs": 1790521219 }, { "wallet": "0x2e41ff7889197ceab7ca505fe08fb54a9da07ab8", "positions": 2, "open": 0, "closed": 2, "wins": 2, "winRatePct": 100, "profitUsd": 602.4129568209053, "feesUsd": 431.0974968623506, "inUsd": 1101.9782460581446, "avgAgeHours": 66.98930555555556, "lastTs": 1790168420 } ], "updatedAt": 1791831160142 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lp/wallet/{address}": { "get": { "tags": [ "Liquidity" ], "operationId": "lpWallet", "summary": "One wallet's LP record", "description": "Everything the wallet board knows about one wallet, whether it is ranked or not: win rate, fees, profit, expected value per position, average invested / age / monthly profit and the 7-day / 30-day / all-time windows (`summary`); one row per UTC day on which a position ended, with the profit and the fees that landed on it (`history`; an open position counts its fees on the day it was last touched); the pools it provided to (`pools`, up to 60, by number of positions).\n\nThe figures use the board's row rules, so a wallet opened from `/lp/leaderboard` shows the same numbers: `unscored` says how many ledger positions were left out and why (each under the first reason that fits), and `ledger` counts every position, scored or not. `operator: true` = 500 or more scored positions, an account the board does not rank. `truncated: true` = the wallet holds more than 20,000 positions and the figures cover the newest 20,000.\n\n**Use it for**: a wallet page, \"is this LP worth following\", a PnL calendar.", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "Not a 0x address is `400 BAD_WALLET`." }, { "name": "chain", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad." }, { "name": "unit", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "usd", "native" ], "default": "usd" }, "description": "`native` = every money field of the answer in the chain's own coin (ETH on Robinhood Chain, MON on Monad; Arc's coin is USDC), each deposit, withdrawal and fee converted at the coin's price of its own hour, and live values at the price now. The fields keep their `…Usd` names; `unit` and `unitSymbol` in the answer say what they carry. The row rules (the $20 floor, the 20x bound) stay in dollars, so both units score the same positions. `503 UNIT_NOT_READY` while a chain's ledger is being rebuilt with these figures; another value is `400 BAD_UNIT`." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "unit": { "type": "string", "description": "`usd` or `native`: the unit of every money field in this answer.", "enum": [ "usd", "native" ] }, "unitSymbol": { "type": "string", "description": "`USD`, or the chain's coin (`ETH`, `MON`, `USDC`)." }, "summary": { "type": "object", "properties": { "positions": { "type": "integer", "description": "Scored positions." }, "open": { "type": "integer", "description": "" }, "closed": { "type": "integer", "description": "" }, "wins": { "type": "integer", "description": "" }, "winRatePct": { "type": [ "number", "null" ], "description": "" }, "pools": { "type": "integer", "description": "" }, "feesUsd": { "type": "number", "description": "" }, "profitUsd": { "type": "number", "description": "" }, "evUsd": { "type": [ "number", "null" ], "description": "Expected value per position." }, "avgAgeHours": { "type": [ "number", "null" ], "description": "" }, "avgInvestedUsd": { "type": [ "number", "null" ], "description": "" }, "avgMonthlyProfitUsd": { "type": [ "number", "null" ], "description": "Profit to date over the months since the first position, never less than one week." }, "windows": { "type": "object", "properties": { "d7": { "type": "object", "properties": { "positions": { "type": "integer", "description": "" }, "profitUsd": { "type": "number", "description": "" }, "feesUsd": { "type": "number", "description": "" } } }, "d30": { "type": "object", "properties": { "positions": { "type": "integer", "description": "" }, "profitUsd": { "type": "number", "description": "" }, "feesUsd": { "type": "number", "description": "" } } }, "all": { "type": "object", "properties": { "positions": { "type": "integer", "description": "" }, "profitUsd": { "type": "number", "description": "" }, "feesUsd": { "type": "number", "description": "" } } } } }, "firstTs": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "lastTs": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." } } }, "history": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "description": "YYYY-MM-DD, UTC" }, "profitUsd": { "type": "number", "description": "" }, "feesUsd": { "type": "number", "description": "" }, "positions": { "type": "integer", "description": "Positions that ended (or, open, were last touched) on the day." } } }, "description": "Oldest first; days with nothing are absent." }, "pools": { "type": "array", "items": { "type": "object", "properties": { "pool": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "token": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "anchor": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "positions": { "type": "integer", "description": "" }, "open": { "type": "integer", "description": "" }, "inUsd": { "type": "number", "description": "" }, "profitUsd": { "type": "number", "description": "" }, "feesUsd": { "type": "number", "description": "" }, "symbol": { "type": [ "string", "null" ], "description": "" }, "anchorSymbol": { "type": [ "string", "null" ], "description": "" }, "logo": { "type": [ "string", "null" ], "description": "" } } } }, "ledger": { "type": "object", "properties": { "positions": { "type": "integer", "description": "" }, "open": { "type": "integer", "description": "" }, "closed": { "type": "integer", "description": "" } }, "description": "Every position the ledger holds for the wallet." }, "unscored": { "type": "object", "properties": { "small": { "type": "integer", "description": "Under `minIn` dollars." }, "jit": { "type": "integer", "description": "Opened and closed inside a minute." }, "unreconciled": { "type": "integer", "description": "Far more dollars out than the index saw go in." }, "partial": { "type": "integer", "description": "Opened before the index started." }, "unlistedPool": { "type": "integer", "description": "On a pool the pool list hides as thin or suspect." } } }, "minIn": { "type": "number", "description": "" }, "truncated": { "type": "boolean", "description": "" }, "operator": { "type": "boolean", "description": "" }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "wallet": "0x5db28691cbfc2ceeca1d919f0749b64013c25432", "summary": { "positions": 2, "open": 0, "closed": 2, "wins": 1, "winRatePct": 50, "pools": 1, "feesUsd": 1473.5195824012221, "profitUsd": 898.4072651256388, "evUsd": 449.2036325628194, "avgAgeHours": 85.54625, "avgInvestedUsd": 2485.7135485602826, "avgMonthlyProfitUsd": 1220.1586855458952, "windows": { "d7": { "positions": 0, "profitUsd": 0, "feesUsd": 0 }, "d30": { "positions": 2, "profitUsd": 898.4072651256388, "feesUsd": 1473.5195824012221 }, "all": { "positions": 2, "profitUsd": 898.4072651256388, "feesUsd": 1473.5195824012221 } }, "firstTs": 1789922677, "lastTs": 1790521219 }, "history": [ { "day": "2026-09-22", "profitUsd": 1767.3683024312918, "feesUsd": 556.5679612124811, "positions": 1 }, { "day": "2026-09-27", "profitUsd": -868.961037305653, "feesUsd": 916.9516211887411, "positions": 1 } ], "pools": [ { "pool": "0xf53f02d9041d00bbd92235b4c902b9f350c554a8ed2dc64fa0a4585aac413f09", "token": "0x8faae5592b9acc27a79fca745c6b872adf514a5d", "anchor": "0x3600000000000000000000000000000000000000", "positions": 2, "open": 0, "inUsd": 4971.427097120565, "profitUsd": 898.4072651256388, "feesUsd": 1473.5195824012221, "symbol": "MURMUR", "anchorSymbol": "USDC", "logo": "https://cdn.dexscreener.com/cms/images/QUq-IqT1GLQNkxMx?width=800&height=800&quality=95&format=auto" } ], "ledger": { "positions": 2, "open": 0, "closed": 2 }, "unscored": { "small": 0, "jit": 0, "unreconciled": 0, "partial": 0, "unlistedPool": 0, "cluster": 0 }, "minIn": 20, "truncated": false, "operator": false, "updatedAt": 1791831176348 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lp/positions": { "get": { "tags": [ "Liquidity" ], "operationId": "lpPositions", "summary": "A wallet's positions", "description": "Every managed position a wallet holds or held: dollars in and out, fees collected, live value and uncollected fees (V3), in-range, PnL on the liquidity leg, age, and the JIT / unreconciled flags; with a summary (open, closed, wins, realized PnL, fees, open value).", "parameters": [ { "name": "chain", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad." }, { "name": "unit", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "usd", "native" ], "default": "usd" }, "description": "`native` = every money field of the answer in the chain's own coin (ETH on Robinhood Chain, MON on Monad; Arc's coin is USDC), each deposit, withdrawal and fee converted at the coin's price of its own hour, and live values at the price now. The fields keep their `…Usd` names; `unit` and `unitSymbol` in the answer say what they carry. The row rules (the $20 floor, the 20x bound) stay in dollars, so both units score the same positions. `503 UNIT_NOT_READY` while a chain's ledger is being rebuilt with these figures; another value is `400 BAD_UNIT`." }, { "name": "owner", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "closed", "all" ], "default": "all" }, "description": "" }, { "name": "token", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "Only positions holding this token." }, { "name": "pool", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "description": "Only positions in this pool." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 }, "description": "" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 20000, "default": 0 }, "description": "Rows to skip, newest first: page through a wallet's closed positions. Out of range is `400 BAD_OFFSET`." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "owner": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "status": { "type": "string", "description": "" }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/LpPosition" } }, "summary": { "type": "object", "properties": { "open": { "type": "integer", "description": "" }, "closed": { "type": "integer", "description": "" }, "wins": { "type": "integer", "description": "" }, "winRatePct": { "type": [ "number", "null" ], "description": "" }, "realizedPnlUsd": { "type": "number", "description": "" }, "feesUsd": { "type": "number", "description": "" }, "openValueUsd": { "type": "number", "description": "" } } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "owner": "0xb145400da27a2497d9fc2cd5621f2bfd37617af4", "status": "all", "positions": [], "summary": { "open": 0, "closed": 0, "wins": 0, "winRatePct": null, "realizedPnlUsd": 0, "feesUsd": 0, "openValueUsd": 0 }, "updatedAt": 1789891871406 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lp/position/{chain}/{manager}/{id}": { "get": { "tags": [ "Liquidity" ], "operationId": "lpPosition", "summary": "One position", "description": "A position by its NFT: the valued row, its events, and a hold-instead comparison (what the same tokens would be worth unpooled). `native` carries the same position in the chain's own coin (`nativeSymbol`): what went in, came out and was paid as fees, each event converted at the coin's price of its own hour, and the value and waiting fees at the coin's price now. It is null while the chain's ledger has no figures in its coin.", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "description": "" }, { "name": "manager", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "Position manager contract." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,30}$" }, "description": "Token id." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "position": { "$ref": "#/components/schemas/LpPosition" }, "events": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "description": "" }, "usd": { "type": "number", "description": "" }, "feeUsd": { "type": "number", "description": "" }, "tokenAmt": { "type": "number", "description": "" }, "anchorAmt": { "type": "number", "description": "" }, "tx": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$", "description": "Transaction hash." }, "ts": { "type": "integer", "description": "Unix time, seconds, UTC." }, "block": { "type": "integer", "description": "" } } } }, "hold": { "type": "object", "properties": { "tokenIn": { "type": "number", "description": "" }, "anchorIn": { "type": "number", "description": "" }, "priceNowUsd": { "type": [ "number", "null" ], "description": "" }, "holdValueUsd": { "type": [ "number", "null" ], "description": "" }, "lpValueUsd": { "type": [ "number", "null" ], "description": "" }, "lpVsHoldUsd": { "type": [ "number", "null" ], "description": "" }, "basis": { "type": "string", "description": "" } } }, "native": { "type": [ "object", "null" ], "properties": { "in": { "type": "number", "description": "In, in the coin." }, "out": { "type": "number", "description": "Out, in the coin." }, "fees": { "type": "number", "description": "Fees paid out, in the coin." }, "value": { "type": [ "number", "null" ], "description": "Value now at the coin's price now; null for a closed position." }, "uncollected": { "type": [ "number", "null" ], "description": "Fees waiting, at the coin's price now." }, "pnl": { "type": [ "number", "null" ], "description": "Closed: out + fees − in. Open: value + waiting + out + fees − in." }, "pnlPct": { "type": [ "number", "null" ], "description": "`pnl` in percent of `in`." } } }, "nativeSymbol": { "type": [ "string", "null" ], "description": "The chain's coin (`ETH`, `MON`, `USDC`); null with `native`." }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing at this identity (`NOT_FOUND`, `UNKNOWN_TOKEN`, `NO_ROUTE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lp/leaderboard": { "get": { "tags": [ "Liquidity" ], "operationId": "lpLeaderboard", "summary": "Best liquidity providers", "description": "LP wallets from the ledger: win rate, fees, pools, expected value per position, average age / invested / monthly profit, profit over 7 / 30 days / all time, the last seven days of profit and what they provide to. Every filter bound is inclusive; unset = off.\n\nThe board is **fee-checked**: a wallet whose profit is positive while the fees it collected are under a tenth of that profit made it on the token's price (liquidity on a launch pulled into the buyers), not by providing, and is left out; `hidden` counts them and `all=1` keeps them in. The check reads the window the board ranks by (`profit_7d` → 7 days, `profit_30d` → 30 days, every other sort → all time). Every sort ranks inside the 400 most profitable wallets of its window that pass the filters; `total` is that count. A window sort lists only wallets with a position that ended or was touched in the window.", "parameters": [ { "name": "chain", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad." }, { "name": "unit", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "usd", "native" ], "default": "usd" }, "description": "`native` = every money field of the answer in the chain's own coin (ETH on Robinhood Chain, MON on Monad; Arc's coin is USDC), each deposit, withdrawal and fee converted at the coin's price of its own hour, and live values at the price now. The fields keep their `…Usd` names; `unit` and `unitSymbol` in the answer say what they carry. The row rules (the $20 floor, the 20x bound) stay in dollars, so both units score the same positions. `503 UNIT_NOT_READY` while a chain's ledger is being rebuilt with these figures; another value is `400 BAD_UNIT`." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "profit", "profit_7d", "profit_30d", "win_rate", "avg_age", "positions", "pools", "ev", "avg_invested", "monthly_profit", "fees", "last_activity" ], "default": "profit" }, "description": "`profit` = all time. An unknown value is `400 BAD_SORT`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 48 }, "description": "" }, { "name": "all", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "0", "1" ] }, "description": "1 = keep the wallets the fee check leaves out." }, { "name": "minIn", "in": "query", "required": false, "schema": { "type": "number", "default": 20 }, "description": "Ignore positions under this many dollars." }, { "name": "minPositions", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" }, { "name": "minAgeHours", "in": "query", "required": false, "schema": { "type": "number" }, "description": "" }, { "name": "minWinRate", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Percent." }, { "name": "minEv", "in": "query", "required": false, "schema": { "type": "number" }, "description": "" }, { "name": "minProfit", "in": "query", "required": false, "schema": { "type": "number" }, "description": "" }, { "name": "minMonthly", "in": "query", "required": false, "schema": { "type": "number" }, "description": "" }, { "name": "maxFirstTs", "in": "query", "required": false, "schema": { "type": "integer", "description": "Unix time, seconds, UTC." }, "description": "Only wallets active before this time." }, { "name": "lastActiveDays", "in": "query", "required": false, "schema": { "type": "number" }, "description": "" }, { "name": "minFees", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Fees collected, all time." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "sort": { "type": "string", "description": "" }, "minIn": { "type": "number", "description": "" }, "filters": { "type": "object", "additionalProperties": true, "description": "" }, "feeCheck": { "type": "boolean", "description": "The fee check was applied." }, "hidden": { "type": "integer", "description": "Wallets passing the filters that the fee check left out." }, "total": { "type": "integer", "description": "Wallets the board ranks." }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/LpLeaderRow" } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "sort": "profit", "minIn": 20, "filters": {}, "rows": [ { "wallet": "0x50550bf5c09b38e5c574c190cef88b859694a44a", "winRatePct": 75, "feesUsd": 13516.447234, "pools": 5, "evUsd": 55.95264399437404, "avgAgeHours": 53.940039682539684, "avgInvestedUsd": 8802.035202296884, "avgMonthlyProfitUsd": 54574.16597590998, "windows": { "d7": { "positions": 7, "profitUsd": 13643.541493977495 }, "d30": { "positions": 7, "profitUsd": 13643.541493977495 }, "all": { "positions": 7, "profitUsd": 13643.541493977495 } }, "open": 3, "closed": 4, "wins": 3, "firstTs": 1789524227, "lastTs": 1789695131, "daily": [ { "day": "2026-09-14", "profitUsd": 0 }, { "day": "2026-09-15", "profitUsd": 0 } ], "tokens": [ { "address": "0xbc43ce8dec648ea298c4275559b81d6261c90b67", "symbol": "TOLLY", "logo": "https://cdn.dexscreener.com/cms/images/LquZIzWeLJoeUE4x?width=800&height=800&quality=95&format=auto", "inUsd": 56621.88931640096, "positions": 4 }, { "address": "0xa163d7624da3b5d9182c50eab5b8cd247ae861bb", "symbol": "Minara", "logo": "https://static.minara.ai/minara-fun/token-logos/1a464bd3cbb6e0db661556f18b784344754785730da3bf9752e383e7e5a2605a.png", "inUsd": 13303.485575872332, "positions": 1 } ] }, { "wallet": "0x4705173e07dc8acde8a826a96883848d0a4bb2cf", "winRatePct": null, "feesUsd": 12121.658648, "pools": 1, "evUsd": null, "avgAgeHours": 50.736111111111114, "avgInvestedUsd": 1585.3021168837654, "avgMonthlyProfitUsd": 48486.634592, "windows": { "d7": { "positions": 5, "profitUsd": 12121.658648 }, "d30": { "positions": 5, "profitUsd": 12121.658648 }, "all": { "positions": 5, "profitUsd": 12121.658648 } }, "open": 5, "closed": 0, "wins": 0, "firstTs": 1789644774, "lastTs": 1789742574, "daily": [ { "day": "2026-09-14", "profitUsd": 0 }, { "day": "2026-09-15", "profitUsd": 0 } ], "tokens": [ { "address": "0x2ba0f44bdfc17fba30eda9cdbecb908ca45b043b", "symbol": "CRCL", "logo": "https://cdn.dexscreener.com/cms/images/Y-swLma-R46hqFvc?width=800&height=800&quality=95&format=auto", "inUsd": 7926.5105844188265, "positions": 5 } ] } ], "updatedAt": 1789891861738 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lp/events": { "get": { "tags": [ "Liquidity" ], "operationId": "lpEvents", "summary": "Liquidity events", "description": "Adds, removes and fee collects on one token, wallet or pool, newest first, each valued in dollars where the pool has an anchor side. One of `token`, `wallet` or `pool` is required.", "parameters": [ { "name": "chain", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad." }, { "name": "token", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" }, { "name": "wallet", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" }, { "name": "pool", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "description": "" }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "add", "remove", "collect" ] }, "description": "" }, { "name": "minUsd", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 40 }, "description": "" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/LpEvent" } }, "limit": { "type": "integer", "description": "" }, "offset": { "type": "integer", "description": "" }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "events": [ { "tx": "0x74acfa695f6ea11770a2356a49b750c9c5e0685a8ee106ebfae67ccd049d4ba6", "logIndex": 20, "pool": "0xf53f02d9041d00bbd92235b4c902b9f350c554a8ed2dc64fa0a4585aac413f09", "dex": "uniswap_v4", "kind": "remove", "wallet": "0xc85d3ed2dfa128888e658e3a947f24bfa96db654", "token": "0x8faae5592b9acc27a79fca745c6b872adf514a5d", "tokenAmt": 0, "anchor": "0x3600000000000000000000000000000000000000", "anchorAmt": 90.769723, "usd": 90.769723, "priced": true, "tickLower": 352440, "tickUpper": 354519, "block": 21802531, "ts": 1789888952 }, { "tx": "0x74acfa695f6ea11770a2356a49b750c9c5e0685a8ee106ebfae67ccd049d4ba6", "logIndex": 18, "pool": "0xf53f02d9041d00bbd92235b4c902b9f350c554a8ed2dc64fa0a4585aac413f09", "dex": "uniswap_v4", "kind": "remove", "wallet": "0xc85d3ed2dfa128888e658e3a947f24bfa96db654", "token": "0x8faae5592b9acc27a79fca745c6b872adf514a5d", "tokenAmt": 0, "anchor": "0x3600000000000000000000000000000000000000", "anchorAmt": 72.615778, "usd": 72.615778, "priced": true, "tickLower": 350361, "tickUpper": 352440, "block": 21802531, "ts": 1789888952 } ], "limit": 2, "offset": 0, "updatedAt": 1789891870679 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lp/token/{address}": { "get": { "tags": [ "Liquidity" ], "operationId": "lpToken", "summary": "Liquidity flow for a token", "description": "Adds, removes and net dollars over the window, one-sided (token-only) events counted but not valued, just-in-time liquidity (same-transaction add and remove) called out so the totals read right, the top providers and the pools by net flow.", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" }, { "name": "chain", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad." }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 720, "default": 24 }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "hours": { "type": "integer", "description": "" }, "adds": { "type": "integer", "description": "" }, "addUsd": { "type": "number", "description": "" }, "removes": { "type": "integer", "description": "" }, "removeUsd": { "type": "number", "description": "" }, "netUsd": { "type": "number", "description": "" }, "tokenOnlyAdds": { "type": "integer", "description": "" }, "tokenOnlyRemoves": { "type": "integer", "description": "" }, "jitTxs": { "type": "integer", "description": "" }, "jitUsd": { "type": "number", "description": "" }, "providers": { "type": "integer", "description": "" }, "top": { "type": "array", "items": { "type": "object", "properties": { "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "netUsd": { "type": "number", "description": "" }, "addedUsd": { "type": "number", "description": "" }, "removedUsd": { "type": "number", "description": "" }, "events": { "type": "integer", "description": "" }, "lastTs": { "type": "integer", "description": "Unix time, seconds, UTC." } } } }, "pools": { "type": "array", "items": { "type": "object", "properties": { "pool": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "dex": { "type": "string", "description": "" }, "netUsd": { "type": "number", "description": "" }, "events": { "type": "integer", "description": "" } } } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "token": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0", "hours": 24, "adds": 200, "addUsd": 274228.1437317083, "removes": 176, "removeUsd": 2291418.4063887238, "netUsd": -2017190.2626570156, "tokenOnlyAdds": 5, "tokenOnlyRemoves": 30, "jitTxs": 18, "jitUsd": 39153.40135616365, "providers": 51, "top": [ { "wallet": "0xa77401a1640e4f090fd5d08b7350b59d6a99b0fd", "netUsd": -2064877.6495731266, "addedUsd": 0, "removedUsd": 2063818.8216671266, "events": 2, "lastTs": 1789845091 }, { "wallet": "0x08d0d1d9d58675fea6e36670d85a9e8dad89f465", "netUsd": 21439.05777238525, "addedUsd": 21439.05777238525, "removedUsd": 0, "events": 1, "lastTs": 1789817213 } ], "pools": [ { "pool": "0x82916bee18fcef517b26c72d7cb5f13694e1db41", "dex": "uniswap_v3", "netUsd": -2065710.8817895816, "events": 88 }, { "pool": "0xd945caee4635bcd7fb8a9fa74dc1d0c4c1472782", "dex": "slipstream_fork", "netUsd": 44581.441725988414, "events": 282 } ], "updatedAt": 1789891863259 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lp/token/{address}/pools": { "get": { "tags": [ "Liquidity" ], "operationId": "lpTokenPools", "summary": "A token's pools by health", "description": "The token's pools ranked by the 0–100 health score with the reasons behind it, and launch facts on Arc (launcher, its share of the liquidity, when it last pulled).", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" }, { "name": "chain", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "pools": { "type": "array", "items": { "type": "object", "properties": { "pool": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "dex": { "type": "string", "description": "" }, "kind": { "type": "string", "description": "" }, "feeBps": { "type": [ "number", "null" ], "description": "" }, "tvlUsd": { "type": [ "number", "null" ], "description": "" }, "vol24h": { "type": "number", "description": "" }, "aprPct": { "type": [ "number", "null" ], "description": "" }, "score": { "type": "integer", "description": "" }, "reasons": { "type": "array", "items": { "type": "string" } }, "launch": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Launch facts (see /lp/pools/{pool})." } } } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "token": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0", "pools": [ { "pool": "0xd945caee4635bcd7fb8a9fa74dc1d0c4c1472782", "dex": "slipstream_fork", "kind": "clmm", "feeBps": 6, "tvlUsd": 570213.05, "vol24h": 772749.320668, "aprPct": 29.678749237025, "score": 75, "reasons": [], "launch": null }, { "pool": "0xc955cbfb9d03cde6f78901a81740264f895b9c00025beb9115cf2d7b86b3ee5a", "dex": "uniswap_v4", "kind": "v4", "feeBps": 30, "tvlUsd": 14896.68, "vol24h": 13956.785425999999, "aprPct": 102.59118166913699, "score": 47, "reasons": [ "the launcher holds 100% of the liquidity added" ], "launch": { "launcher": "0x6049c9a0e26405c0985f9e3685c87d0ae917f82b", "launcherName": "Uniswap Liquidity Launcher", "creator": "0x8007221ab6bdb20496eb74d038cbc5d590d1bea9", "hooks": null, "launchedTs": 1789559316, "launcherLpAddedUsd": 69592.12438223744, "totalLpAddedUsd": 69592.12438223744, "launcherSharePct": 100, "launcherLastRemoveTs": 1789838701, "launcherRemovedUsd": 51498.944581131305 } } ], "updatedAt": 1789891866065 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lp/plan": { "get": { "tags": [ "Liquidity" ], "operationId": "lpPlan", "summary": "Plan a position", "description": "Range bands for a token from its own volatility (tight / balanced / wide, with the share of the last seven days each range would have stayed inside) and each profile backtested on Chord's candles against holding — fees, impermanent loss, exits, time in range. Needs at least 24 hourly candles and an anchored pool (`404 NOT_ENOUGH_HISTORY` otherwise). `young: true` means under two days of candles — the bands are a launch's noise.", "parameters": [ { "name": "chain", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad." }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" }, { "name": "amountUsd", "in": "query", "required": false, "schema": { "type": "number", "minimum": 1, "default": 1000 }, "description": "" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 7 }, "description": "Backtest window." }, { "name": "pool", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "description": "Pin a pool; default = the token's best anchored pool." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amountUsd": { "type": "number", "description": "" }, "days": { "type": "integer", "description": "" }, "bands": { "type": "object", "properties": { "priceUsd": { "type": "number", "description": "" }, "hourlyVolPct": { "type": "number", "description": "" }, "dailyVolPct": { "type": "number", "description": "" }, "candles": { "type": "integer", "description": "" }, "young": { "type": "boolean", "description": "" }, "profiles": { "type": "array", "items": { "type": "object", "properties": { "profile": { "type": "string", "enum": [ "tight", "balanced", "wide" ] }, "horizonHours": { "type": "integer", "description": "" }, "lower": { "type": "number", "description": "" }, "upper": { "type": "number", "description": "" }, "widthPct": { "type": "number", "description": "" }, "last7dInsidePct": { "type": "number", "description": "" } } } }, "histogram": { "type": "array", "items": { "type": "object", "properties": { "lo": { "type": "number", "description": "" }, "hi": { "type": "number", "description": "" }, "hours": { "type": "integer", "description": "" } } }, "description": "Where the price spent its hours." } } }, "sims": { "type": "array", "items": { "type": "object", "properties": { "profile": { "type": "string", "description": "" }, "lower": { "type": "number", "description": "" }, "upper": { "type": "number", "description": "" }, "sim": { "$ref": "#/components/schemas/SimResult" } } } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 5042, "token": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0", "amountUsd": 1000, "days": 7, "bands": { "priceUsd": 80418.25, "hourlyVolPct": 0.44, "dailyVolPct": 2.1, "candles": 104, "young": false, "profiles": [ { "profile": "tight", "horizonHours": 24, "lower": 78711.94, "upper": 82161.56, "widthPct": 2.2, "last7dInsidePct": 42 }, { "profile": "balanced", "horizonHours": 72, "lower": 76059.95, "upper": 85026.29, "widthPct": 5.7, "last7dInsidePct": 82 } ], "histogram": [ { "lo": 73301.06, "hi": 73799.8, "hours": 1 }, { "lo": 73799.8, "hi": 74301.94, "hours": 0 } ] }, "sims": [ { "profile": "tight", "lower": 78711.94, "upper": 82161.56, "sim": { "pool": "0x82916bee18fcef517b26c72d7cb5f13694e1db41", "dex": "uniswap_v3", "feeBps": 1, "tvlUsd": 11239238.75, "days": 7, "hours": 104, "hoursInRange": 1, "inRangePct": 1, "exits": 1, "lower": 71745.77, "upper": 74890.09, "unreliable": null, "entryPrice": 73301.06, "exitPrice": 80418.25, "priceChangePct": 9.7, "feesUsd": 0.01, "lpValueEndUsd": 1005.39, "holdValueEndUsd": 1048.55, "ilUsd": -43.16, "netVsHoldUsd": -43.15, "totalReturnUsd": 5.4, "totalReturnPct": 0.54, "feeAprPct": 0.1, "capitalEfficiency": 50, "shareOfPoolPct": 0.443, "note": "Backtest on the last 7 days of Chord's own candles and this pool's hourly volume at today's TVL — what would have happened, not what will." } }, { "profile": "balanced", "lower": 76059.95, "upper": 85026.29, "sim": { "pool": "0x82916bee18fcef517b26c72d7cb5f13694e1db41", "dex": "uniswap_v3", "feeBps": 1, "tvlUsd": 11239238.75, "days": 7, "hours": 104, "hoursInRange": 53, "inRangePct": 51, "exits": 1, "lower": 69328.48, "upper": 77501.28, "unreliable": null, "entryPrice": 73301.06, "exitPrice": 80418.25, "priceChangePct": 9.7, "feesUsd": 3.03, "lpValueEndUsd": 1014.13, "holdValueEndUsd": 1048.55, "ilUsd": -34.42, "netVsHoldUsd": -31.39, "totalReturnUsd": 17.16, "totalReturnPct": 1.72, "feeAprPct": 15.8, "capitalEfficiency": 36.4, "shareOfPoolPct": 0.323, "note": "Backtest on the last 7 days of Chord's own candles and this pool's hourly volume at today's TVL — what would have happened, not what will." } } ], "updatedAt": 1789891866541 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing at this identity (`NOT_FOUND`, `UNKNOWN_TOKEN`, `NO_ROUTE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lp/simulate": { "get": { "tags": [ "Liquidity" ], "operationId": "lpSimulate", "summary": "Backtest one range", "description": "One explicit price range replayed over the last `days` of candles in the token's pool: fees earned at the pool's real tier and the position's share, impermanent loss, exits, LP value versus hold.", "parameters": [ { "name": "chain", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad." }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" }, { "name": "lower", "in": "query", "required": true, "schema": { "type": "number", "exclusiveMinimum": 0 }, "description": "Lower price, USD." }, { "name": "upper", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Upper price, USD (> lower)." }, { "name": "amountUsd", "in": "query", "required": false, "schema": { "type": "number", "minimum": 1, "default": 1000 }, "description": "" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 7 }, "description": "" }, { "name": "pool", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, { "$ref": "#/components/schemas/SimResult" } ] } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing at this identity (`NOT_FOUND`, `UNKNOWN_TOKEN`, `NO_ROUTE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lp/watch": { "get": { "tags": [ "Liquidity" ], "operationId": "lpWatchStatus", "summary": "Watch state and alert inbox", "description": "Whether the wallet's positions are watched, how many Telegram chats receive its alerts, the alert thresholds, the last alerts, and the pools on its watchlist.", "parameters": [ { "name": "chain", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "description": "Chain id: `5042` Arc · `4663` Robinhood Chain · `143` Monad." }, { "name": "wallet", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "watched": { "type": "boolean", "description": "" }, "telegramChats": { "type": "integer", "description": "" }, "feeBarUsd": { "type": "number", "description": "Alert when uncollected fees pass this." }, "drainPct": { "type": "number", "description": "Alert when a pool loses this share of its liquidity." }, "telegramBot": { "type": [ "string", "null" ], "description": "Bot username for the deep link." }, "alerts": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "description": "" }, "chain": { "type": "integer", "description": "" }, "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "manager": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenId": { "type": "string", "description": "" }, "pool": { "type": [ "string", "null" ], "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "token": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "symbol": { "type": [ "string", "null" ], "description": "" }, "text": { "type": "string", "description": "" }, "usd": { "type": [ "number", "null" ], "description": "" }, "ts": { "type": "integer", "description": "Unix time, seconds, UTC." }, "href": { "type": [ "string", "null" ], "description": "Where the wallet's owner acts on the alert: the position's page for a mark, the pool with the same range for a followed wallet's new position." } }, "required": [ "kind", "chain", "wallet", "text", "ts" ] } }, "pools": { "type": "array", "items": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." } }, "marks": { "type": "object", "description": "Take-profit / stop-loss marks by `:`.", "additionalProperties": { "type": "object", "properties": { "tpPct": { "type": [ "number", "null" ], "description": "Take-profit: PnL in percent of the dollars that went in, above 0." }, "slPct": { "type": [ "number", "null" ], "description": "Stop-loss: the same, between -100 and 0." }, "at": { "type": "integer", "description": "Unix time, seconds, UTC." }, "unit": { "type": "string", "description": "Present, and `native`, when the percent is counted in the chain's own coin; absent = in dollars.", "enum": [ "native" ] } } } }, "following": { "type": "array", "items": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Liquidity" ], "operationId": "lpWatch", "summary": "Watch a wallet's positions", "description": "Turns on in-app alerts for the wallet's positions (out of range, fees to collect, pool draining) and returns a one-hour Telegram deep link that routes the same alerts to a chat.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." } }, "required": [ "chain", "wallet" ] }, "example": { "chain": 5042, "wallet": "0xb145400da27a2497d9fc2cd5621f2bfd37617af4" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "watched": { "type": "boolean", "description": "" }, "telegramChats": { "type": "integer", "description": "" }, "feeBarUsd": { "type": "number", "description": "" }, "drainPct": { "type": "number", "description": "" }, "code": { "type": "string", "description": "" }, "tgLink": { "type": [ "string", "null" ], "description": "`https://t.me/?start=lp_`, valid one hour." } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Liquidity" ], "operationId": "lpUnwatch", "summary": "Stop watching a wallet", "description": "", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." } }, "required": [ "chain", "wallet" ] }, "example": { "chain": 5042, "wallet": "0xb145400da27a2497d9fc2cd5621f2bfd37617af4" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "watched": { "type": "boolean", "const": false } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lp/watch/pool": { "post": { "tags": [ "Liquidity" ], "operationId": "lpWatchPool", "summary": "Watch a pool", "description": "Adds a pool to the wallet's watchlist — drain alerts without holding a position.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "pool": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." } }, "required": [ "chain", "wallet", "pool" ] }, "example": { "chain": 5042, "wallet": "0xb145400da27a2497d9fc2cd5621f2bfd37617af4", "pool": "0xf53f02d9041d00bbd92235b4c902b9f350c554a8ed2dc64fa0a4585aac413f09" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "pools": { "type": "array", "items": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." } } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Liquidity" ], "operationId": "lpUnwatchPool", "summary": "Stop watching a pool", "description": "", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "pool": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." } }, "required": [ "chain", "wallet", "pool" ] }, "example": { "chain": 5042, "wallet": "0xb145400da27a2497d9fc2cd5621f2bfd37617af4", "pool": "0xf53f02d9041d00bbd92235b4c902b9f350c554a8ed2dc64fa0a4585aac413f09" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "pools": { "type": "array", "items": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." } } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lp/watch/mark": { "post": { "tags": [ "Liquidity" ], "operationId": "lpWatchMark", "summary": "Set a take-profit / stop-loss alert on a position", "description": "A mark on one open position: when its PnL (percent of the dollars that went in, live value and fees included) crosses the take-profit or the stop-loss, one alert goes to the wallet's inbox and linked Telegram chats with a link to the position, and the mark is removed. It is an alert, not an order: nothing is signed or closed for the wallet. Both values null removes the mark. The wallet is watched from then on; positions are checked every two minutes. A mark with `unit: \"native\"` waits (it never falls back to dollars) while the chain has no figures in its coin.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "manager": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenId": { "type": "string", "description": "The position's id on its manager, decimal." }, "tpPct": { "type": [ "number", "null" ], "description": "Above 0, at most 10000." }, "slPct": { "type": [ "number", "null" ], "description": "Between -100 and 0." }, "unit": { "type": "string", "description": "`native` = count the percent in the chain's own coin: what went in and what the position is worth now, both in ETH / MON (`native` of `GET /lp/position`). The coin moving against the dollar then crosses nothing. Default `usd`.", "enum": [ "usd", "native" ] } }, "required": [ "chain", "wallet", "manager", "tokenId" ] }, "example": { "chain": 4663, "wallet": "0xb145400da27a2497d9fc2cd5621f2bfd37617af4", "manager": "0x58daec3116aae6d93017baaea7749052e8a04fa7", "tokenId": "2990642", "tpPct": 20, "slPct": -15 } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "marks": { "type": "object", "additionalProperties": { "type": "object", "properties": { "tpPct": { "type": [ "number", "null" ], "description": "Take-profit: PnL in percent of the dollars that went in, above 0." }, "slPct": { "type": [ "number", "null" ], "description": "Stop-loss: the same, between -100 and 0." }, "at": { "type": "integer", "description": "Unix time, seconds, UTC." }, "unit": { "type": "string", "description": "Present, and `native`, when the percent is counted in the chain's own coin; absent = in dollars.", "enum": [ "native" ] } } } } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lp/watch/follow": { "post": { "tags": [ "Liquidity" ], "operationId": "lpWatchFollow", "summary": "Follow a liquidity provider", "description": "Alerts for `wallet` when `target` opens or closes a position, from now on (a follow does not replay the wallet's past). An \"opened\" alert links to the same pool with the same range; nothing is copied for the wallet. At most 10 followed wallets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "enum": [ 5042, 4663, 143 ] }, "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "target": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "on": { "type": "boolean", "description": "false = stop following. Default true." } }, "required": [ "chain", "wallet", "target" ] }, "example": { "chain": 4663, "wallet": "0xb145400da27a2497d9fc2cd5621f2bfd37617af4", "target": "0x5b0dbd62f7639bef7a1ae1c4ff9408105946a9b9", "on": true } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "following": { "type": "array", "items": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." } } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lp/status": { "get": { "tags": [ "Liquidity" ], "operationId": "lpStatus", "summary": "Liquidity lane state", "description": "Per-chain cursors, heads, last tick, pool-stat floors and position counts for the liquidity indexer — the freshness check for everything under `/lp`.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Lane state per chain (`lanes`, `pools`, `positions`)." }, "example": { "enabled": true, "chains": [ 5042, 4663 ], "lanes": { "143": { "cursor": 106412087, "head": 106412087, "chunk": 4000, "rows": 2, "lastTick": 1789891861000, "last": { "logs": 0, "rows": 0, "unknownPools": 0, "resolved": 0, "nonAnchored": 0, "noDecimals": 0, "noRate": 0, "noSqrt": 0, "tokenOnly": 0, "managed": 0, "collects": 0, "transfers": 0 }, "tickStartedAt": 1789891860977, "attrib": { "txs": 0, "set": 0, "floor": 1789891861, "idle": true, "at": 1789891861000 }, "behind": 0, "running": true }, "4663": { "cursor": 67785681, "head": 67785681, "chunk": 4000, "rows": 1322, "lastTick": 1789891861864, "last": { "logs": 115, "rows": 24, "unknownPools": 0, "resolved": 3, "nonAnchored": 44, "noDecimals": 0, "noRate": 0, "noSqrt": 0, "tokenOnly": 3, "managed": 19, "collects": 11, "transfers": 10 }, "tickStartedAt": 1789891861137, "attrib": { "txs": 0, "set": 0, "floor": 1789891861, "idle": true, "at": 1789891861866 }, "behind": 0, "running": true }, "5042": { "cursor": 21808258, "head": 21808258, "chunk": 4000, "rows": 77, "lastTick": 1789891858995, "last": { "logs": 3, "rows": 2, "unknownPools": 2, "resolved": 0, "nonAnchored": 0, "noDecimals": 0, "noRate": 0, "noSqrt": 0, "tokenOnly": 0, "managed": 1, "collects": 1, "transfers": 2 }, "tickStartedAt": 1789891858105, "attrib": { "txs": 300, "set": 0, "floor": 1789538828, "idle": false, "at": 1789891860035 }, "behind": 0, "running": true } }, "pools": { "143": { "floor": 1789146000, "tvlRows": 164, "hourlyRows": 14539 }, "4663": { "floor": 1789146000, "tvlRows": 879, "hourlyRows": 154120 }, "5042": { "floor": 1789146000, "tvlRows": 1816, "hourlyRows": 245072 } }, "positions": { "143": { "cursor": "106411386:64", "positions": 982, "open": 326 }, "4663": { "cursor": "67785366:7", "positions": 161730, "open": 44557 }, "5042": { "cursor": "21808179:20", "positions": 249663, "open": 195886 } } } } } } } } }, "/points/rules": { "get": { "tags": [ "Points" ], "operationId": "pointsRules", "summary": "Points program rules", "description": "Season, current week, points per dollar, the weekly pool, the daily cap, streak multipliers, referral bonuses and the tiers — and the plain-English rules of what counts. Only swaps executed through Chord on Arc score.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "season": { "type": "integer", "description": "" }, "seasonStart": { "type": "integer", "description": "Unix time, seconds, UTC." }, "currentWeek": { "type": "integer", "description": "" }, "weekLengthSec": { "type": "integer", "description": "" }, "pointsPerUsd": { "type": "number", "description": "" }, "minTradeUsd": { "type": "number", "description": "" }, "weekPool": { "type": "number", "description": "" }, "dayCapUsd": { "type": "number", "description": "" }, "referredBonusPct": { "type": "number", "description": "" }, "referralBonusPct": { "type": "number", "description": "" }, "streak": { "type": "array", "items": { "type": "object", "properties": { "days": { "type": "integer", "description": "" }, "multiplier": { "type": "number", "description": "" } } } }, "counts": { "type": "string", "description": "" }, "size": { "type": "string", "description": "" }, "pool": { "type": "string", "description": "" }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "" }, "topRanks": { "type": [ "integer", "null" ], "description": "" }, "topPct": { "type": [ "number", "null" ], "description": "" }, "note": { "type": "string", "description": "" } } } }, "provisional": { "type": "string", "description": "" } } }, "example": { "chain": 5042, "season": 1, "seasonStart": 1789516800, "currentWeek": 1, "weekLengthSec": 604800, "pointsPerUsd": 0.1, "minTradeUsd": 1, "weekPool": 1000000, "dayCapUsd": 50000, "referredBonusPct": 10, "referralBonusPct": 10, "streak": [ { "days": 5, "multiplier": 1.25 }, { "days": 3, "multiplier": 1.1 } ], "counts": "Swaps executed through Chord on Arc (chain 5042). Swaps made elsewhere on Arc, or on any other chain, do not count.", "size": "The dollar size of the trade as priced by Chord's own index (one route leg, never the sum of hops).", "pool": "Each week a fixed pool of points is split among traders in proportion to their weighted volume. Your points for a week settle when the week closes.", "tiers": [ { "name": "Challenger", "topRanks": 10, "topPct": null, "note": "top 10 of the season" }, { "name": "Diamond", "topRanks": null, "topPct": 1, "note": "top 1% of scored wallets" } ], "provisional": "Points are provisional until the week closes and can be voided for wash trading or self-dealing. Routers, bots and relayers are never scored." } } } } } } }, "/points/leaderboard": { "get": { "tags": [ "Points" ], "operationId": "pointsLeaderboard", "summary": "Weekly or season leaderboard", "description": "Wallets ranked by points for one week or the whole season, with base points, referral and streak bonuses, volume, trades, days active and tier. `503 NOT_ENABLED` while the program is off on the deployment.", "parameters": [ { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "week", "season" ], "default": "week" }, "description": "" }, { "name": "week", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Week number or `current`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "season": { "type": "integer", "description": "" }, "scope": { "type": "string", "description": "" }, "week": { "type": [ "integer", "null" ], "description": "" }, "weekBounds": { "type": [ "object", "null" ], "properties": { "from": { "type": "integer", "description": "Unix time, seconds, UTC." }, "to": { "type": "integer", "description": "Unix time, seconds, UTC." } } }, "seasonStart": { "type": "integer", "description": "Unix time, seconds, UTC." }, "currentWeek": { "type": "integer", "description": "" }, "weekPool": { "type": "number", "description": "" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer", "description": "" }, "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "points": { "type": "number", "description": "" }, "basePoints": { "type": "number", "description": "" }, "referralBonus": { "type": "number", "description": "" }, "streakBonus": { "type": "number", "description": "" }, "volumeUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "daysActive": { "type": "integer", "description": "" }, "tier": { "type": [ "string", "null" ], "description": "" }, "lastTradeTs": { "type": "integer", "description": "Unix time, seconds, UTC." } } } }, "totalWallets": { "type": "integer", "description": "" }, "totalPoints": { "type": "number", "description": "" }, "totalVolumeUsd": { "type": "number", "description": "" }, "indexedToBlock": { "type": [ "integer", "null" ], "description": "" }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/points/wallet/{address}": { "get": { "tags": [ "Points" ], "operationId": "pointsWallet", "summary": "One wallet's standing", "description": "Season and current-week points, rank, tier and volume for a wallet.", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`{ chain, season, wallet, seasonStart, currentWeek, weekPool, season_: {points, basePoints, referralBonus, streakBonus, volumeUsd, trades, rank, tier, totalWallets}, week: {…} }`" } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ask/status": { "get": { "tags": [ "Ask agent" ], "operationId": "askStatus", "summary": "Is the analyst on", "description": "Whether Ask is enabled, whether guest sessions are open, and today's token budget.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "" }, "chain": { "type": "integer", "const": 5042 }, "guest": { "type": "boolean", "description": "" }, "privy": { "type": "boolean", "description": "The server accepts Privy sign-in (the Ask wallet)" }, "budget": { "type": "object", "properties": { "used": { "type": "integer", "description": "" }, "total": { "type": "integer", "description": "" } } } } }, "example": { "enabled": true, "chain": 5042, "guest": true, "budget": { "used": 41707, "total": 4000000 } } } } } } } }, "/ask": { "post": { "tags": [ "Ask agent" ], "operationId": "ask", "summary": "Ask the analyst", "description": "Chord's analyst over the Arc index and the router — 40+ tools (trending, a token's flow, holders and risk, support and resistance, top traders on a token, a wallet's PnL and trades, largest prints, launches, depth, a bridge quote, read-only SQL over the index). Returns the answer, source links, an optional route card, tables and charts the analysis produced, and a report when one was built. It analyses: a plan (zones, tranches, an exit, the level where the idea is wrong) is written only when the question asks for one, and is illustrative, with its assumptions stated.\n\n**Layout**: `text` is the whole answer on its own. The optional fields `shape`, `parts`, `details`, `followUpKinds` and `focus` say how the chat lays it out: `parts` is the same answer in order, with the tables and charts of `viz` placed inside the text (in `text` a placed table is written out as a Markdown table), and `details` is further depth the chat folds, which `text` does not repeat. A client that ignores them loses nothing of the answer.\n\n**Auth**: a developer API key (`X-API-Key`) or a Google session bearer. Metered per key per day against the deployment's token budget; 8 questions a minute per caller.\n\n**Agents**: send `\"stream\": false` for one JSON answer (5–40 s). Without it the response is `text/event-stream` with `status` events (which tool is running), one `answer` event, then `done`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string", "maxLength": 1000, "description": "May be empty when `images` is set." }, "stream": { "type": "boolean", "description": "false = one JSON response instead of SSE." }, "history": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string", "maxLength": 4000 }, "images": { "type": "array", "items": { "type": "string" }, "description": "Image ids that user turn carried — their reading comes back as context." } } }, "description": "Up to 12 prior turns." }, "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "The caller's wallet, so \"my PnL\" resolves." }, "mode": { "type": "string", "enum": [ "quick", "deep" ], "description": "How long an answer to write. `quick`: the shortest form (the verdict, its claim, at most three rows of evidence, 120 words at most), faster. `deep`: a judgement or an explanation comes back as a full research note (`shape: \"report\"`), any other answer with a longer folded `details`. Omitted: the length the question calls for. Any other value is ignored." }, "images": { "type": "array", "items": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "description": "Up to 4 ids from `POST /v1/ask/image` (your own, 30 days). The analyst reads each image — chart, positions, a swap or wallet screenshot — before it answers, and can zoom into one." } }, "required": [ "question" ] }, "example": { "question": "What is moving on Arc right now, and is ARGUS still being bought by real wallets?", "stream": false } } } }, "responses": { "200": { "description": "With `stream: false`: the whole answer. Otherwise `text/event-stream`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "The answer, Markdown, complete on its own: a table the answer placed is written out in it (its first 8 rows and 6 columns). `details` is not repeated here." }, "citations": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "What the link is." }, "href": { "type": "string", "description": "A Chord page as a path under `https://getchord.xyz` (`/arc/token/0x…`), or the source's own URL." } }, "description": "A source link." }, "description": "Where to check the numbers: the Chord pages and outside sources behind the answer." }, "quote": { "type": [ "object", "null" ], "additionalProperties": true, "description": "A route card when the question implied a trade: the two tokens, the amounts in whole tokens, the venues, price impact, fee and a link to the trade on Chord. A preview, not a `/v1/quote` response: `/v1/swap` needs a fresh `/v1/quote`." }, "artifact": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The token the answer is about: its stats, where volume traded (support, resistance, VWAP), a report link when one was built." }, "walletArtifact": { "type": [ "object", "null" ], "additionalProperties": true, "description": "" }, "viz": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Tables and charts (`kind`: table · bar · line · donut), at most 6: the ones `parts` and `details` place come first, in that order." } }, "toolsUsed": { "type": "array", "items": { "type": "string" } }, "tokens": { "type": "integer", "description": "Model tokens spent." }, "followUps": { "type": "array", "items": { "type": "string" }, "description": "Up to three next questions: one that goes deeper, one that widens, one action (an alert, a chart, a plan)." }, "assets": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Price chips for the assets the answer names (symbol, label, price, 24h change), at most 8." } }, "shape": { "type": "string", "enum": [ "fact", "explain", "brief", "board", "why", "overview", "compare", "post", "do", "report", "auto" ], "description": "The kind of answer the question got: a single fact, an explanation, a call with its evidence (`brief`), a ranked list (`board`), why something moves, a market overview, a comparison, something to post, something to do on Chord, a full report, or `auto` when nothing matched." }, "parts": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "t": { "type": "string", "const": "md" }, "text": { "type": "string", "description": "Markdown." } }, "description": "Text.", "required": [ "t", "text" ] }, { "type": "object", "properties": { "t": { "type": "string", "const": "viz" }, "i": { "type": "integer", "description": "Index into `viz`." } }, "description": "The table or chart placed at this point.", "required": [ "t", "i" ] } ] }, "description": "The answer body in order: text, and the blocks of `viz` placed inside it. Absent on a question back (`clarify`)." }, "details": { "type": [ "object", "null" ], "properties": { "text": { "type": "string", "description": "The folded part as Markdown, placed tables written out." }, "parts": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "t": { "type": "string", "const": "md" }, "text": { "type": "string", "description": "Markdown." } }, "description": "Text.", "required": [ "t", "text" ] }, { "type": "object", "properties": { "t": { "type": "string", "const": "viz" }, "i": { "type": "integer", "description": "Index into `viz`." } }, "description": "The table or chart placed at this point.", "required": [ "t", "i" ] } ] }, "description": "`i` indexes the same `viz`." } }, "description": "Further depth (a per-venue breakdown, a longer history) that the chat folds under \"Show full analysis\". Not part of `text`. Null when the answer has none." }, "followUpKinds": { "type": "array", "items": { "type": "string", "enum": [ "ask", "alert", "deeper" ] }, "description": "Parallel to `followUps`: `alert` = it asks for an alert, `deeper` = it goes deeper into this answer, `ask` = any other question." }, "focus": { "type": [ "integer", "null" ], "description": "Index into `assets` of the one asset the answer is about, when there is one." } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown credential (`UNAUTHORIZED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKey": [] }, { "Session": [] } ] } }, "/ask/picks": { "get": { "tags": [ "Ask agent" ], "operationId": "askPicks", "summary": "Ask Picks board", "description": "The analyst's current picks (rebuilt every four hours over tokens with real activity): side, score, confidence, the reasons for and against, and the facts behind them, plus the seven-day track record: picks graded, the share that moved their way and the average move. It carries no targets or stops.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "const": 5042 }, "computedAt": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "picks": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "integer", "description": "Unix time, seconds, UTC." }, "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "symbol": { "type": [ "string", "null" ], "description": "" }, "side": { "type": "string", "enum": [ "bullish", "bearish" ] }, "score": { "type": "number", "description": "" }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "priceUsd": { "type": "number", "description": "" }, "why": { "type": "array", "items": { "type": "string" } }, "against": { "type": "array", "items": { "type": "string" } }, "facts": { "type": "object", "additionalProperties": true, "description": "" } } } }, "trackRecord7d": { "type": [ "object", "null" ], "properties": { "graded": { "type": "integer", "description": "" }, "open": { "type": "integer", "description": "" }, "rightWayPct": { "type": [ "number", "null" ], "description": "Of the graded picks that have a price move so far, the share that moved the pick's way, percent. Null while none has one." }, "avgMovePct": { "type": [ "number", "null" ], "description": "Their average move in the pick's direction, percent. Null while none has one." } } } } }, "example": { "chain": 5042, "computedAt": 1789891756, "picks": [ { "ts": 1789891743, "token": "0xbc43ce8dec648ea298c4275559b81d6261c90b67", "symbol": "TOLLY", "side": "bullish", "score": 3.93, "confidence": "medium", "priceUsd": 0.0044422, "why": [ "buyers 64% of the last hour (156 trades)", "59.8% of buying from wallets that are not bots or routers" ], "against": [], "facts": { "change24hPct": 3.451327756586764, "buyShare1h": 64, "buyShare24h": 53, "realBuyerPct": 59.8, "top10Pct": 22.6, "vsVwapPct": 1.3, "lastHourVsPriorPct": 44, "lastHourUsd": 27067, "lastHourTrades": 156, "volume24h": 633338, "traders": 1919 } }, { "ts": 1789891755, "token": "0x70857041fef0ced97f9e01e7ccc21889afe3f6f4", "symbol": "CRA", "side": "bullish", "score": 3.71, "confidence": "medium", "priceUsd": 0.00014232, "why": [ "volume 284% above the prior six hours", "70.3% of buying from wallets that are not bots or routers" ], "against": [], "facts": { "change24hPct": -27.189832782274127, "buyShare1h": 43, "buyShare24h": 49, "realBuyerPct": 70.3, "top10Pct": 11.81, "vsVwapPct": -21.6, "lastHourVsPriorPct": 284, "lastHourUsd": 6334, "lastHourTrades": 71, "volume24h": 104328, "traders": 587 } } ], "trackRecord7d": { "graded": 120, "open": 38, "avgMovePct": 2.4 } } } } } } } }, "/ask/report": { "post": { "tags": [ "Ask agent" ], "operationId": "askReport", "summary": "Build a research note", "description": "Builds Chord's three-page research note for a token (HTML → PDF in the browser, plus Markdown) and returns links good for seven days.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Address or symbol on Arc." }, "summary": { "type": "string", "maxLength": 4000, "description": "Optional analyst text to place on the first page." } }, "required": [ "token" ] }, "example": { "token": "ARGUS" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "" }, "url": { "type": "string", "description": "HTML." }, "mdUrl": { "type": "string", "description": "Markdown." } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown credential (`UNAUTHORIZED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing at this identity (`NOT_FOUND`, `UNKNOWN_TOKEN`, `NO_ROUTE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "Session": [] } ] } }, "/ask/image": { "post": { "tags": [ "Ask agent" ], "operationId": "askImageUpload", "summary": "Attach an image", "description": "Uploads one image for a question (PNG, JPEG, WebP, GIF first frame; ≤ 12 MB). It is re-encoded as a JPEG no wider or taller than 2048 px, with its metadata (EXIF, GPS) removed, and kept 30 days. Send the returned `id` in `images` of `POST /v1/ask`. 30 uploads per 10 minutes per caller.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ] } }, "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "32 hex characters." }, "url": { "type": "string", "description": "`/v1/ask/image/{id}`." }, "width": { "type": "integer", "description": "" }, "height": { "type": "integer", "description": "" }, "bytes": { "type": "integer", "description": "" } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown credential (`UNAUTHORIZED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKey": [] }, { "Session": [] } ] } }, "/ask/image/{id}": { "get": { "tags": [ "Ask agent" ], "operationId": "askImage", "summary": "Fetch an attached image", "description": "The stored JPEG. Public by unguessable id (an `` sends no bearer), 30 days.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Image id." } ], "responses": { "200": { "description": "`image/jpeg`.", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Nothing at this identity (`NOT_FOUND`, `UNKNOWN_TOKEN`, `NO_ROUTE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ask/report/{id}": { "get": { "tags": [ "Ask agent" ], "operationId": "askReportGet", "summary": "Fetch a report", "description": "The note as HTML, or Markdown with a `.md` suffix. Public by unguessable id, seven days.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Report id, optionally with `.md`." } ], "responses": { "200": { "description": "`text/html` or `text/markdown`.", "content": { "text/html": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } } } }, "404": { "description": "Nothing at this identity (`NOT_FOUND`, `UNKNOWN_TOKEN`, `NO_ROUTE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ask/export/{id}": { "get": { "tags": [ "Ask agent" ], "operationId": "askExport", "summary": "Fetch a CSV export", "description": "A table the analyst exported, as CSV (one hour).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Export id, optionally with `.csv`." } ], "responses": { "200": { "description": "`text/csv`.", "content": { "text/csv": { "schema": { "type": "string" } } } }, "404": { "description": "Nothing at this identity (`NOT_FOUND`, `UNKNOWN_TOKEN`, `NO_ROUTE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bridge2/config": { "get": { "tags": [ "Bridge" ], "operationId": "bridge2Config", "summary": "CCTP chain table", "description": "Circle CCTP V2 fast transfer to and from Arc: the chains and domains, USDC addresses, the TokenMessenger / MessageTransmitter contracts, and the Arc-side relayer (address, balance, enabled). The browser signs the burn; Chord proxies the attestation and relays the Arc mint.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "const": "cctp-v2" }, "fastFinalityThreshold": { "type": "integer", "description": "" }, "arcDomain": { "type": "integer", "description": "" }, "contracts": { "type": "object", "properties": { "tokenMessengerV2": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "messageTransmitterV2": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." } } }, "chains": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer", "description": "" }, "domain": { "type": "integer", "description": "" }, "name": { "type": "string", "description": "" }, "usdc": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." } } } }, "relayer": { "type": "object", "properties": { "address": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "arcBalance": { "type": [ "string", "null" ], "description": "Wei." }, "enabled": { "type": "boolean", "description": "" } } } } }, "example": { "provider": "cctp-v2", "fastFinalityThreshold": 1000, "arcDomain": 26, "contracts": { "tokenMessengerV2": "0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d", "messageTransmitterV2": "0x81D40F21F12A8F0E3252Bccb954D722d4c464B64" }, "chains": [ { "chainId": 5042, "domain": 26, "name": "Arc", "usdc": "0x3600000000000000000000000000000000000000" }, { "chainId": 143, "domain": 15, "name": "Monad", "usdc": "0x754704Bc059F8C67012fEd69BC8A327a5aafb603" } ], "relayer": { "address": "0x66449F79050828abb7A205434C0971dBA7a44C38", "arcBalance": "1646165237063978241", "enabled": true } } } } } } } }, "/bridge2/fee": { "get": { "tags": [ "Bridge" ], "operationId": "bridge2Fee", "summary": "CCTP fee", "description": "Circle's minimum fee for a fast and a standard transfer between two domains, in basis points.", "parameters": [ { "name": "src", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Source CCTP domain." }, { "name": "dst", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Destination CCTP domain." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "src": { "type": "integer", "description": "" }, "dst": { "type": "integer", "description": "" }, "fastBps": { "type": "number", "description": "" }, "standardBps": { "type": "number", "description": "" } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bridge2/status": { "get": { "tags": [ "Bridge" ], "operationId": "bridge2Status", "summary": "Attestation status", "description": "Iris status for a burn transaction: `not_found`, `pending` or `complete` with the message and attestation when ready.", "parameters": [ { "name": "srcDomain", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "" }, { "name": "tx", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$", "description": "Transaction hash." }, "description": "The burn transaction." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_found", "pending", "complete" ] }, "srcDomain": { "type": "integer", "description": "" }, "tx": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$", "description": "Transaction hash." }, "message": { "type": [ "string", "null" ], "description": "" }, "attestation": { "type": [ "string", "null" ], "description": "" }, "eventNonce": { "type": [ "string", "null" ], "description": "" }, "decoded": { "type": [ "object", "null" ], "additionalProperties": true, "description": "" } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bridge2/relay": { "post": { "tags": [ "Bridge" ], "operationId": "bridge2Relay", "summary": "Relay the Arc mint", "description": "Once attested, Chord's relayer submits `receiveMessage` on Arc so the recipient needs no gas there. `409 NOT_ATTESTED` until Iris completes; `429 DAILY_CAP`; `503 RELAYER_OFF`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "srcDomain": { "type": "integer", "description": "" }, "tx": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$", "description": "Transaction hash." } }, "required": [ "srcDomain", "tx" ] }, "example": { "srcDomain": 6, "tx": "0x…" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "txHash": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$", "description": "Transaction hash." } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`NOT_ATTESTED` or `IN_FLIGHT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The routing engine or an upstream did not answer (`ENGINE_ERROR`, `ROUTE_ERROR`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/xswap/plan": { "post": { "tags": [ "Bridge" ], "operationId": "xswapPlan", "summary": "Cross-chain swap plan", "description": "Quotes a token on one chain into a token on another two ways at once — **composed** (Chord's router on the origin → USDC/USDG rail → Chord's router on the destination) and **direct** (Relay end to end) — and names the one that lands more. Long-tail tokens on Arc / Monad / Robinhood only route on the composed path. Fees come back as three lines (protocol · bridge · network) and `gas` says who pays on each side. `MIN_SIZE` below 10 USD of the bridged stable.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "chainIn": { "type": "integer", "enum": [ 143, 4663, 5042 ] }, "chainOut": { "type": "integer", "enum": [ 143, 4663, 5042 ] }, "tokenIn": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenOut": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "slippageBps": { "type": "integer", "minimum": 10, "maximum": 500, "default": 100 }, "recipient": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "rail": { "type": "string", "enum": [ "auto", "relay", "cctp" ], "default": "auto", "description": "Force a rail; `auto` applies the corridor rules (Robinhood → Relay; Monad ↔ Arc → CCTP when the mint relayer is funded; else Relay)." } }, "required": [ "user", "chainIn", "chainOut", "tokenIn", "tokenOut", "amount" ] }, "example": { "user": "0xb145400da27a2497d9fc2cd5621f2bfd37617af4", "chainIn": 5042, "chainOut": 143, "tokenIn": "0x3600000000000000000000000000000000000000", "tokenOut": "0x350035555e10d9afaf1566aaebfced5ba6c27777", "amount": "1000000000", "slippageBps": 100 } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "best": { "type": "string", "enum": [ "composed", "direct" ] }, "composed": { "type": [ "object", "null" ], "properties": { "chainIn": { "type": "integer", "description": "" }, "chainOut": { "type": "integer", "description": "" }, "tokenIn": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenOut": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amountIn": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "amountOut": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "legs": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap" }, "chainId": { "type": "integer", "description": "" }, "tokenIn": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenOut": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amountIn": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "amountOut": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "priceImpactPct": { "type": "number", "description": "" }, "feeBps": { "type": "integer", "description": "Our tier fee on this leg's output." }, "dexIds": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "properties": { "kind": { "type": "string", "const": "bridge" }, "rail": { "type": "string", "enum": [ "relay", "cctp" ] }, "chainIdIn": { "type": "integer", "description": "" }, "chainIdOut": { "type": "integer", "description": "" }, "tokenIn": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenOut": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amountIn": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "amountOut": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "timeEstimateSec": { "type": "number", "description": "" }, "requestId": { "type": "string", "description": "Relay intent id; empty on CCTP until the burn is sent." }, "srcDomain": { "type": "integer", "description": "CCTP only." }, "dstDomain": { "type": "integer", "description": "CCTP only." }, "feeBps": { "type": "number", "description": "Circle's fast-transfer fee, CCTP only." } } } ] } }, "timeEstimateSec": { "type": "number", "description": "" }, "rail": { "type": "string", "enum": [ "relay", "cctp" ] }, "railReason": { "type": "string", "description": "Why this rail." }, "fees": { "type": "object", "properties": { "protocol": { "type": "object", "properties": { "originBps": { "type": "integer", "description": "" }, "destBps": { "type": "integer", "description": "" }, "usd": { "type": "number", "description": "" } }, "description": "Our on-chain tier fee per swap leg." }, "bridge": { "type": "object", "properties": { "rail": { "type": "string", "description": "" }, "usd": { "type": "number", "description": "" }, "bps": { "type": "number", "description": "" }, "appFeeBps": { "type": "integer", "description": "App fee added on Relay." } }, "description": "The bridge's own cut." }, "network": { "type": "object", "properties": { "usd": { "type": "number", "description": "Flat per relayer-paid transaction." }, "covered": { "type": "boolean", "description": "true = we eat it (Arc mint)." }, "mode": { "type": "string", "enum": [ "user", "usdc-gas", "gasless", "solver", "none" ] } }, "description": "Gas we front on the destination." }, "totalUsd": { "type": "number", "description": "" } } }, "gas": { "type": "object", "properties": { "origin": { "type": "string", "description": "" }, "dest": { "type": "string", "description": "" } }, "description": "Who pays gas on each side." }, "minAnchorUnits": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "bridge": { "type": "object", "additionalProperties": true, "description": "Rail-shaped: `{ rail, requestId, checkEndpoint, steps[], fees, details }` — sign `steps` in order on the origin chain (an `approval` item may be skipped when the allowance covers it)." } } }, "direct": { "type": [ "object", "null" ], "properties": { "chainIn": { "type": "integer", "description": "" }, "chainOut": { "type": "integer", "description": "" }, "tokenIn": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenOut": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amountIn": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "amountOut": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "legs": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap" }, "chainId": { "type": "integer", "description": "" }, "tokenIn": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenOut": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amountIn": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "amountOut": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "priceImpactPct": { "type": "number", "description": "" }, "feeBps": { "type": "integer", "description": "Our tier fee on this leg's output." }, "dexIds": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "properties": { "kind": { "type": "string", "const": "bridge" }, "rail": { "type": "string", "enum": [ "relay", "cctp" ] }, "chainIdIn": { "type": "integer", "description": "" }, "chainIdOut": { "type": "integer", "description": "" }, "tokenIn": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenOut": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amountIn": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "amountOut": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "timeEstimateSec": { "type": "number", "description": "" }, "requestId": { "type": "string", "description": "Relay intent id; empty on CCTP until the burn is sent." }, "srcDomain": { "type": "integer", "description": "CCTP only." }, "dstDomain": { "type": "integer", "description": "CCTP only." }, "feeBps": { "type": "number", "description": "Circle's fast-transfer fee, CCTP only." } } } ] } }, "timeEstimateSec": { "type": "number", "description": "" }, "rail": { "type": "string", "enum": [ "relay", "cctp" ] }, "railReason": { "type": "string", "description": "Why this rail." }, "fees": { "type": "object", "properties": { "protocol": { "type": "object", "properties": { "originBps": { "type": "integer", "description": "" }, "destBps": { "type": "integer", "description": "" }, "usd": { "type": "number", "description": "" } }, "description": "Our on-chain tier fee per swap leg." }, "bridge": { "type": "object", "properties": { "rail": { "type": "string", "description": "" }, "usd": { "type": "number", "description": "" }, "bps": { "type": "number", "description": "" }, "appFeeBps": { "type": "integer", "description": "App fee added on Relay." } }, "description": "The bridge's own cut." }, "network": { "type": "object", "properties": { "usd": { "type": "number", "description": "Flat per relayer-paid transaction." }, "covered": { "type": "boolean", "description": "true = we eat it (Arc mint)." }, "mode": { "type": "string", "enum": [ "user", "usdc-gas", "gasless", "solver", "none" ] } }, "description": "Gas we front on the destination." }, "totalUsd": { "type": "number", "description": "" } } }, "gas": { "type": "object", "properties": { "origin": { "type": "string", "description": "" }, "dest": { "type": "string", "description": "" } }, "description": "Who pays gas on each side." }, "minAnchorUnits": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "bridge": { "type": "object", "additionalProperties": true, "description": "Rail-shaped: `{ rail, requestId, checkEndpoint, steps[], fees, details }` — sign `steps` in order on the origin chain (an `approval` item may be skipped when the allowance covers it)." } } }, "errors": { "type": "object", "additionalProperties": true, "description": "Per-path failure `{ code, message }` when a path could not be quoted." } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing at this identity (`NOT_FOUND`, `UNKNOWN_TOKEN`, `NO_ROUTE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The routing engine or an upstream did not answer (`ENGINE_ERROR`, `ROUTE_ERROR`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/xswap/quote": { "post": { "tags": [ "Bridge" ], "operationId": "xswapQuote", "summary": "Composed cross-chain quote", "description": "The composed path only (see `/xswap/plan`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "chainIn": { "type": "integer", "enum": [ 143, 4663, 5042 ] }, "chainOut": { "type": "integer", "enum": [ 143, 4663, 5042 ] }, "tokenIn": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenOut": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "slippageBps": { "type": "integer", "minimum": 10, "maximum": 500, "default": 100 }, "recipient": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "rail": { "type": "string", "enum": [ "auto", "relay", "cctp" ], "default": "auto", "description": "Force a rail; `auto` applies the corridor rules (Robinhood → Relay; Monad ↔ Arc → CCTP when the mint relayer is funded; else Relay)." } }, "required": [ "user", "chainIn", "chainOut", "tokenIn", "tokenOut", "amount" ] }, "example": { "user": "0xb145400da27a2497d9fc2cd5621f2bfd37617af4", "chainIn": 5042, "chainOut": 143, "tokenIn": "0x3600000000000000000000000000000000000000", "tokenOut": "0x350035555e10d9afaf1566aaebfced5ba6c27777", "amount": "1000000000", "slippageBps": 100 } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chainIn": { "type": "integer", "description": "" }, "chainOut": { "type": "integer", "description": "" }, "tokenIn": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenOut": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amountIn": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "amountOut": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "legs": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap" }, "chainId": { "type": "integer", "description": "" }, "tokenIn": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenOut": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amountIn": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "amountOut": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "priceImpactPct": { "type": "number", "description": "" }, "feeBps": { "type": "integer", "description": "Our tier fee on this leg's output." }, "dexIds": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "properties": { "kind": { "type": "string", "const": "bridge" }, "rail": { "type": "string", "enum": [ "relay", "cctp" ] }, "chainIdIn": { "type": "integer", "description": "" }, "chainIdOut": { "type": "integer", "description": "" }, "tokenIn": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenOut": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amountIn": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "amountOut": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "timeEstimateSec": { "type": "number", "description": "" }, "requestId": { "type": "string", "description": "Relay intent id; empty on CCTP until the burn is sent." }, "srcDomain": { "type": "integer", "description": "CCTP only." }, "dstDomain": { "type": "integer", "description": "CCTP only." }, "feeBps": { "type": "number", "description": "Circle's fast-transfer fee, CCTP only." } } } ] } }, "timeEstimateSec": { "type": "number", "description": "" }, "rail": { "type": "string", "enum": [ "relay", "cctp" ] }, "railReason": { "type": "string", "description": "Why this rail." }, "fees": { "type": "object", "properties": { "protocol": { "type": "object", "properties": { "originBps": { "type": "integer", "description": "" }, "destBps": { "type": "integer", "description": "" }, "usd": { "type": "number", "description": "" } }, "description": "Our on-chain tier fee per swap leg." }, "bridge": { "type": "object", "properties": { "rail": { "type": "string", "description": "" }, "usd": { "type": "number", "description": "" }, "bps": { "type": "number", "description": "" }, "appFeeBps": { "type": "integer", "description": "App fee added on Relay." } }, "description": "The bridge's own cut." }, "network": { "type": "object", "properties": { "usd": { "type": "number", "description": "Flat per relayer-paid transaction." }, "covered": { "type": "boolean", "description": "true = we eat it (Arc mint)." }, "mode": { "type": "string", "enum": [ "user", "usdc-gas", "gasless", "solver", "none" ] } }, "description": "Gas we front on the destination." }, "totalUsd": { "type": "number", "description": "" } } }, "gas": { "type": "object", "properties": { "origin": { "type": "string", "description": "" }, "dest": { "type": "string", "description": "" } }, "description": "Who pays gas on each side." }, "minAnchorUnits": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "bridge": { "type": "object", "additionalProperties": true, "description": "Rail-shaped: `{ rail, requestId, checkEndpoint, steps[], fees, details }` — sign `steps` in order on the origin chain (an `approval` item may be skipped when the allowance covers it)." } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing at this identity (`NOT_FOUND`, `UNKNOWN_TOKEN`, `NO_ROUTE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The routing engine or an upstream did not answer (`ENGINE_ERROR`, `ROUTE_ERROR`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/xswap/order": { "post": { "tags": [ "Bridge" ], "operationId": "xswapOrder", "summary": "Register a cross-chain order", "description": "Quotes and records the order the wallet is about to sign so it can be resumed after a refresh: the server tracks the bridge (Relay status or Circle attestation), mints CCTP transfers on Arc, and re-quotes the final leg at the amount that actually arrived. Poll `GET /xswap/order?id=`. `path: \"direct\"` registers the Relay end-to-end candidate instead.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "chainIn": { "type": "integer", "enum": [ 143, 4663, 5042 ] }, "chainOut": { "type": "integer", "enum": [ 143, 4663, 5042 ] }, "tokenIn": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenOut": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "slippageBps": { "type": "integer", "minimum": 10, "maximum": 500, "default": 100 }, "recipient": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "rail": { "type": "string", "enum": [ "auto", "relay", "cctp" ], "default": "auto", "description": "Force a rail; `auto` applies the corridor rules (Robinhood → Relay; Monad ↔ Arc → CCTP when the mint relayer is funded; else Relay)." }, "path": { "type": "string", "enum": [ "composed", "direct" ], "default": "composed" } }, "required": [ "user", "chainIn", "chainOut", "tokenIn", "tokenOut", "amount" ] }, "example": { "user": "0xb145400da27a2497d9fc2cd5621f2bfd37617af4", "chainIn": 5042, "chainOut": 143, "tokenIn": "0x3600000000000000000000000000000000000000", "tokenOut": "0x350035555e10d9afaf1566aaebfced5ba6c27777", "amount": "1000000000", "slippageBps": 100 } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "object", "additionalProperties": true, "description": "`{ id, state, rail, chainIn, chainOut, tokenIn, tokenOut, amountIn, quotedOut, requestId, originTxHash?, destTxHash?, bridgedAmount?, destQuote?, claim?, note? }` — states: pending_origin · bridging · pending_dest · done · stuck_dest · failed_origin." }, "quote": { "type": "object", "properties": { "chainIn": { "type": "integer", "description": "" }, "chainOut": { "type": "integer", "description": "" }, "tokenIn": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenOut": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amountIn": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "amountOut": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "legs": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap" }, "chainId": { "type": "integer", "description": "" }, "tokenIn": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenOut": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amountIn": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "amountOut": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "priceImpactPct": { "type": "number", "description": "" }, "feeBps": { "type": "integer", "description": "Our tier fee on this leg's output." }, "dexIds": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "properties": { "kind": { "type": "string", "const": "bridge" }, "rail": { "type": "string", "enum": [ "relay", "cctp" ] }, "chainIdIn": { "type": "integer", "description": "" }, "chainIdOut": { "type": "integer", "description": "" }, "tokenIn": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenOut": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amountIn": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "amountOut": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "timeEstimateSec": { "type": "number", "description": "" }, "requestId": { "type": "string", "description": "Relay intent id; empty on CCTP until the burn is sent." }, "srcDomain": { "type": "integer", "description": "CCTP only." }, "dstDomain": { "type": "integer", "description": "CCTP only." }, "feeBps": { "type": "number", "description": "Circle's fast-transfer fee, CCTP only." } } } ] } }, "timeEstimateSec": { "type": "number", "description": "" }, "rail": { "type": "string", "enum": [ "relay", "cctp" ] }, "railReason": { "type": "string", "description": "Why this rail." }, "fees": { "type": "object", "properties": { "protocol": { "type": "object", "properties": { "originBps": { "type": "integer", "description": "" }, "destBps": { "type": "integer", "description": "" }, "usd": { "type": "number", "description": "" } }, "description": "Our on-chain tier fee per swap leg." }, "bridge": { "type": "object", "properties": { "rail": { "type": "string", "description": "" }, "usd": { "type": "number", "description": "" }, "bps": { "type": "number", "description": "" }, "appFeeBps": { "type": "integer", "description": "App fee added on Relay." } }, "description": "The bridge's own cut." }, "network": { "type": "object", "properties": { "usd": { "type": "number", "description": "Flat per relayer-paid transaction." }, "covered": { "type": "boolean", "description": "true = we eat it (Arc mint)." }, "mode": { "type": "string", "enum": [ "user", "usdc-gas", "gasless", "solver", "none" ] } }, "description": "Gas we front on the destination." }, "totalUsd": { "type": "number", "description": "" } } }, "gas": { "type": "object", "properties": { "origin": { "type": "string", "description": "" }, "dest": { "type": "string", "description": "" } }, "description": "Who pays gas on each side." }, "minAnchorUnits": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "bridge": { "type": "object", "additionalProperties": true, "description": "Rail-shaped: `{ rail, requestId, checkEndpoint, steps[], fees, details }` — sign `steps` in order on the origin chain (an `approval` item may be skipped when the allowance covers it)." } } }, "requoteToleranceBps": { "type": "integer", "description": "" } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing at this identity (`NOT_FOUND`, `UNKNOWN_TOKEN`, `NO_ROUTE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The routing engine or an upstream did not answer (`ENGINE_ERROR`, `ROUTE_ERROR`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Bridge" ], "operationId": "xswapOrderGet", "summary": "Advance and read an order", "description": "Asks the bridge where the money is and, once it landed, returns a fresh destination-leg quote (`destQuote`) to sign. Polling this is what moves the order.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "description": "Order id." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "object", "additionalProperties": true, "description": "" }, "requoteToleranceBps": { "type": "integer", "description": "" } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing at this identity (`NOT_FOUND`, `UNKNOWN_TOKEN`, `NO_ROUTE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The routing engine or an upstream did not answer (`ENGINE_ERROR`, `ROUTE_ERROR`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/xswap/orders": { "get": { "tags": [ "Bridge" ], "operationId": "xswapOrders", "summary": "A wallet's in-flight orders", "description": "Newest first — how a client recovers cross-chain state it never held locally.", "parameters": [ { "name": "user", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "" } } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The routing engine or an upstream did not answer (`ENGINE_ERROR`, `ROUTE_ERROR`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/relayers": { "get": { "tags": [ "Account and health" ], "operationId": "relayers", "summary": "Relayer gas health", "description": "For each chain Chord's relayer pays gas on (Monad gasless swaps, Robinhood Permit2 swaps, Arc CCTP mints): its address, native balance, current gas price and the estimated transactions that balance still covers. `ok` = above the floor; the cross-chain planner stops routing through a relayer that is not ok.", "parameters": [ { "name": "force", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Re-read now instead of the 60 s cache." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "minTx": { "type": "integer", "description": "The floor." }, "relayers": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer", "description": "" }, "name": { "type": "string", "description": "" }, "symbol": { "type": "string", "description": "" }, "role": { "type": "string", "description": "" }, "configured": { "type": "boolean", "description": "" }, "address": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "balance": { "type": [ "string", "null" ], "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "gasPrice": { "type": [ "string", "null" ], "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "gasPerTx": { "type": "integer", "description": "" }, "txRemaining": { "type": [ "integer", "null" ], "description": "" }, "ok": { "type": "boolean", "description": "" }, "checkedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." }, "error": { "type": "string", "description": "" } } } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } } } } } } } }, "/crosschain/config": { "get": { "tags": [ "Bridge" ], "operationId": "crosschainConfig", "summary": "Bridge providers and chains", "description": "Whether the provider is enabled, its app fee, the origin chains this deployment offers, and the destination chains with display names, native symbols, explorers and icons.", "parameters": [ { "name": "provider", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "lifi", "relay" ] }, "description": "Bridge provider. Chord uses `lifi`." }, { "name": "origin", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Exclude this chain from the list." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "" }, "provider": { "type": "string", "description": "" }, "appFeeBps": { "type": "number", "description": "" }, "origins": { "type": "array", "items": { "type": "integer" } }, "origin": { "type": [ "integer", "null" ], "description": "" }, "chains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "" }, "name": { "type": "string", "description": "" }, "displayName": { "type": "string", "description": "" }, "nativeSymbol": { "type": "string", "description": "" }, "explorerUrl": { "type": "string", "description": "" }, "featured": { "type": "boolean", "description": "" }, "iconUrl": { "type": [ "string", "null" ], "description": "" } } } } } }, "example": { "enabled": true, "provider": "lifi", "appFeeBps": 5, "origins": [ 143, 4663 ], "origin": null, "chains": [ { "id": 4663, "name": "out", "displayName": "Robinhood Chain", "nativeSymbol": "ETH", "explorerUrl": "https://robin.etherscan.io", "featured": true, "iconUrl": "https://raw.githubusercontent.com/lifinance/types/main/src/assets/icons/chains/robinhood.svg" }, { "id": 5042, "name": "arc", "displayName": "Arc", "nativeSymbol": "USDC", "explorerUrl": "https://explorer.arc.io", "featured": true, "iconUrl": "https://raw.githubusercontent.com/lifinance/types/main/src/assets/icons/chains/arc.svg" } ] } } } } } } }, "/crosschain/currencies": { "get": { "tags": [ "Bridge" ], "operationId": "crosschainCurrencies", "summary": "Bridgeable tokens on a chain", "description": "Tokens the provider can move on a chain, filtered by a search term.", "parameters": [ { "name": "chainId", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 }, "description": "Symbol or name (≥ 2 characters)." }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "lifi", "relay" ] }, "description": "Bridge provider. Chord uses `lifi`." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chainId": { "type": "integer", "description": "" }, "provider": { "type": "string", "description": "" }, "currencies": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Token rows (address, symbol, name, decimals, logo)." } } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/crosschain/quote": { "post": { "tags": [ "Bridge" ], "operationId": "crosschainQuote", "summary": "Bridge quote", "description": "A cross-chain quote from the provider: the steps, fees and the transactions to sign on the origin chain (an approve step is added when the origin token is an ERC-20). Poll `/crosschain/status` with the deposit hash.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "originChainId": { "type": "integer", "default": 143 }, "destinationChainId": { "type": "integer", "description": "" }, "originCurrency": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "destinationCurrency": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "slippageBps": { "type": "integer", "minimum": 10, "maximum": 500, "default": 100 }, "recipient": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "provider": { "type": "string", "enum": [ "lifi", "relay" ] }, "usePermit": { "type": "boolean", "description": "Relay only: a permit (signature) deposit instead of a transaction, for tokens that support it (native USDC on Arbitrum)." } }, "required": [ "user", "destinationChainId", "originCurrency", "destinationCurrency", "amount" ] }, "example": { "user": "0xb145400da27a2497d9fc2cd5621f2bfd37617af4", "originChainId": 8453, "destinationChainId": 5042, "originCurrency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "destinationCurrency": "0x3600000000000000000000000000000000000000", "amount": "100000000", "slippageBps": 100, "provider": "lifi" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`{ provider, requestId, steps[], fees, details, checkEndpoint, txns[] }` — provider-shaped; sign `txns` in order." } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The routing engine or an upstream did not answer (`ENGINE_ERROR`, `ROUTE_ERROR`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/crosschain/permit": { "post": { "tags": [ "Bridge" ], "operationId": "crosschainPermit", "summary": "Submit a signed permit deposit", "description": "Hands a signed `signature` step from a `usePermit` quote back to the provider (Relay only): send the step's `post.body` fields plus the EIP-712 signature. Then poll `/crosschain/status`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$" }, "kind": { "type": "string", "description": "e.g. `eip3009`" }, "api": { "type": "string", "description": "e.g. `swap`" }, "signature": { "type": "string", "description": "0x… EIP-712 signature" } }, "required": [ "requestId", "kind", "api", "signature" ] }, "example": { "requestId": "0x17900816413eb4c1d4ec4b00d0be87c6b60872ed43d103eb87dc22a0b80ff325", "kind": "eip3009", "api": "swap", "signature": "0x…" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Provider-shaped acknowledgement." } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The routing engine or an upstream did not answer (`ENGINE_ERROR`, `ROUTE_ERROR`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/crosschain/status": { "get": { "tags": [ "Bridge" ], "operationId": "crosschainStatus", "summary": "Bridge status", "description": "Status of a bridge by its request id or deposit hash: `waiting` · `depositing` · `pending` · `submitted` · `success` · `delayed` · `refund` · `failure` · `unknown`.", "parameters": [ { "name": "requestId", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$" }, "description": "Request id (or the deposit tx hash on LI.FI)." }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "lifi", "relay" ] }, "description": "Bridge provider. Chord uses `lifi`." }, { "name": "fromChain", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" }, { "name": "toChain", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "waiting", "depositing", "pending", "submitted", "success", "delayed", "refund", "failure", "unknown" ] }, "substatus": { "type": "string", "description": "" }, "inTxHashes": { "type": "array", "items": { "type": "string" } }, "txHashes": { "type": "array", "items": { "type": "string" } }, "explorerLink": { "type": "string", "description": "" }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The routing engine or an upstream did not answer (`ENGINE_ERROR`, `ROUTE_ERROR`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rh/status": { "get": { "tags": [ "Robinhood Chain data" ], "operationId": "rhStatus", "summary": "Rollup freshness", "description": "Chain 4663 only; takes no `chain` parameter. Served from Chord's rollup tables, never from a raw scan. `503 NOT_READY` until the rollup has run.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "const": 4663 }, "enabled": { "type": "boolean", "description": "" }, "recentAt": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "staleSec": { "type": [ "integer", "null" ], "description": "" }, "floorHour": { "type": [ "integer", "null" ], "description": "" }, "genesisHour": { "type": [ "integer", "null" ], "description": "" }, "backfillComplete": { "type": "boolean", "description": "" }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 4663, "enabled": true, "recentAt": 1789891427, "staleSec": 441, "floorHour": 1781197200, "genesisHour": 1785974400, "backfillComplete": true, "updatedAt": 1789891868582 } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rh/overview": { "get": { "tags": [ "Robinhood Chain data" ], "operationId": "rhOverview", "summary": "Chain totals", "description": "Last 24 hours, venue share, 24 hourly buckets and up to 30 daily rows. Chain 4663 only; takes no `chain` parameter. Served from Chord's rollup tables, never from a raw scan. `503 NOT_READY` until the rollup has run.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "const": 4663 }, "last24h": { "type": "object", "properties": { "volUsd": { "type": "number", "description": "" }, "swaps": { "type": "integer", "description": "" }, "tokens": { "type": "integer", "description": "" }, "sinceHour": { "type": "integer", "description": "" } } }, "venues24h": { "type": "array", "items": { "type": "object", "properties": { "dex": { "type": "string", "description": "" }, "volUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "tokens": { "type": "integer", "description": "" }, "sharePct": { "type": "number", "description": "" } } } }, "hourly24": { "type": "array", "items": { "type": "object", "properties": { "hour": { "type": "integer", "description": "" }, "volUsd": { "type": "number", "description": "" }, "swaps": { "type": "integer", "description": "" } } } }, "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "integer", "description": "" }, "swaps": { "type": "integer", "description": "" }, "volUsd": { "type": "number", "description": "" }, "tokens": { "type": "integer", "description": "" }, "wallets": { "type": "integer", "description": "" }, "venues": { "type": "integer", "description": "" } } } }, "coverage": { "$ref": "#/components/schemas/Coverage" }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 4663, "last24h": { "volUsd": 550299744.1561619, "swaps": 1079429, "tokens": 1248, "sinceHour": 1789808400 }, "venues24h": [ { "dex": "uniswap_v3", "volUsd": 398446666.0763337, "trades": 793745, "tokens": 976, "sharePct": 72.40538821025947 }, { "dex": "nadfun_dex", "volUsd": 86870804.38588408, "trades": 94710, "tokens": 205, "sharePct": 15.786088456045553 } ], "hourly24": [ { "hour": 1789808400, "volUsd": 20860178.787550393, "swaps": 29122 }, { "hour": 1789812000, "volUsd": 16607559.066086678, "swaps": 28538 } ], "daily": [ { "day": 1787356800, "swaps": 706077, "volUsd": 248035051.5861872, "tokens": 1056, "wallets": 32922, "venues": 8 }, { "day": 1787443200, "swaps": 760930, "volUsd": 261936195.3020307, "tokens": 1065, "wallets": 26961, "venues": 9 } ], "coverage": { "recentAt": 1789891427, "stale": false, "floorHour": 1781197200, "genesisHour": 1785974400, "backfillComplete": true }, "updatedAt": 1789891794537 } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rh/venues": { "get": { "tags": [ "Robinhood Chain data" ], "operationId": "rhVenues", "summary": "Venue share over a window", "description": "Chain 4663 only; takes no `chain` parameter. Served from Chord's rollup tables, never from a raw scan. `503 NOT_READY` until the rollup has run.", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 180, "default": 30 }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "const": 4663 }, "days": { "type": "integer", "description": "" }, "venues": { "type": "array", "items": { "type": "object", "properties": { "dex": { "type": "string", "description": "" }, "volUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "sharePct": { "type": "number", "description": "" }, "series": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "integer", "description": "" }, "volUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "tokens": { "type": "integer", "description": "" } } } } } } }, "totals": { "type": "object", "properties": { "volUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" } } } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rh/tokens": { "get": { "tags": [ "Robinhood Chain data" ], "operationId": "rhTokens", "summary": "Every token traded in the last 24 hours", "description": "Price, change, volume split, trade counts and attributed traders. Unlisted tokens (no curated metadata or logo) are hidden unless asked for. Chain 4663 only; takes no `chain` parameter. Served from Chord's rollup tables, never from a raw scan. `503 NOT_READY` until the rollup has run.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 }, "description": "" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "volume", "trades", "traders", "change" ], "default": "volume" }, "description": "" }, { "name": "includeUnlisted", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "const": 4663 }, "sinceHour": { "type": "integer", "description": "" }, "tradersSince": { "type": "integer", "description": "" }, "sort": { "type": "string", "description": "" }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/RhTokenRow" } }, "total": { "type": "integer", "description": "" }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 4663, "sinceHour": 1789808400, "tradersSince": 1789776000, "sort": "volume", "tokens": [ { "address": "0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73", "symbol": "WETH", "name": "WETH", "decimals": 18, "logoURI": "https://assets.coingecko.com/coins/images/2518/small/weth.png?1696503332", "tags": [ "bridged" ], "listed": true, "priceUsd": 2580.1259797979797, "change24hPct": -2.421961053968613, "liquidityUsd": null, "volume24h": 305214685.46276, "buyVolume24h": 150250793.83089906, "sellVolume24h": 154963891.63186103, "trades24h": 431734, "buys24h": 221381, "sells24h": 210353, "traders": 19755, "lastTradeTs": 1789891402 }, { "address": "0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC", "symbol": "NVDA", "name": "NVIDIA • Robinhood Token", "decimals": 18, "logoURI": "https://cdn.robinhood.com/ncw_assets/logos/0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec.png", "tags": [ "stock" ], "listed": true, "priceUsd": 220.97693371148938, "change24hPct": -0.7107543259553206, "liquidityUsd": 7508320, "volume24h": 34504046.378991455, "buyVolume24h": 16798001.15787153, "sellVolume24h": 17706045.221119925, "trades24h": 103172, "buys24h": 52577, "sells24h": 50595, "traders": 5056, "lastTradeTs": 1789891401 } ], "total": 357, "updatedAt": 1789891868895 } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rh/token/{address}": { "get": { "tags": [ "Robinhood Chain data" ], "operationId": "rhToken", "summary": "One token: hourly tape and venue split", "description": "Chain 4663 only; takes no `chain` parameter. Served from Chord's rollup tables, never from a raw scan. `503 NOT_READY` until the rollup has run.", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "" }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 720, "default": 168 }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "symbol": { "type": [ "string", "null" ], "description": "" } } }, "series": { "type": "array", "items": { "type": "object", "properties": { "hour": { "type": "integer", "description": "" }, "volUsd": { "type": "number", "description": "" }, "buyUsd": { "type": "number", "description": "" }, "sellUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "buys": { "type": "integer", "description": "" }, "sells": { "type": "integer", "description": "" }, "priceLast": { "type": [ "number", "null" ], "description": "" } } } }, "byDex": { "type": "array", "items": { "type": "object", "properties": { "dex": { "type": "string", "description": "" }, "volUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "sharePct": { "type": "number", "description": "" } } } } } } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rh/stocks": { "get": { "tags": [ "Robinhood Chain data" ], "operationId": "rhStocks", "summary": "Tokenized stocks", "description": "Every tokenized stock and ETF on chain 4663 with its 24-hour tape, NAV basis where the issuer publishes a rate, and the share of the last seven days that traded outside the NYSE session. Chain 4663 only; takes no `chain` parameter. Served from Chord's rollup tables, never from a raw scan. `503 NOT_READY` until the rollup has run.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "const": 4663 }, "sinceHour": { "type": "integer", "description": "" }, "tradersSince": { "type": "integer", "description": "" }, "stocks": { "type": "array", "items": { "$ref": "#/components/schemas/RhStockRow" } }, "note": { "type": "string", "description": "" }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 4663, "sinceHour": 1789808400, "tradersSince": 1789776000, "stocks": [ { "address": "0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC", "symbol": "NVDA", "name": "NVIDIA • Robinhood Token", "decimals": 18, "logoURI": "https://cdn.robinhood.com/ncw_assets/logos/0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec.png", "tags": [ "stock" ], "listed": true, "priceUsd": 220.97693371148938, "change24hPct": -0.7107543259553206, "liquidityUsd": 7508320, "volume24h": 34504046.378991455, "buyVolume24h": 16798001.15787153, "sellVolume24h": 17706045.221119925, "trades24h": 103172, "buys24h": 52577, "sells24h": 50595, "traders": 5056, "lastTradeTs": 1789891401, "navUsd": null, "basisPct": null, "offHours7d": { "volUsd": 122712280.03735964, "trades": 365579, "sharePct": 57.75403042239189 } }, { "address": "0x4a0E65A3EcceC6dBe60AE065F2e7bb85Fae35eEa", "symbol": "SPCX", "name": "Space Exploration Technologies Corp • Robinhood Token", "decimals": 18, "logoURI": "https://cdn.robinhood.com/ncw_assets/logos/0x4a0e65a3eccec6dbe60ae065f2e7bb85fae35eea.png", "tags": [ "stock" ], "listed": true, "priceUsd": 152.33158650694747, "change24hPct": -0.278639004753245, "liquidityUsd": 4756081, "volume24h": 14186052.186705315, "buyVolume24h": 7064922.470980956, "sellVolume24h": 7121129.715724356, "trades24h": 41993, "buys24h": 22090, "sells24h": 19903, "traders": 3138, "lastTradeTs": 1789891402, "navUsd": null, "basisPct": null, "offHours7d": { "volUsd": 75910449.80504468, "trades": 277274, "sharePct": 42.37032851899335 } } ], "note": "offHours7d = volume in hour buckets outside the NYSE regular session (09:30-16:00 New York, Mon-Fri, DST-aware; exchange holidays not modelled). navUsd = Blockscout exchange_rate at last catalogue refresh.", "updatedAt": 1789891849578 } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/{chain}/status": { "get": { "tags": [ "Avalanche, Base, BNB Chain" ], "operationId": "chainStatus", "summary": "Rollup freshness and coverage", "description": "Is the chain's rollup fresh, how far back it reaches, whether the tape and the public flag are on, where the raw tape is cut, and the ingest floor. Answers 200 even before the first rollup pass (`recentAt` is then null). Check it before trusting a quiet number.\n\nChain-keyed data for Avalanche C-Chain, Base and BNB Chain, served from Chord's rollup tables for the chain (every swap summed by hour, token and venue). Only the trade tape, the prints ticker and the wallet read raw rows, scoped to one token or one wallet and bounded.\n\n- **Access.** No key needed while the chain is public (all three are today). A chain whose tape is off, or that is not public yet, answers `400 UNSUPPORTED_CHAIN` (\"chain N is not served yet\") unless the request carries an `X-API-Key`; those answers are sent `Cache-Control: private`.\n- **Ingest floor.** Every count, volume and print covers trades at or above the chain's floor, returned as `ingestFloor`. BNB Chain runs at $100 today; Avalanche and Base at 0.\n- **Readiness.** `503 NOT_READY` until the chain's rollup has run on this deployment; `503 CHAIN_DATA_UNAVAILABLE` when the store cannot be read. Never treat either as \"no trades\".", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "avalanche", "base", "bnb", "arbitrum", "ethereum", "43114", "8453", "56", "42161", "1" ] }, "description": "The chain, by key or id: `avalanche` or `43114`, `base` or `8453`, `bnb` or `56`, `arbitrum` or `42161`, `ethereum` or `1` (case-insensitive). Arc, Robinhood Chain and Monad are refused with `400 UNSUPPORTED_CHAIN` and a pointer to their own routes." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "Registry id." }, "enabled": { "type": "boolean", "description": "The rollup and the tape both run." }, "tape": { "type": "boolean", "description": "The chain's trade tape runs." }, "public": { "type": "boolean", "description": "Served to callers without a key." }, "recentAt": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "staleSec": { "type": [ "integer", "null" ], "description": "Seconds since the last rollup pass." }, "floorHour": { "type": [ "integer", "null" ], "description": "Oldest hour the backfill has rolled." }, "genesisHour": { "type": [ "integer", "null" ], "description": "The chain's first indexed hour, when this server knows it; often null." }, "backfillComplete": { "type": "boolean", "description": "True once the backfill has reached the first indexed hour." }, "retentionCutoffDay": { "type": [ "integer", "null" ], "description": "UTC day start. Raw trades before it are retired from the database (about 3 days on BNB Chain and Base, 7 on Avalanche today); the hourly and daily rollups keep their history." }, "ingestFloor": { "$ref": "#/components/schemas/IngestFloor" }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 56, "enabled": true, "tape": true, "public": true, "recentAt": 1791020996, "staleSec": 460, "floorHour": 1790787600, "genesisHour": null, "backfillComplete": true, "retentionCutoffDay": 1790726400, "ingestFloor": { "minTradeUsd": 100, "history": [ { "usd": 100, "fromTs": 1790789196 } ] }, "updatedAt": 1791021456137 } } } }, "400": { "description": "`UNSUPPORTED_CHAIN` (unknown chain, a chain with its own routes, or a chain not served to this caller yet).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE`: the store could not be read. Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/{chain}/overview": { "get": { "tags": [ "Avalanche, Base, BNB Chain" ], "operationId": "chainOverview", "summary": "Chain totals", "description": "Last 24 hours (volume, swaps, tokens, venues), distinct wallets per UTC day, venue share, 24 hourly buckets and up to 14 daily rows.\n\nChain-keyed data for Avalanche C-Chain, Base and BNB Chain, served from Chord's rollup tables for the chain (every swap summed by hour, token and venue). Only the trade tape, the prints ticker and the wallet read raw rows, scoped to one token or one wallet and bounded.\n\n- **Access.** No key needed while the chain is public (all three are today). A chain whose tape is off, or that is not public yet, answers `400 UNSUPPORTED_CHAIN` (\"chain N is not served yet\") unless the request carries an `X-API-Key`; those answers are sent `Cache-Control: private`.\n- **Ingest floor.** Every count, volume and print covers trades at or above the chain's floor, returned as `ingestFloor`. BNB Chain runs at $100 today; Avalanche and Base at 0.\n- **Readiness.** `503 NOT_READY` until the chain's rollup has run on this deployment; `503 CHAIN_DATA_UNAVAILABLE` when the store cannot be read. Never treat either as \"no trades\".", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "avalanche", "base", "bnb", "arbitrum", "ethereum", "43114", "8453", "56", "42161", "1" ] }, "description": "The chain, by key or id: `avalanche` or `43114`, `base` or `8453`, `bnb` or `56`, `arbitrum` or `42161`, `ethereum` or `1` (case-insensitive). Arc, Robinhood Chain and Monad are refused with `400 UNSUPPORTED_CHAIN` and a pointer to their own routes." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "last24h": { "type": "object", "properties": { "volUsd": { "type": "number", "description": "" }, "swaps": { "type": "integer", "description": "" }, "tokens": { "type": "integer", "description": "" }, "venues": { "type": "integer", "description": "" }, "sinceHour": { "type": "integer", "description": "Start of the window." } } }, "wallets": { "type": "object", "properties": { "day": { "type": "integer", "description": "Unix time, seconds, UTC." }, "today": { "type": [ "integer", "null" ], "description": "Distinct attributed wallets so far today (UTC); partial." }, "yesterday": { "type": [ "integer", "null" ], "description": "" } }, "description": "Calendar-day counts, never a sliding 24 hours. Null = no day row yet." }, "venues24h": { "type": "array", "items": { "$ref": "#/components/schemas/ChainVenueShare" }, "description": "Biggest first." }, "hourly24": { "type": "array", "items": { "type": "object", "properties": { "hour": { "type": "integer", "description": "" }, "volUsd": { "type": "number", "description": "" }, "swaps": { "type": "integer", "description": "" } } }, "description": "Oldest first." }, "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "integer", "description": "" }, "swaps": { "type": "integer", "description": "" }, "volUsd": { "type": "number", "description": "" }, "tokens": { "type": "integer", "description": "" }, "wallets": { "type": "integer", "description": "Attributed wallets only." }, "venues": { "type": "integer", "description": "" } } }, "description": "Up to 14 days, oldest first. The first day of a young tape is partial." }, "coverage": { "$ref": "#/components/schemas/ChainCoverage" }, "ingestFloor": { "$ref": "#/components/schemas/IngestFloor" }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 56, "last24h": { "volUsd": 1014438316.7825807, "swaps": 1725125, "tokens": 4466, "venues": 57, "sinceHour": 1790935200 }, "wallets": { "day": 1790985600, "today": 52979, "yesterday": 110488 }, "venues24h": [ { "dex": "pancake_v3", "volUsd": 507002171.3116286, "trades": 802437, "tokens": 581, "sharePct": 49.97861012581327 }, { "dex": "pancake_v2", "volUsd": 243172605.08525935, "trades": 299915, "tokens": 2950, "sharePct": 23.971157345131836 } ], "hourly24": [ { "hour": 1790935200, "volUsd": 32855754.23107098, "swaps": 62895 }, { "hour": 1790938800, "volUsd": 37902743.56465449, "swaps": 74862 } ], "daily": [ { "day": 1790726400, "swaps": 352759, "volUsd": 201620870.33918935, "tokens": 1711, "wallets": 24991, "venues": 31 }, { "day": 1790812800, "swaps": 2017913, "volUsd": 1025889560.5733465, "tokens": 4523, "wallets": 95849, "venues": 55 } ], "coverage": { "recentAt": 1791020331, "stale": false }, "ingestFloor": { "minTradeUsd": 100, "history": [ { "usd": 100, "fromTs": 1790789196 } ] }, "updatedAt": 1791020818773 } } } }, "400": { "description": "`UNSUPPORTED_CHAIN` (unknown chain, a chain with its own routes, or a chain not served to this caller yet).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`NOT_READY` (the chain's rollup has not run on this deployment yet) or `CHAIN_DATA_UNAVAILABLE` (the store could not be read). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/{chain}/tokens": { "get": { "tags": [ "Avalanche, Base, BNB Chain" ], "operationId": "chainTokens", "summary": "Every token traded in the last 24 hours", "description": "The chain's 24-hour board: price on the busiest venue, change, volume split, trade counts and the dominant venue for every token that traded, with symbol, name and decimals read from the contract. There is no curated list on these chains yet: rows carry no logo, no `listed` flag, no trader count and no wash or impostor flags, so check the address before trusting a symbol.\n\nChain-keyed data for Avalanche C-Chain, Base and BNB Chain, served from Chord's rollup tables for the chain (every swap summed by hour, token and venue). Only the trade tape, the prints ticker and the wallet read raw rows, scoped to one token or one wallet and bounded.\n\n- **Access.** No key needed while the chain is public (all three are today). A chain whose tape is off, or that is not public yet, answers `400 UNSUPPORTED_CHAIN` (\"chain N is not served yet\") unless the request carries an `X-API-Key`; those answers are sent `Cache-Control: private`.\n- **Ingest floor.** Every count, volume and print covers trades at or above the chain's floor, returned as `ingestFloor`. BNB Chain runs at $100 today; Avalanche and Base at 0.\n- **Readiness.** `503 NOT_READY` until the chain's rollup has run on this deployment; `503 CHAIN_DATA_UNAVAILABLE` when the store cannot be read. Never treat either as \"no trades\".", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "avalanche", "base", "bnb", "arbitrum", "ethereum", "43114", "8453", "56", "42161", "1" ] }, "description": "The chain, by key or id: `avalanche` or `43114`, `base` or `8453`, `bnb` or `56`, `arbitrum` or `42161`, `ethereum` or `1` (case-insensitive). Arc, Robinhood Chain and Monad are refused with `400 UNSUPPORTED_CHAIN` and a pointer to their own routes." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 }, "description": "" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "volume", "trades", "change" ], "default": "volume" }, "description": "Descending." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "sinceHour": { "type": "integer", "description": "" }, "sort": { "type": "string", "description": "" }, "total": { "type": "integer", "description": "Tokens that traded in the window." }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/ChainTokenRow" } }, "coverage": { "$ref": "#/components/schemas/ChainCoverage" }, "ingestFloor": { "$ref": "#/components/schemas/IngestFloor" }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 56, "sinceHour": 1790935200, "sort": "volume", "total": 4477, "tokens": [ { "address": "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c", "symbol": "WBNB", "name": "Wrapped BNB", "decimals": 18, "logoURI": null, "priceUsd": 767.6455496451134, "change24hPct": -1.2492564760959057, "volume24h": 166967025.3366614, "buyVolume24h": 82320162.1387899, "sellVolume24h": 84646863.19787142, "trades24h": 249872, "buys24h": 126268, "sells24h": 123604, "dominantDex": "pancake_v3", "lastTradeTs": 1791020960 }, { "address": "0x4fa7c69a7b69f8bc48233024d546bc299d6b03bf", "symbol": "quq", "name": "quq", "decimals": 18, "logoURI": null, "priceUsd": 0.0016094473421225778, "change24hPct": -0.02009274621601609, "volume24h": 117639331.46884526, "buyVolume24h": 58830955.6143909, "sellVolume24h": 58808375.85445432, "trades24h": 23746, "buys24h": 11867, "sells24h": 11879, "dominantDex": "pancake_v3", "lastTradeTs": 1791020960 } ], "coverage": { "recentAt": 1791020996, "stale": false }, "ingestFloor": { "minTradeUsd": 100, "history": [ { "usd": 100, "fromTs": 1790789196 } ] }, "updatedAt": 1791021450415 } } } }, "400": { "description": "`UNSUPPORTED_CHAIN` (unknown chain, a chain with its own routes, or a chain not served to this caller yet), or `BAD_LIMIT` / `BAD_SORT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`NOT_READY` (the chain's rollup has not run on this deployment yet) or `CHAIN_DATA_UNAVAILABLE` (the store could not be read). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/{chain}/prints": { "get": { "tags": [ "Avalanche, Base, BNB Chain" ], "operationId": "chainPrints", "summary": "Latest prints across the chain", "description": "The newest swaps of tokens on the chain's 24-hour board, newest first: a ticker, not a tape. It looks back ten minutes, skips trades under $1, keeps at most three prints a token so one busy pair does not fill it, and is shared for 10 seconds per chain. For one token's full tape use `/chains/{chain}/token/{address}/trades`.\n\nChain-keyed data for Avalanche C-Chain, Base and BNB Chain, served from Chord's rollup tables for the chain (every swap summed by hour, token and venue). Only the trade tape, the prints ticker and the wallet read raw rows, scoped to one token or one wallet and bounded.\n\n- **Access.** No key needed while the chain is public (all three are today). A chain whose tape is off, or that is not public yet, answers `400 UNSUPPORTED_CHAIN` (\"chain N is not served yet\") unless the request carries an `X-API-Key`; those answers are sent `Cache-Control: private`.\n- **Ingest floor.** Every count, volume and print covers trades at or above the chain's floor, returned as `ingestFloor`. BNB Chain runs at $100 today; Avalanche and Base at 0.\n- **Readiness.** `503 NOT_READY` until the chain's rollup has run on this deployment; `503 CHAIN_DATA_UNAVAILABLE` when the store cannot be read. Never treat either as \"no trades\".", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "avalanche", "base", "bnb", "arbitrum", "ethereum", "43114", "8453", "56", "42161", "1" ] }, "description": "The chain, by key or id: `avalanche` or `43114`, `base` or `8453`, `bnb` or `56`, `arbitrum` or `42161`, `ethereum` or `1` (case-insensitive). Arc, Robinhood Chain and Monad are refused with `400 UNSUPPORTED_CHAIN` and a pointer to their own routes." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "prints": { "type": "array", "items": { "type": "object", "properties": { "tx": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$", "description": "Transaction hash." }, "logIndex": { "type": "integer", "description": "" }, "block": { "type": "integer", "description": "" }, "dex": { "type": "string", "description": "" }, "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "usd": { "type": "number", "description": "" }, "priceUsd": { "type": "number", "description": "" }, "ts": { "type": "integer", "description": "Unix time, seconds, UTC." }, "symbol": { "type": "string", "description": "From the board." } } } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 56, "prints": [ { "tx": "0xfd35e2957d9660bddbef974222d8f4cf0960aa00ffbb560b437eeda98921124d", "logIndex": 322, "block": 125464252, "dex": "uniswap_v4", "token": "0xca750ef65f295bbecd685abf54e82caf297bdb61", "side": "sell", "usd": 374.6517520746725, "priceUsd": 196.98795013758274, "ts": 1791021448, "symbol": "SKHYB" }, { "tx": "0x8eb8fb435526573f238417c155ebd7ad95ff73dae108eed0965db4bb7d84f7f3", "logIndex": 175, "block": 125464252, "dex": "pancake_infinity_cl", "token": "0x7ec43cf65f1663f820427c62a5780b8f2e25593a", "side": "buy", "usd": 109.53620868310122, "priceUsd": 0.052400254396345075, "ts": 1791021448, "symbol": "LAB" } ], "updatedAt": 1791021450656 } } } }, "400": { "description": "`UNSUPPORTED_CHAIN` (unknown chain, a chain with its own routes, or a chain not served to this caller yet), or `BAD_LIMIT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`NOT_READY` (the chain's rollup has not run on this deployment yet) or `CHAIN_DATA_UNAVAILABLE` (the store could not be read). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/{chain}/token/{address}": { "get": { "tags": [ "Avalanche, Base, BNB Chain" ], "operationId": "chainToken", "summary": "One token: hourly tape and venue split", "description": "The token's identity (read from the contract), 24-hour stats, an hourly series (1–720 hours) and the venue split for the window. `404 UNKNOWN_TOKEN` when the chain's rollups have never seen the token trade; the same address on another chain is another token. For a price of a token Chord has not seen trade, `/ref-price` asks CoinGecko.\n\nChain-keyed data for Avalanche C-Chain, Base and BNB Chain, served from Chord's rollup tables for the chain (every swap summed by hour, token and venue). Only the trade tape, the prints ticker and the wallet read raw rows, scoped to one token or one wallet and bounded.\n\n- **Access.** No key needed while the chain is public (all three are today). A chain whose tape is off, or that is not public yet, answers `400 UNSUPPORTED_CHAIN` (\"chain N is not served yet\") unless the request carries an `X-API-Key`; those answers are sent `Cache-Control: private`.\n- **Ingest floor.** Every count, volume and print covers trades at or above the chain's floor, returned as `ingestFloor`. BNB Chain runs at $100 today; Avalanche and Base at 0.\n- **Readiness.** `503 NOT_READY` until the chain's rollup has run on this deployment; `503 CHAIN_DATA_UNAVAILABLE` when the store cannot be read. Never treat either as \"no trades\".", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "avalanche", "base", "bnb", "arbitrum", "ethereum", "43114", "8453", "56", "42161", "1" ] }, "description": "The chain, by key or id: `avalanche` or `43114`, `base` or `8453`, `bnb` or `56`, `arbitrum` or `42161`, `ethereum` or `1` (case-insensitive). Arc, Robinhood Chain and Monad are refused with `400 UNSUPPORTED_CHAIN` and a pointer to their own routes." }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "Token address. The zero address means the chain's wrapped native token (WAVAX, WETH, WBNB)." }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 720, "default": 168 }, "description": "Hourly buckets to return." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "token": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "symbol": { "type": [ "string", "null" ], "description": "" }, "name": { "type": [ "string", "null" ], "description": "" }, "decimals": { "type": [ "integer", "null" ], "description": "" }, "logoURI": { "type": "null" } } }, "hours": { "type": "integer", "description": "" }, "stats24h": { "type": "object", "properties": { "volUsd": { "type": "number", "description": "" }, "buyUsd": { "type": "number", "description": "" }, "sellUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "buys": { "type": "integer", "description": "" }, "sells": { "type": "integer", "description": "" }, "lastTs": { "type": "integer", "description": "Unix time, seconds, UTC." }, "dominantDex": { "type": [ "string", "null" ], "description": "" }, "priceUsd": { "type": [ "number", "null" ], "description": "Last print on the dominant venue." }, "priceThen": { "type": [ "number", "null" ], "description": "Price 24 hours ago, same rule." }, "change24hPct": { "type": [ "number", "null" ], "description": "" }, "sinceHour": { "type": "integer", "description": "" } } }, "series": { "type": "array", "items": { "type": "object", "properties": { "hour": { "type": "integer", "description": "" }, "volUsd": { "type": "number", "description": "" }, "buyUsd": { "type": "number", "description": "" }, "sellUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "buys": { "type": "integer", "description": "" }, "sells": { "type": "integer", "description": "" }, "priceLast": { "type": [ "number", "null" ], "description": "The busiest venue's last print in the hour." } } }, "description": "Oldest first. Hours without a trade are absent." }, "byDex": { "type": "array", "items": { "type": "object", "properties": { "dex": { "type": "string", "description": "" }, "volUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "sharePct": { "type": "number", "description": "" } } }, "description": "Over the requested window, biggest first." }, "coverage": { "$ref": "#/components/schemas/ChainCoverage" }, "ingestFloor": { "$ref": "#/components/schemas/IngestFloor" }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 56, "token": { "address": "0x7130d2a12b9bcbfae4f2634d864a1ee1ce3ead9c", "symbol": "BTCB", "name": "BTCB Token", "decimals": 18, "logoURI": null }, "hours": 2, "stats24h": { "volUsd": 60117802.11906611, "buyUsd": 28027904.632707972, "sellUsd": 32089897.486358132, "trades": 43182, "buys": 20811, "sells": 22371, "lastTs": 1791020918, "dominantDex": "pancake_v3", "priceUsd": 84842.07226361385, "priceThen": 86518.97620817002, "change24hPct": -1.93819207999113, "sinceHour": 1790935200 }, "series": [ { "hour": 1791014400, "volUsd": 335885.749755259, "buyUsd": 157624.90195060932, "sellUsd": 178260.84780464956, "trades": 500, "buys": 259, "sells": 241, "priceLast": 84615.63679704415 }, { "hour": 1791018000, "volUsd": 499369.02600572666, "buyUsd": 84656.32485821295, "sellUsd": 414712.70114751335, "trades": 636, "buys": 166, "sells": 470, "priceLast": 84842.07226361385 } ], "byDex": [ { "dex": "pancake_v3", "volUsd": 712878.8358403383, "trades": 920, "sharePct": 85.34866923578463 }, { "dex": "uniswap_v3", "volUsd": 100444.15196685962, "trades": 98, "sharePct": 12.025570506357985 } ], "coverage": { "recentAt": 1791020996, "stale": false }, "ingestFloor": { "minTradeUsd": 100, "history": [ { "usd": 100, "fromTs": 1790789196 } ] }, "updatedAt": 1791021450886 } } } }, "400": { "description": "`UNSUPPORTED_CHAIN` (unknown chain, a chain with its own routes, or a chain not served to this caller yet), or `BAD_ADDRESS` / `BAD_HOURS`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`UNKNOWN_TOKEN`: no indexed trades for this token on this chain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`NOT_READY` (the chain's rollup has not run on this deployment yet) or `CHAIN_DATA_UNAVAILABLE` (the store could not be read). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/{chain}/token/{address}/ref-price": { "get": { "tags": [ "Avalanche, Base, BNB Chain" ], "operationId": "chainTokenRefPrice", "summary": "Reference price from CoinGecko", "description": "CoinGecko's price and 24-hour change for a token by contract address, for a token Chord's index has not seen trade (or to cross-check one it has). Not Chord's own data: the answer says so in `source`. Cached two minutes; `ageS` is the age of the cached CoinGecko answer.\n\nChain-keyed data for Avalanche C-Chain, Base and BNB Chain, served from Chord's rollup tables for the chain (every swap summed by hour, token and venue). Only the trade tape, the prints ticker and the wallet read raw rows, scoped to one token or one wallet and bounded.\n\n- **Access.** No key needed while the chain is public (all three are today). A chain whose tape is off, or that is not public yet, answers `400 UNSUPPORTED_CHAIN` (\"chain N is not served yet\") unless the request carries an `X-API-Key`; those answers are sent `Cache-Control: private`.\n- **Ingest floor.** Every count, volume and print covers trades at or above the chain's floor, returned as `ingestFloor`. BNB Chain runs at $100 today; Avalanche and Base at 0.\n- **Readiness.** `503 NOT_READY` until the chain's rollup has run on this deployment; `503 CHAIN_DATA_UNAVAILABLE` when the store cannot be read. Never treat either as \"no trades\".", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "avalanche", "base", "bnb", "arbitrum", "ethereum", "43114", "8453", "56", "42161", "1" ] }, "description": "The chain, by key or id: `avalanche` or `43114`, `base` or `8453`, `bnb` or `56`, `arbitrum` or `42161`, `ethereum` or `1` (case-insensitive). Arc, Robinhood Chain and Monad are refused with `400 UNSUPPORTED_CHAIN` and a pointer to their own routes." }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "Token address. The zero address means the chain's wrapped native token (WAVAX, WETH, WBNB)." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "priceUsd": { "type": "number", "description": "" }, "change24hPct": { "type": [ "number", "null" ], "description": "" }, "source": { "type": "string", "const": "coingecko" }, "ageS": { "type": "integer", "description": "Seconds since CoinGecko answered." } } }, "example": { "chain": 56, "address": "0x7130d2a12b9bcbfae4f2634d864a1ee1ce3ead9c", "priceUsd": 84397, "change24hPct": -2.11, "source": "coingecko", "ageS": 0 } } } }, "400": { "description": "`UNSUPPORTED_CHAIN` (unknown chain, a chain with its own routes, or a chain not served to this caller yet), or `BAD_ADDRESS`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`NOT_LISTED`: CoinGecko does not list this token on this chain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`UNAVAILABLE`: CoinGecko did not answer. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/{chain}/token/{address}/trades": { "get": { "tags": [ "Avalanche, Base, BNB Chain" ], "operationId": "chainTokenTrades", "summary": "Trade tape", "description": "The token's swaps straight from the raw tape, newest first: venue, side, size, USD, price, block, wallet (`null` for a router or an unattributed trade, never a guess) and pool. Keyset-paged: pass `nextBefore` back as `before` for the next page; `nextBefore` is null on the last one. The raw tape is short on these chains (see `retentionCutoffDay` on `/status`), so paging stops there.\n\nChain-keyed data for Avalanche C-Chain, Base and BNB Chain, served from Chord's rollup tables for the chain (every swap summed by hour, token and venue). Only the trade tape, the prints ticker and the wallet read raw rows, scoped to one token or one wallet and bounded.\n\n- **Access.** No key needed while the chain is public (all three are today). A chain whose tape is off, or that is not public yet, answers `400 UNSUPPORTED_CHAIN` (\"chain N is not served yet\") unless the request carries an `X-API-Key`; those answers are sent `Cache-Control: private`.\n- **Ingest floor.** Every count, volume and print covers trades at or above the chain's floor, returned as `ingestFloor`. BNB Chain runs at $100 today; Avalanche and Base at 0.\n- **Readiness.** `503 NOT_READY` until the chain's rollup has run on this deployment; `503 CHAIN_DATA_UNAVAILABLE` when the store cannot be read. Never treat either as \"no trades\".", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "avalanche", "base", "bnb", "arbitrum", "ethereum", "43114", "8453", "56", "42161", "1" ] }, "description": "The chain, by key or id: `avalanche` or `43114`, `base` or `8453`, `bnb` or `56`, `arbitrum` or `42161`, `ethereum` or `1` (case-insensitive). Arc, Robinhood Chain and Monad are refused with `400 UNSUPPORTED_CHAIN` and a pointer to their own routes." }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "Token address. The zero address means the chain's wrapped native token (WAVAX, WETH, WBNB)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Newest rows." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{1,12}(:\\d{1,15}:\\d{1,9})?$" }, "description": "Exclusive cursor: the previous page's `nextBefore` (`ts:block:logIndex`), or a Unix second." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "trades": { "type": "array", "items": { "type": "object", "properties": { "tx": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$", "description": "Transaction hash." }, "logIndex": { "type": "integer", "description": "" }, "block": { "type": "integer", "description": "" }, "dex": { "type": "string", "description": "" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "tokenAmt": { "type": "number", "description": "Whole tokens." }, "usd": { "type": "number", "description": "" }, "priceUsd": { "type": "number", "description": "" }, "ts": { "type": "integer", "description": "Unix time, seconds, UTC." }, "wallet": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "pool": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." } } } }, "nextBefore": { "type": [ "string", "null" ], "description": "Cursor for the next page; null when this page is not full." }, "ingestFloor": { "$ref": "#/components/schemas/IngestFloor" }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 56, "token": "0x7130d2a12b9bcbfae4f2634d864a1ee1ce3ead9c", "trades": [ { "tx": "0x92fdb5120761de73892df232e459c1e93bd540160abf8123235d24b6a7544f65", "logIndex": 116, "block": 125464201, "dex": "pancake_v3", "side": "buy", "tokenAmt": 0.003505439793265937, "usd": 296.55131688178034, "priceUsd": 84597.46404758256, "ts": 1791021425, "wallet": "0x7d63e553f87e560528ecd18e3d801ef4c7144313", "pool": "0x247f51881d1e3ae0f759afb801413a6c948ef442" }, { "tx": "0xbc749bf541475ff782ea186a076614a6634ace0abe6f855d1b4f6f7ff871055f", "logIndex": 138, "block": 125464200, "dex": "pancake_v3", "side": "sell", "tokenAmt": 0.001923013554163473, "usd": 162.647334016205, "priceUsd": 84579.40073488351, "ts": 1791021425, "wallet": "0x939572264f180637d6a0f62aac7df9a4387146bd", "pool": "0x247f51881d1e3ae0f759afb801413a6c948ef442" } ], "nextBefore": "1791021425:125464200:138", "ingestFloor": { "minTradeUsd": 100, "history": [ { "usd": 100, "fromTs": 1790789196 } ] }, "updatedAt": 1791021451693 } } } }, "400": { "description": "`UNSUPPORTED_CHAIN` (unknown chain, a chain with its own routes, or a chain not served to this caller yet), or `BAD_ADDRESS` / `BAD_LIMIT` / `BAD_BEFORE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`NOT_READY` (the chain's rollup has not run on this deployment yet) or `CHAIN_DATA_UNAVAILABLE` (the store could not be read). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/{chain}/venues": { "get": { "tags": [ "Avalanche, Base, BNB Chain" ], "operationId": "chainVenues", "summary": "Venue share over a window", "description": "Per-venue volume, trades and share for 1–30 UTC days, with a daily series per venue. The first day of a young tape is partial.\n\nChain-keyed data for Avalanche C-Chain, Base and BNB Chain, served from Chord's rollup tables for the chain (every swap summed by hour, token and venue). Only the trade tape, the prints ticker and the wallet read raw rows, scoped to one token or one wallet and bounded.\n\n- **Access.** No key needed while the chain is public (all three are today). A chain whose tape is off, or that is not public yet, answers `400 UNSUPPORTED_CHAIN` (\"chain N is not served yet\") unless the request carries an `X-API-Key`; those answers are sent `Cache-Control: private`.\n- **Ingest floor.** Every count, volume and print covers trades at or above the chain's floor, returned as `ingestFloor`. BNB Chain runs at $100 today; Avalanche and Base at 0.\n- **Readiness.** `503 NOT_READY` until the chain's rollup has run on this deployment; `503 CHAIN_DATA_UNAVAILABLE` when the store cannot be read. Never treat either as \"no trades\".", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "avalanche", "base", "bnb", "arbitrum", "ethereum", "43114", "8453", "56", "42161", "1" ] }, "description": "The chain, by key or id: `avalanche` or `43114`, `base` or `8453`, `bnb` or `56`, `arbitrum` or `42161`, `ethereum` or `1` (case-insensitive). Arc, Robinhood Chain and Monad are refused with `400 UNSUPPORTED_CHAIN` and a pointer to their own routes." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "description": "Window length, in UTC days including today." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "days": { "type": "integer", "description": "" }, "since": { "type": "integer", "description": "Unix time, seconds, UTC." }, "venues": { "type": "array", "items": { "type": "object", "properties": { "dex": { "type": "string", "description": "" }, "volUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "sharePct": { "type": "number", "description": "" }, "series": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "integer", "description": "" }, "volUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "tokens": { "type": "integer", "description": "" } } } } } }, "description": "Biggest first." }, "totals": { "type": "object", "properties": { "volUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" } } }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 56, "days": 2, "since": 1790899200, "venues": [ { "dex": "pancake_v3", "volUsd": 736112650.6777563, "trades": 1132649, "sharePct": 48.37984424468907, "series": [ { "day": 1790899200, "volUsd": 580832396.3483784, "trades": 883596, "tokens": 576 }, { "day": 1790985600, "volUsd": 155280254.32937792, "trades": 249053, "tokens": 430 } ] }, { "dex": "pancake_infinity_cl", "volUsd": 315145928.03220856, "trades": 871769, "sharePct": 20.712469617942627, "series": [ { "day": 1790899200, "volUsd": 249510270.7062881, "trades": 732838, "tokens": 166 }, { "day": 1790985600, "volUsd": 65635657.32592046, "trades": 138931, "tokens": 128 } ] } ], "totals": { "volUsd": 1521527533.1494346, "trades": 2819913 }, "updatedAt": 1791021451942 } } } }, "400": { "description": "`UNSUPPORTED_CHAIN` (unknown chain, a chain with its own routes, or a chain not served to this caller yet), or `BAD_DAYS`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`NOT_READY` (the chain's rollup has not run on this deployment yet) or `CHAIN_DATA_UNAVAILABLE` (the store could not be read). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/{chain}/wallet/{address}/trades": { "get": { "tags": [ "Avalanche, Base, BNB Chain" ], "operationId": "chainWalletTrades", "summary": "A wallet's swaps", "description": "The wallet's swaps on the chain, newest first, each with the token and its symbol. Keyset-paged: pass `nextBefore` back as `before` for the next page; `nextBefore` is null on the last one.\n\n**The list covers the raw tape only**: the last few days the database keeps on these chains (about 3 on BNB Chain and Base, 7 on Avalanche today). `window.fromTs` is where it starts. Older days are counted in the wallet route named by `olderHistory`, as totals per token, not as a list. Say how far back the list goes when you show it.\n\n- `wallet` on a trade is the address the tape attributed it to; a swap sent through a router that the tape could not attribute is not in the list.\n- Trades under the chain's ingest floor are not in the tape (BNB Chain: $100).\n\nChain-keyed data for Avalanche C-Chain, Base and BNB Chain, served from Chord's rollup tables for the chain (every swap summed by hour, token and venue). Only the trade tape, the prints ticker and the wallet read raw rows, scoped to one token or one wallet and bounded.\n\n- **Access.** No key needed while the chain is public (all three are today). A chain whose tape is off, or that is not public yet, answers `400 UNSUPPORTED_CHAIN` (\"chain N is not served yet\") unless the request carries an `X-API-Key`; those answers are sent `Cache-Control: private`.\n- **Ingest floor.** Every count, volume and print covers trades at or above the chain's floor, returned as `ingestFloor`. BNB Chain runs at $100 today; Avalanche and Base at 0.\n- **Readiness.** `503 NOT_READY` until the chain's rollup has run on this deployment; `503 CHAIN_DATA_UNAVAILABLE` when the store cannot be read. Never treat either as \"no trades\".", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "avalanche", "base", "bnb", "arbitrum", "ethereum", "43114", "8453", "56", "42161", "1" ] }, "description": "The chain, by key or id: `avalanche` or `43114`, `base` or `8453`, `bnb` or `56`, `arbitrum` or `42161`, `ethereum` or `1` (case-insensitive). Arc, Robinhood Chain and Monad are refused with `400 UNSUPPORTED_CHAIN` and a pointer to their own routes." }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "Wallet address." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Newest rows." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{1,12}(:\\d{1,15}:\\d{1,9})?$" }, "description": "Exclusive cursor: the previous page's `nextBefore` (`ts:block:logIndex`), or a Unix second." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "window": { "type": "object", "properties": { "fromTs": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "toTs": { "type": "integer", "description": "Unix time, seconds, UTC." } }, "description": "The span the list can cover. `fromTs` null = the chain has no raw day yet." }, "history": { "type": "string", "description": "Always `raw`: this list never reads the data lake." }, "trades": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "integer", "description": "Unix time, seconds, UTC." }, "tx": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$", "description": "Transaction hash." }, "logIndex": { "type": "integer", "description": "" }, "block": { "type": "integer", "description": "" }, "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "symbol": { "type": [ "string", "null" ], "description": "" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "tokenAmt": { "type": "number", "description": "Whole tokens." }, "usd": { "type": "number", "description": "" }, "priceUsd": { "type": "number", "description": "" }, "dex": { "type": "string", "description": "" } } }, "description": "Newest first." }, "nextBefore": { "type": [ "string", "null" ], "description": "Cursor for the next page; null when this page is not full." }, "olderHistory": { "type": [ "string", "null" ], "description": "Path of the wallet route that counts the days before `window.fromTs`." }, "ingestFloor": { "$ref": "#/components/schemas/IngestFloor" } } }, "example": { "chain": 56, "wallet": "0x2cf971cb78b7a3cdc0b2044a11abd7392b796c2d", "window": { "fromTs": 1791417600, "toTs": 1791746566 }, "history": "raw", "trades": [ { "ts": 1791746543, "tx": "0x330db50d0c397734e4d61fc2659b053527a9076f516b00050d4cceed47cf9c7e", "logIndex": 50, "block": 127074619, "token": "0x4fa7c69a7b69f8bc48233024d546bc299d6b03bf", "side": "sell", "tokenAmt": 950204.2671867504, "usd": 1519.2258102727808, "priceUsd": 0.0015988412836439056, "dex": "pancake_v3", "symbol": "quq" }, { "ts": 1791746523, "tx": "0x4e1457e8bdc7d83db90ce6fed43a8092f71814c57834ecad38ec4746b47c11c1", "logIndex": 45, "block": 127074574, "token": "0x4fa7c69a7b69f8bc48233024d546bc299d6b03bf", "side": "buy", "tokenAmt": 855183.3425646495, "usd": 1367.5757736974172, "priceUsd": 0.0015991609116194076, "dex": "pancake_v3", "symbol": "quq" } ], "nextBefore": "1791746523:127074574:45", "olderHistory": "/v1/chains/bnb/wallet/0x2cf971cb78b7a3cdc0b2044a11abd7392b796c2d", "ingestFloor": { "minTradeUsd": 100, "history": [ { "usd": 100, "fromTs": 1790789196 } ] } } } } }, "400": { "description": "`UNSUPPORTED_CHAIN` (unknown chain, a chain with its own routes, or a chain not served to this caller yet), or `BAD_ADDRESS` / `BAD_LIMIT` / `BAD_BEFORE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`NOT_READY` (the chain's rollup has not run on this deployment yet) or `CHAIN_DATA_UNAVAILABLE` (the store could not be read). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/{chain}/wallet/{address}": { "get": { "tags": [ "Avalanche, Base, BNB Chain" ], "operationId": "chainWallet", "summary": "One wallet's swaps and PnL", "description": "A wallet's swaps on the chain and an average-cost PnL over them. **The window is short**: the database keeps the raw tape for a few days on these chains (about 3 on BNB Chain and Base, 7 on Avalanche today), and older days come from Chord's data lake only where its days run without a gap up to that window. `window` says how far back the numbers go and `history` where they came from (`raw`, `raw+lake`, or `raw (lake unavailable)`). Say so when you show the number.\n\n- A buy adds tokens and cost; a sell realizes proceeds minus the average cost of the part the window saw bought.\n- A sell with nothing bought in the window has no cost basis: it is counted in `soldWithoutBasisUsd`, never as profit.\n- `holdsTokens` is bought minus sold inside the window, priced at the token's last hourly print. It is not the on-chain balance (transfers are not swaps).\n- Trades under the chain's ingest floor are not in the tape (BNB Chain: $100).\n- Past 5,000 swaps in the window the newest 5,000 are kept and `truncated` is true (a bot or a router).\n\nChain-keyed data for Avalanche C-Chain, Base and BNB Chain, served from Chord's rollup tables for the chain (every swap summed by hour, token and venue). Only the trade tape, the prints ticker and the wallet read raw rows, scoped to one token or one wallet and bounded.\n\n- **Access.** No key needed while the chain is public (all three are today). A chain whose tape is off, or that is not public yet, answers `400 UNSUPPORTED_CHAIN` (\"chain N is not served yet\") unless the request carries an `X-API-Key`; those answers are sent `Cache-Control: private`.\n- **Ingest floor.** Every count, volume and print covers trades at or above the chain's floor, returned as `ingestFloor`. BNB Chain runs at $100 today; Avalanche and Base at 0.\n- **Readiness.** `503 NOT_READY` until the chain's rollup has run on this deployment; `503 CHAIN_DATA_UNAVAILABLE` when the store cannot be read. Never treat either as \"no trades\".", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "avalanche", "base", "bnb", "arbitrum", "ethereum", "43114", "8453", "56", "42161", "1" ] }, "description": "The chain, by key or id: `avalanche` or `43114`, `base` or `8453`, `bnb` or `56`, `arbitrum` or `42161`, `ethereum` or `1` (case-insensitive). Arc, Robinhood Chain and Monad are refused with `400 UNSUPPORTED_CHAIN` and a pointer to their own routes." }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "description": "Wallet address." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "window": { "type": "object", "properties": { "fromTs": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "toTs": { "type": "integer", "description": "Unix time, seconds, UTC." }, "days": { "type": [ "integer", "null" ], "description": "" } }, "description": "The span the numbers cover. `fromTs` null = no trades indexed for the wallet." }, "history": { "type": "string", "enum": [ "raw", "raw+lake", "raw (lake unavailable)" ], "description": "Where the window's rows came from." }, "trades": { "type": "integer", "description": "Swaps in the window." }, "truncated": { "type": "boolean", "description": "More than 5,000 swaps in the window: only the newest 5,000 are counted." }, "realizedUsd": { "type": "number", "description": "" }, "unrealizedUsd": { "type": "number", "description": "" }, "totalUsd": { "type": "number", "description": "" }, "volumeUsd": { "type": "number", "description": "" }, "soldWithoutBasisUsd": { "type": "number", "description": "Sell proceeds with no buy in the window to match. Not profit." }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "symbol": { "type": [ "string", "null" ], "description": "" }, "buys": { "type": "integer", "description": "" }, "sells": { "type": "integer", "description": "" }, "boughtUsd": { "type": "number", "description": "" }, "soldUsd": { "type": "number", "description": "" }, "realizedUsd": { "type": "number", "description": "" }, "unrealizedUsd": { "type": "number", "description": "" }, "totalUsd": { "type": "number", "description": "" }, "holdsTokens": { "type": "number", "description": "Bought minus sold in the window, whole tokens." }, "holdsUsd": { "type": "number", "description": "" }, "avgCostUsd": { "type": [ "number", "null" ], "description": "Average cost per token of what is still held." }, "lastPriceUsd": { "type": [ "number", "null" ], "description": "Last hourly print within 7 days." }, "soldWithoutBasisUsd": { "type": "number", "description": "" } } }, "description": "Largest absolute PnL first." }, "recent": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "integer", "description": "Unix time, seconds, UTC." }, "tx": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$", "description": "Transaction hash." }, "logIndex": { "type": "integer", "description": "" }, "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "tokenAmt": { "type": "number", "description": "" }, "usd": { "type": "number", "description": "" }, "priceUsd": { "type": "number", "description": "" }, "dex": { "type": "string", "description": "" }, "symbol": { "type": [ "string", "null" ], "description": "" } } }, "description": "Last 25 swaps, newest first." }, "ingestFloor": { "$ref": "#/components/schemas/IngestFloor" }, "updatedAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." } } }, "example": { "chain": 56, "wallet": "0x34135a8b5cc02d1b579789fb09dd9cec4f8d7c13", "window": { "fromTs": 1790726400, "toTs": 1791021452, "days": 3 }, "history": "raw", "trades": 438, "truncated": false, "realizedUsd": -52.50256178614943, "unrealizedUsd": 264.3511103300407, "totalUsd": 211.84854854389124, "volumeUsd": 1074760.992352269, "soldWithoutBasisUsd": 142196.1744304485, "tokens": [ { "token": "0x7130d2a12b9bcbfae4f2634d864a1ee1ce3ead9c", "symbol": "BTCB", "buys": 82, "sells": 88, "boughtUsd": 232801.99929077973, "soldUsd": 268637.2602480728, "realizedUsd": 332.35056120683566, "unrealizedUsd": 322.78762778211967, "totalUsd": 655.1381889889553, "holdsTokens": 0.48237177905003725, "holdsUsd": 40925.42133609123, "avgCostUsd": 84172.90453490094, "lastPriceUsd": 84842.07226361385, "soldWithoutBasisUsd": 76105.54410439507 }, { "token": "0x2170ed0880ac9a755fd29b2688956bd959f933f8", "symbol": "ETH", "buys": 92, "sells": 96, "boughtUsd": 179038.3807585184, "soldUsd": 167683.46997452437, "realizedUsd": -421.56179009490035, "unrealizedUsd": -58.43651745207899, "totalUsd": -479.99830754697933, "holdsTokens": 14.799424875074559, "holdsUsd": 39691.36613138376, "avgCostUsd": 2685.901849860607, "lastPriceUsd": 2681.9532830787653, "soldWithoutBasisUsd": 28816.45365493667 } ], "recent": [ { "ts": 1791021243, "tx": "0xfacfd422253d675c6f886afffeb849d5a4f50c38cb0a3a5979b73473dd5b4273", "logIndex": 31, "token": "0x7130d2a12b9bcbfae4f2634d864a1ee1ce3ead9c", "side": "buy", "tokenAmt": 0.007796979293366881, "usd": 661.4196898072091, "priceUsd": 84830.24834629204, "dex": "pancake_v3", "symbol": "BTCB" }, { "ts": 1791016125, "tx": "0x06ac8ef3af4d007c08c7a9ca9e7ab666a724e1393c21865fe1d70d7c5825c19b", "logIndex": 76, "token": "0x2170ed0880ac9a755fd29b2688956bd959f933f8", "side": "sell", "tokenAmt": 0.1525057769098823, "usd": 408.73262726748277, "priceUsd": 2680.1124229478096, "dex": "pancake_v3", "symbol": "ETH" } ], "ingestFloor": { "minTradeUsd": 100, "history": [ { "usd": 100, "fromTs": 1790789196 } ] }, "updatedAt": 1791021452229 } } } }, "400": { "description": "`UNSUPPORTED_CHAIN` (unknown chain, a chain with its own routes, or a chain not served to this caller yet), or `BAD_ADDRESS`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE`: the store could not be read. Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/status": { "get": { "tags": [ "Solana data" ], "operationId": "solStatus", "summary": "Is the tape following the chain", "description": "The ingest's own health: the last slot written, how far behind the chain it is, the age of the newest block it has written, swaps per minute, and per-venue decode counters since the ingest started (`decode` is keyed by venue number: 1 pumpswap · 2 pumpfun · 3 meteora_dbc · 4 meteora_damm_v2 · 5 meteora_dlmm · 6 raydium_clmm · 7 orca · 8 raydium_cpmm · 9 raydium_v4 · 10 meteora_pools · 11 raydium_launchlab; the example shows two of the eleven). `ok: false` or a large `blockAgeS` means the numbers on the other routes are behind: say so when you show them. Never cached.\n\nChord's own Solana tape, read-only. No key needed.\n\n- **What it reads.** The swap events of 11 venues: PumpSwap, the pump.fun bonding curve, Meteora DBC, Meteora DAMM v2, Meteora DLMM, Meteora pools (dynamic AMM v1), Raydium CLMM, Raydium CPMM, Raydium AMM v4, Raydium LaunchLab and Orca Whirlpool. Each swap is checked against the pool vaults' balance changes in the same transaction.\n- **What it does not read.** Prop AMMs (SolFi, HumidiFi and the like) and order books. SOL/USDC and other major pairs therefore show far less volume than the whole market; the numbers are accurate for pump.fun, Meteora and Raydium style tokens. Transfers are not seen either: wallet PnL is average cost inside the window.\n- **History.** Live since 2026-10-03 12:01 UTC, plus a backfill of the days before. `coverageSince` on `/chains/solana/overview` says from when totals are complete: quote that field, not a date.\n- **Addresses** are base58 and **case-sensitive**. Never lower-case a mint or a wallet: a lower-cased mint is a different string, refused with `400 BAD_ADDRESS` when it stops being base58 (an `L` becomes `l`) and answered `404 TOKEN_NOT_FOUND` otherwise. Solana has no numeric chain id here: the path segment is the literal `solana`.\n- **Units.** Token amounts are whole tokens (decimals already applied), `quoteAmount` is whole units of the pool's quote (SOL, USDC, USDT or the other token), prices and `*Usd` fields are US dollars. Timestamps, `updatedAt` included, are Unix **seconds**.\n- **Names are untrusted.** `symbol`, `name` and `image` are whatever the token's creator wrote; many mints share a symbol and there are no wash or impostor flags. Identify a token by its mint.\n- **Errors.** `400 BAD_*` for a bad parameter; `400 UNSUPPORTED_CHAIN` if Solana is not public on the deployment and the request has no `X-API-Key`; `503 CHAIN_DATA_UNAVAILABLE` when the Solana store cannot be read in time and `503 CHAIN_NOT_ENABLED` when the lane is off: retry later, never read either as \"no trades\".", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "const": "solana" }, "ok": { "type": "boolean", "description": "The ingest is healthy right now." }, "cursor": { "type": "integer", "description": "Last slot written." }, "genesisSlot": { "type": "integer", "description": "First slot of the live tape." }, "auditCursor": { "type": "integer", "description": "Last slot re-checked against `finalized` (orphaned slots removed, late ones written)." }, "lagSlots": { "type": [ "integer", "null" ], "description": "Slots between the chain head and `cursor`." }, "blockAgeS": { "type": [ "integer", "null" ], "description": "Age of the newest block written, seconds." }, "slotsPerMin": { "type": [ "number", "null" ], "description": "" }, "swapsPerMin": { "type": [ "number", "null" ], "description": "" }, "startedAt": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "solUsd": { "type": [ "number", "null" ], "description": "SOL price the tape is using (from its own SOL/stable swaps)." }, "decode": { "type": "object", "properties": {}, "description": "Venue number → counters since `startedAt`.", "additionalProperties": { "type": "object", "properties": { "events": { "type": "integer", "description": "" }, "swaps": { "type": "integer", "description": "" }, "ok": { "type": "integer", "description": "Swaps whose amounts match the vaults' balance changes exactly." }, "bad": { "type": "integer", "description": "Swaps that do not match." }, "unchecked": { "type": "integer", "description": "Not checkable (a fee paid to a third account, a pool created and seeded in the same transaction)." }, "noParent": { "type": "integer", "description": "" }, "otherEvents": { "type": "integer", "description": "" } } } }, "totals": { "type": [ "object", "null" ], "properties": { "slots": { "type": "integer", "description": "" }, "swaps": { "type": "integer", "description": "" }, "orphaned": { "type": "integer", "description": "" }, "late": { "type": "integer", "description": "" } }, "description": "Since `startedAt`." }, "venues": { "type": "string", "description": "What the tape reads, in words." }, "notCovered": { "type": "string", "description": "What it does not read, in words." }, "public": { "type": "boolean", "description": "Served to callers without a key." }, "gate": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The automatic public gate: `pass`, `liveHours`, `missing24h` (missing slots in 24 hours), `hourCheck` (rollup against raw for the last closed hour), `reasons`." } } }, "example": { "chain": "solana", "ok": false, "cursor": 453384220, "genesisSlot": 452927437, "auditCursor": 453383708, "lagSlots": 2065, "blockAgeS": 15287, "slotsPerMin": 273, "swapsPerMin": 33344, "startedAt": 1791163969, "solUsd": 121.06980743427287, "decode": { "1": { "events": 412502, "swaps": 392156, "ok": 392155, "bad": 1, "unchecked": 0, "noParent": 0, "otherEvents": 20346 }, "2": { "events": 127002, "swaps": 108165, "ok": 108151, "bad": 14, "unchecked": 0, "noParent": 0, "otherEvents": 18837 } }, "totals": { "slots": 5931, "swaps": 740575, "orphaned": 0, "late": 0 }, "venues": "PumpSwap, pump.fun, Meteora (DAMM v2, DLMM, DBC, dynamic pools), Raydium (CLMM, CPMM, v4, LaunchLab) and Orca", "notCovered": "prop AMMs such as SolFi / HumidiFi and order books such as Phoenix are not read, so SOL/USDC-style majors are understated", "public": true, "gate": { "pass": false, "at": 1791166182, "liveHours": 38.1, "missing24h": 0, "hourCheck": { "hour": 497545, "hourlyDiff": 0, "candleDiff": 0 }, "reasons": [ "ingest not healthy right now" ] } } } } }, "400": { "description": "`UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/overview": { "get": { "tags": [ "Solana data" ], "operationId": "solOverview", "summary": "Chain totals", "description": "Last 24 hours on the venues the tape reads: volume, trades, buys, tokens traded, venue share and hourly buckets, plus `coverageSince`. The window never starts before `coverageSince`: `coverageHours` under 24 means a partial day. Cached 30 seconds.\n\nChord's own Solana tape, read-only. No key needed.\n\n- **What it reads.** The swap events of 11 venues: PumpSwap, the pump.fun bonding curve, Meteora DBC, Meteora DAMM v2, Meteora DLMM, Meteora pools (dynamic AMM v1), Raydium CLMM, Raydium CPMM, Raydium AMM v4, Raydium LaunchLab and Orca Whirlpool. Each swap is checked against the pool vaults' balance changes in the same transaction.\n- **What it does not read.** Prop AMMs (SolFi, HumidiFi and the like) and order books. SOL/USDC and other major pairs therefore show far less volume than the whole market; the numbers are accurate for pump.fun, Meteora and Raydium style tokens. Transfers are not seen either: wallet PnL is average cost inside the window.\n- **History.** Live since 2026-10-03 12:01 UTC, plus a backfill of the days before. `coverageSince` on `/chains/solana/overview` says from when totals are complete: quote that field, not a date.\n- **Addresses** are base58 and **case-sensitive**. Never lower-case a mint or a wallet: a lower-cased mint is a different string, refused with `400 BAD_ADDRESS` when it stops being base58 (an `L` becomes `l`) and answered `404 TOKEN_NOT_FOUND` otherwise. Solana has no numeric chain id here: the path segment is the literal `solana`.\n- **Units.** Token amounts are whole tokens (decimals already applied), `quoteAmount` is whole units of the pool's quote (SOL, USDC, USDT or the other token), prices and `*Usd` fields are US dollars. Timestamps, `updatedAt` included, are Unix **seconds**.\n- **Names are untrusted.** `symbol`, `name` and `image` are whatever the token's creator wrote; many mints share a symbol and there are no wash or impostor flags. Identify a token by its mint.\n- **Errors.** `400 BAD_*` for a bad parameter; `400 UNSUPPORTED_CHAIN` if Solana is not public on the deployment and the request has no `X-API-Key`; `503 CHAIN_DATA_UNAVAILABLE` when the Solana store cannot be read in time and `503 CHAIN_NOT_ENABLED` when the lane is off: retry later, never read either as \"no trades\".", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "const": "solana" }, "windowHours": { "type": "integer", "description": "" }, "volumeUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "buys": { "type": "integer", "description": "" }, "tokensTraded": { "type": "integer", "description": "" }, "venues": { "type": "array", "items": { "type": "object", "properties": { "dex": { "type": "string", "description": "Venue id: `pumpswap` · `pumpfun` (bonding curve) · `meteora_dbc` · `meteora_damm_v2` · `meteora_dlmm` · `meteora_pools` (dynamic AMM v1) · `raydium_clmm` · `raydium_cpmm` · `raydium_v4` · `raydium_launchlab` · `orca` (Whirlpool)." }, "volumeUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "share": { "type": "number", "description": "Fraction of the window's volume, 0–1 (not percent)." } } }, "description": "Biggest first." }, "hourly": { "type": "array", "items": { "type": "object", "properties": { "hour": { "type": "integer", "description": "Unix time, seconds, UTC." }, "volumeUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" } } }, "description": "Oldest first; `hour` is the bucket start." }, "coverageSince": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "coverageHours": { "type": "number", "description": "Hours of the 24-hour window the tape covers." }, "cursor": { "type": "integer", "description": "Last slot written." }, "updatedAt": { "type": "integer", "description": "Unix time, SECONDS, when the Solana box built this answer. Unlike the rest of the API (milliseconds)." }, "botTapes": { "type": [ "object", "null" ], "properties": { "tokens": { "type": "integer", "description": "" }, "volumeUsd": { "type": "number", "description": "" }, "rule": { "type": "string", "description": "" } }, "description": "The part of `volumeUsd` made by volume-bot tapes among the board's candidates (see `/chains/solana/tokens`). Null before the first measure." } } }, "example": { "chain": "solana", "windowHours": 24, "volumeUsd": 3120445357.1785517, "trades": 28259618, "buys": 16493707, "tokensTraded": 98530, "venues": [ { "dex": "pumpswap", "volumeUsd": 1420441349.9695024, "trades": 15748395, "share": 0.45520468631241756 }, { "dex": "meteora_pools", "volumeUsd": 464739991.2308222, "trades": 40125, "share": 0.1489338661744846 } ], "hourly": [ { "hour": 1791082800, "volumeUsd": 136078621.887329, "trades": 1510518 }, { "hour": 1791086400, "volumeUsd": 110648628.7027686, "trades": 1442682 } ], "coverageSince": 1790611483, "coverageHours": 24, "cursor": 453384035, "updatedAt": 1791166406 } } } }, "400": { "description": "`UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/tokens": { "get": { "tags": [ "Solana data" ], "operationId": "solTokens", "summary": "Every token traded in the last 24 hours", "description": "The 24-hour board. `volume` ranks the 600 most traded tokens and `trades` the 300 with the most trades; `change` (24-hour price change) and `new` (first seen in the last 24 hours, newest first) rank inside the 600 most traded tokens with at least $5,000 of volume, so a $40 pool moving 900 % is not a mover. Cached 20 seconds.\n\n**Volume-bot tapes and impostors are left out** (`screened` counts them, `all=1` keeps them in with their `screen`). Most of Solana's busiest tokens are wallets trading with themselves: on 13 and 14 October, 265 and 271 of the 400 most traded tokens had under 3 % of their volume from wallets that went one way, about 70 % of the board's volume (one of them printed $150M on $350k of liquidity, 78 wallets each buying and selling ~$1.56M). A token is left out when under 10 % of its 24-hour volume is one-way (`oneWayPct`) unless it is a deep market (at least $250k of SOL / stable liquidity turned over at most 10× in the window: majors whose Solana flow is arbitrage stay). Many tokens still share a symbol.\n\nChord's own Solana tape, read-only. No key needed.\n\n- **What it reads.** The swap events of 11 venues: PumpSwap, the pump.fun bonding curve, Meteora DBC, Meteora DAMM v2, Meteora DLMM, Meteora pools (dynamic AMM v1), Raydium CLMM, Raydium CPMM, Raydium AMM v4, Raydium LaunchLab and Orca Whirlpool. Each swap is checked against the pool vaults' balance changes in the same transaction.\n- **What it does not read.** Prop AMMs (SolFi, HumidiFi and the like) and order books. SOL/USDC and other major pairs therefore show far less volume than the whole market; the numbers are accurate for pump.fun, Meteora and Raydium style tokens. Transfers are not seen either: wallet PnL is average cost inside the window.\n- **History.** Live since 2026-10-03 12:01 UTC, plus a backfill of the days before. `coverageSince` on `/chains/solana/overview` says from when totals are complete: quote that field, not a date.\n- **Addresses** are base58 and **case-sensitive**. Never lower-case a mint or a wallet: a lower-cased mint is a different string, refused with `400 BAD_ADDRESS` when it stops being base58 (an `L` becomes `l`) and answered `404 TOKEN_NOT_FOUND` otherwise. Solana has no numeric chain id here: the path segment is the literal `solana`.\n- **Units.** Token amounts are whole tokens (decimals already applied), `quoteAmount` is whole units of the pool's quote (SOL, USDC, USDT or the other token), prices and `*Usd` fields are US dollars. Timestamps, `updatedAt` included, are Unix **seconds**.\n- **Names are untrusted.** `symbol`, `name` and `image` are whatever the token's creator wrote; many mints share a symbol and there are no wash or impostor flags. Identify a token by its mint.\n- **Errors.** `400 BAD_*` for a bad parameter; `400 UNSUPPORTED_CHAIN` if Solana is not public on the deployment and the request has no `X-API-Key`; `503 CHAIN_DATA_UNAVAILABLE` when the Solana store cannot be read in time and `503 CHAIN_NOT_ENABLED` when the lane is off: retry later, never read either as \"no trades\".", "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "volume", "trades", "change", "new" ], "default": "volume" }, "description": "Descending; `new` = newest first." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "sort": { "type": "string", "description": "" }, "windowHours": { "type": "integer", "description": "" }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/SolTokenRow" } }, "screened": { "type": "object", "properties": { "tokens": { "type": "integer", "description": "Candidates of this board left out." }, "volumeUsd": { "type": "number", "description": "Their 24-hour volume." }, "byReason": { "type": "object", "additionalProperties": true, "description": "Count per `screen` value." }, "rule": { "type": "string", "description": "The rule, in words." }, "measured": { "type": "boolean", "description": "False when the volume screen did not run for this board (the tape's per-wallet rollup is missing or behind): rows are then unscreened for volume." } }, "description": "What the board left out." }, "updatedAt": { "type": "integer", "description": "Unix time, SECONDS, when the Solana box built this answer. Unlike the rest of the API (milliseconds)." } } }, "example": { "sort": "trades", "windowHours": 24, "tokens": [ { "token": "So11111111111111111111111111111111111111112", "symbol": "SOL", "name": "Solana", "image": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/So11111111111111111111111111111111111111112/logo.png", "decimals": 9, "priceUsd": 120.98396092263611, "change24hPct": 1.1310855236659645, "volume24hUsd": 92343484.342816, "trades24h": 668125, "buys24h": 344626, "buyVolume24hUsd": 47132735.284852006, "liquidityUsd": 30496683.315842, "marketCapUsd": null, "pool": "58oQChx4yWmvKdwLLZzBi4ChoCc2fqCUWBkwMihLYQo2", "dex": "raydium_v4", "firstSeen": 1791028889 }, { "token": "Xs3oZwbHvqis4NYcf4YKWmEia2eC84wSiVrcYcTqpH8", "symbol": "SPCXx", "name": "SpaceX xStock", "image": "https://xstocks-metadata.backed.fi/logos/tokens/SPCXx.png", "decimals": 8, "priceUsd": 163.10022589848552, "change24hPct": null, "volume24hUsd": 37511133.496547684, "trades24h": 476322, "buys24h": 230903, "buyVolume24hUsd": 18759541.58185133, "liquidityUsd": 95373.03161138113, "marketCapUsd": 91333037.55386804, "pool": "B7nYoGHqCGoFRiPB4AoT1NqbqrFWJDfiEkD3WNXxSCnt", "dex": "raydium_cpmm", "firstSeen": 1791028946 } ], "updatedAt": 1791166451 } } } }, "400": { "description": "`BAD_LIMIT` / `BAD_SORT`, or `UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/search": { "get": { "tags": [ "Solana data" ], "operationId": "solSearch", "summary": "Find a token by mint, symbol or name", "description": "A mint returns that token (when the tape has seen it trade). Anything else is an exact, case-insensitive match on symbol or name among the tokens the tape has seen, up to 20, ordered by the volume of each token's deepest pool; a leading `$` is ignored. No prefix or substring search. Expect several mints per symbol: show the mint, and pick by liquidity and volume only when the user has not named one.\n\n`volumeUsd` is the main pool's volume since the tape first saw it for a symbol or name match, and the token's 24-hour volume for a mint: a ranking hint, not a window total. Use `/chains/solana/token/{address}` for the token's numbers.\n\nChord's own Solana tape, read-only. No key needed.\n\n- **What it reads.** The swap events of 11 venues: PumpSwap, the pump.fun bonding curve, Meteora DBC, Meteora DAMM v2, Meteora DLMM, Meteora pools (dynamic AMM v1), Raydium CLMM, Raydium CPMM, Raydium AMM v4, Raydium LaunchLab and Orca Whirlpool. Each swap is checked against the pool vaults' balance changes in the same transaction.\n- **What it does not read.** Prop AMMs (SolFi, HumidiFi and the like) and order books. SOL/USDC and other major pairs therefore show far less volume than the whole market; the numbers are accurate for pump.fun, Meteora and Raydium style tokens. Transfers are not seen either: wallet PnL is average cost inside the window.\n- **History.** Live since 2026-10-03 12:01 UTC, plus a backfill of the days before. `coverageSince` on `/chains/solana/overview` says from when totals are complete: quote that field, not a date.\n- **Addresses** are base58 and **case-sensitive**. Never lower-case a mint or a wallet: a lower-cased mint is a different string, refused with `400 BAD_ADDRESS` when it stops being base58 (an `L` becomes `l`) and answered `404 TOKEN_NOT_FOUND` otherwise. Solana has no numeric chain id here: the path segment is the literal `solana`.\n- **Units.** Token amounts are whole tokens (decimals already applied), `quoteAmount` is whole units of the pool's quote (SOL, USDC, USDT or the other token), prices and `*Usd` fields are US dollars. Timestamps, `updatedAt` included, are Unix **seconds**.\n- **Names are untrusted.** `symbol`, `name` and `image` are whatever the token's creator wrote; many mints share a symbol and there are no wash or impostor flags. Identify a token by its mint.\n- **Errors.** `400 BAD_*` for a bad parameter; `400 UNSUPPORTED_CHAIN` if Solana is not public on the deployment and the request has no `X-API-Key`; `503 CHAIN_DATA_UNAVAILABLE` when the Solana store cannot be read in time and `503 CHAIN_NOT_ENABLED` when the lane is off: retry later, never read either as \"no trades\".", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 60 }, "description": "A mint (base58), a symbol or a name." } ], "responses": { "200": { "description": "Matches. An empty `tokens` is a real answer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "const": "solana" }, "query": { "type": "string", "description": "" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "symbol": { "type": [ "string", "null" ], "description": "" }, "name": { "type": [ "string", "null" ], "description": "" }, "image": { "type": [ "string", "null" ], "description": "" }, "priceUsd": { "type": [ "number", "null" ], "description": "" }, "liquidityUsd": { "type": [ "number", "null" ], "description": "" }, "volumeUsd": { "type": [ "number", "null" ], "description": "See above." }, "screen": { "type": [ "string", "null" ], "enum": [ "volume bot", "impostor" ], "description": "Why the boards leave this token out, or null. `volume bot`: under 10 % of its 24-hour volume came from one-way wallets and it is not a deep market (at least $250k of SOL / stable liquidity turned over at most 10× in the window). `impostor`: the ticker of SOL, USDC or USDT, look-alike letters included, on another mint." } } } } } }, "example": { "chain": "solana", "query": "Agency", "tokens": [ { "token": "PGXpPuXMe4jpcjHwC4FCvtu5oMn4izLVRJVkwe3AHaM", "symbol": "Agency", "name": "Agency", "image": "https://pbs.twimg.com/profile_images/2105704660116144128/u2fzyGVC_400x400.jpg", "priceUsd": 0.000002688447447596337, "liquidityUsd": 242806.21490618165, "volumeUsd": 32772996.00219991 }, { "token": "7VertkgF9KLhxxJXHX6uaWuoYZTP9LdGj2bWmVXVpump", "symbol": "Agency", "name": "Agency", "image": "https://ipfs.io/ipfs/bafybeicailrr3iobedoxprzs6evwq3nqxsezdhvxbhpseyhltfmufybxuq", "priceUsd": 0.012402169398382247, "liquidityUsd": 490945.0136094359, "volumeUsd": 30097665.520332042 } ] } } } }, "400": { "description": "`BAD_QUERY` (empty, or longer than 60 characters), or `UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/token/{address}": { "get": { "tags": [ "Solana data" ], "operationId": "solToken", "summary": "One token: stats, pools and hourly tape", "description": "Identity (from the token's metadata), price on the main pool with 1-hour and 24-hour change, fully diluted market cap, liquidity summed over the pools that traded in the last 24 hours, 24-hour volume and trade counts with the venue split, up to 20 pools, and an hourly series.\n\n**Pass `hours` of 24 or more**: the 24-hour totals are summed from the same hourly rows the series returns, so `hours=2` gives the totals of two hours. In `pools`, `volumeUsd` and `swaps` count since the tape first saw the pool, not 24 hours. Cached 10 seconds.\n\nChord's own Solana tape, read-only. No key needed.\n\n- **What it reads.** The swap events of 11 venues: PumpSwap, the pump.fun bonding curve, Meteora DBC, Meteora DAMM v2, Meteora DLMM, Meteora pools (dynamic AMM v1), Raydium CLMM, Raydium CPMM, Raydium AMM v4, Raydium LaunchLab and Orca Whirlpool. Each swap is checked against the pool vaults' balance changes in the same transaction.\n- **What it does not read.** Prop AMMs (SolFi, HumidiFi and the like) and order books. SOL/USDC and other major pairs therefore show far less volume than the whole market; the numbers are accurate for pump.fun, Meteora and Raydium style tokens. Transfers are not seen either: wallet PnL is average cost inside the window.\n- **History.** Live since 2026-10-03 12:01 UTC, plus a backfill of the days before. `coverageSince` on `/chains/solana/overview` says from when totals are complete: quote that field, not a date.\n- **Addresses** are base58 and **case-sensitive**. Never lower-case a mint or a wallet: a lower-cased mint is a different string, refused with `400 BAD_ADDRESS` when it stops being base58 (an `L` becomes `l`) and answered `404 TOKEN_NOT_FOUND` otherwise. Solana has no numeric chain id here: the path segment is the literal `solana`.\n- **Units.** Token amounts are whole tokens (decimals already applied), `quoteAmount` is whole units of the pool's quote (SOL, USDC, USDT or the other token), prices and `*Usd` fields are US dollars. Timestamps, `updatedAt` included, are Unix **seconds**.\n- **Names are untrusted.** `symbol`, `name` and `image` are whatever the token's creator wrote; many mints share a symbol and there are no wash or impostor flags. Identify a token by its mint.\n- **Errors.** `400 BAD_*` for a bad parameter; `400 UNSUPPORTED_CHAIN` if Solana is not public on the deployment and the request has no `X-API-Key`; `503 CHAIN_DATA_UNAVAILABLE` when the Solana store cannot be read in time and `503 CHAIN_NOT_ENABLED` when the lane is off: retry later, never read either as \"no trades\".", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "description": "Token mint, base58, exactly as it appears on-chain." }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 720, "default": 168 }, "description": "Hourly buckets in `hourly`; also the span the 24-hour totals are read from (see above)." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "const": "solana" }, "token": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "symbol": { "type": [ "string", "null" ], "description": "" }, "name": { "type": [ "string", "null" ], "description": "" }, "image": { "type": [ "string", "null" ], "description": "" }, "decimals": { "type": [ "integer", "null" ], "description": "" }, "supply": { "type": [ "number", "null" ], "description": "Whole tokens." }, "firstSeen": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "priceUsd": { "type": [ "number", "null" ], "description": "" }, "change1hPct": { "type": [ "number", "null" ], "description": "" }, "change24hPct": { "type": [ "number", "null" ], "description": "" }, "marketCapUsd": { "type": [ "number", "null" ], "description": "Price × supply." }, "liquidityUsd": { "type": [ "number", "null" ], "description": "Sum over pools that traded in the last 24 hours." }, "volume24hUsd": { "type": "number", "description": "" }, "trades24h": { "type": "integer", "description": "" }, "buys24h": { "type": "integer", "description": "" }, "sells24h": { "type": "integer", "description": "" }, "buyVolume24hUsd": { "type": "number", "description": "" }, "sellVolume24hUsd": { "type": "number", "description": "" }, "venues": { "type": "array", "items": { "type": "object", "properties": { "dex": { "type": "string", "description": "Venue id: `pumpswap` · `pumpfun` (bonding curve) · `meteora_dbc` · `meteora_damm_v2` · `meteora_dlmm` · `meteora_pools` (dynamic AMM v1) · `raydium_clmm` · `raydium_cpmm` · `raydium_v4` · `raydium_launchlab` · `orca` (Whirlpool)." }, "volumeUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" } } }, "description": "24-hour venue split, biggest first." }, "flow24h": { "type": [ "object", "null" ], "properties": { "oneWayPct": { "type": [ "number", "null" ], "description": "As on the board row." }, "screen": { "type": [ "string", "null" ], "enum": [ "volume bot", "impostor" ], "description": "Why the boards leave this token out, or null. `volume bot`: under 10 % of its 24-hour volume came from one-way wallets and it is not a deep market (at least $250k of SOL / stable liquidity turned over at most 10× in the window). `impostor`: the ticker of SOL, USDC or USDT, look-alike letters included, on another mint." }, "wallets": { "type": [ "integer", "null" ], "description": "Distinct wallets in the window." }, "volumeUsd": { "type": [ "number", "null" ], "description": "The window's volume this was measured on." }, "rule": { "type": "string", "description": "" } }, "description": "Who made the 24-hour volume. Null when not measured." }, "pools": { "type": "array", "items": { "type": "object", "properties": { "pool": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "dex": { "type": "string", "description": "Venue id: `pumpswap` · `pumpfun` (bonding curve) · `meteora_dbc` · `meteora_damm_v2` · `meteora_dlmm` · `meteora_pools` (dynamic AMM v1) · `raydium_clmm` · `raydium_cpmm` · `raydium_v4` · `raydium_launchlab` · `orca` (Whirlpool)." }, "quote": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "priceUsd": { "type": [ "number", "null" ], "description": "" }, "liquidityUsd": { "type": [ "number", "null" ], "description": "" }, "volumeUsd": { "type": "number", "description": "Since the tape first saw the pool." }, "swaps": { "type": "integer", "description": "Since the tape first saw the pool." }, "firstSeen": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "lastTrade": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." } } }, "description": "Up to 20; traded in the last hour first, then the deepest." }, "hourly": { "type": "array", "items": { "type": "object", "properties": { "hour": { "type": "integer", "description": "Unix time, seconds, UTC." }, "volumeUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "buys": { "type": "integer", "description": "" } } }, "description": "Oldest first. Hours without a trade are absent." }, "updatedAt": { "type": "integer", "description": "Unix time, SECONDS, when the Solana box built this answer. Unlike the rest of the API (milliseconds)." } } }, "example": { "chain": "solana", "token": "7VertkgF9KLhxxJXHX6uaWuoYZTP9LdGj2bWmVXVpump", "symbol": "Agency", "name": "Agency", "image": "https://ipfs.io/ipfs/bafybeicailrr3iobedoxprzs6evwq3nqxsezdhvxbhpseyhltfmufybxuq", "decimals": 6, "supply": 966189741.871528, "firstSeen": 1791028889, "priceUsd": 0.012471350009671632, "change1hPct": 0, "change24hPct": -33.59296229824511, "marketCapUsd": 12049690.446634114, "liquidityUsd": 492710.3227884476, "volume24hUsd": 22300513.95510154, "trades24h": 98644, "buys24h": 50875, "sells24h": 47769, "buyVolume24hUsd": 10815371.994912628, "sellVolume24hUsd": 11485141.96018891, "venues": [ { "dex": "pumpswap", "volumeUsd": 12526132.33339345, "trades": 59671 }, { "dex": "meteora_dlmm", "volumeUsd": 9716267.646647243, "trades": 27864 } ], "pools": [ { "pool": "CyJwKnLiiY4fmiwqMCSWFSHxo7T9Ubshgs2uRAuJCrk5", "dex": "pumpswap", "quote": "So11111111111111111111111111111111111111112", "priceUsd": 0.012471350009671632, "liquidityUsd": 492426.2442871083, "volumeUsd": 30096468.174518585, "swaps": 152986, "firstSeen": 1791028889, "lastTrade": 1791151092 }, { "pool": "4MRafCAZEk9KLLDJ7YAQSuwAFFtxz3fVLUuyDKySU8Ep", "dex": "meteora_damm_v2", "quote": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "priceUsd": 0.017382927320372235, "liquidityUsd": 277.017254, "volumeUsd": 1947.9255100000016, "swaps": 3651, "firstSeen": 1791067406, "lastTrade": 1791124069 } ], "hourly": [ { "hour": 1791082800, "volumeUsd": 634272.1321694182, "trades": 3874, "buys": 2057 }, { "hour": 1791086400, "volumeUsd": 1392924.1494347786, "trades": 7064, "buys": 3395 } ], "updatedAt": 1791166385 } } } }, "400": { "description": "`BAD_ADDRESS` / `BAD_HOURS`, or `UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`TOKEN_NOT_FOUND`: this mint has not traded on a venue the tape reads since the tape started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/token/{address}/trades": { "get": { "tags": [ "Solana data" ], "operationId": "solTokenTrades", "summary": "Trade tape", "description": "The token's newest swaps across up to 30 of its pools, newest first: side, both amounts, USD, price, venue, pool, wallet and the transaction signature. Each page looks back at most two days from `before` (or from now): an empty page means no swap in that span. A mint the tape has never seen answers an empty list.\n\n- `side`: `buy` = the wallet bought the token, `sell` = it sold it.\n- `tokenAmount` and `quoteAmount` are what the wallet received or paid, fees included, in whole units; `priceUsd` is the pool's execution price.\n- `wallet` is the user account named in the swap instruction: often a bot or an arbitrage contract, sometimes on both sides of one transaction.\n\nChord's own Solana tape, read-only. No key needed.\n\n- **What it reads.** The swap events of 11 venues: PumpSwap, the pump.fun bonding curve, Meteora DBC, Meteora DAMM v2, Meteora DLMM, Meteora pools (dynamic AMM v1), Raydium CLMM, Raydium CPMM, Raydium AMM v4, Raydium LaunchLab and Orca Whirlpool. Each swap is checked against the pool vaults' balance changes in the same transaction.\n- **What it does not read.** Prop AMMs (SolFi, HumidiFi and the like) and order books. SOL/USDC and other major pairs therefore show far less volume than the whole market; the numbers are accurate for pump.fun, Meteora and Raydium style tokens. Transfers are not seen either: wallet PnL is average cost inside the window.\n- **History.** Live since 2026-10-03 12:01 UTC, plus a backfill of the days before. `coverageSince` on `/chains/solana/overview` says from when totals are complete: quote that field, not a date.\n- **Addresses** are base58 and **case-sensitive**. Never lower-case a mint or a wallet: a lower-cased mint is a different string, refused with `400 BAD_ADDRESS` when it stops being base58 (an `L` becomes `l`) and answered `404 TOKEN_NOT_FOUND` otherwise. Solana has no numeric chain id here: the path segment is the literal `solana`.\n- **Units.** Token amounts are whole tokens (decimals already applied), `quoteAmount` is whole units of the pool's quote (SOL, USDC, USDT or the other token), prices and `*Usd` fields are US dollars. Timestamps, `updatedAt` included, are Unix **seconds**.\n- **Names are untrusted.** `symbol`, `name` and `image` are whatever the token's creator wrote; many mints share a symbol and there are no wash or impostor flags. Identify a token by its mint.\n- **Errors.** `400 BAD_*` for a bad parameter; `400 UNSUPPORTED_CHAIN` if Solana is not public on the deployment and the request has no `X-API-Key`; `503 CHAIN_DATA_UNAVAILABLE` when the Solana store cannot be read in time and `503 CHAIN_NOT_ENABLED` when the lane is off: retry later, never read either as \"no trades\".", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "description": "Token mint, base58, exactly as it appears on-chain." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Newest rows." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 4000000000 }, "description": "Exclusive cursor, Unix seconds: rows strictly older than it. Pass the last row's `ts` for the next page. Several swaps can share a second, so a page boundary can skip the rest of that second: overlap with `ts + 1` and drop rows whose `tx` you already have." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "const": "solana" }, "token": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "trades": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "integer", "description": "Unix time, seconds, UTC." }, "slot": { "type": "integer", "description": "" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "tokenAmount": { "type": "number", "description": "Whole tokens." }, "quoteAmount": { "type": "number", "description": "Whole units of the pool's quote." }, "usd": { "type": [ "number", "null" ], "description": "" }, "priceUsd": { "type": [ "number", "null" ], "description": "" }, "dex": { "type": "string", "description": "Venue id: `pumpswap` · `pumpfun` (bonding curve) · `meteora_dbc` · `meteora_damm_v2` · `meteora_dlmm` · `meteora_pools` (dynamic AMM v1) · `raydium_clmm` · `raydium_cpmm` · `raydium_v4` · `raydium_launchlab` · `orca` (Whirlpool)." }, "pool": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "wallet": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "tx": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{64,88}$", "description": "Transaction signature, base58." } } } }, "updatedAt": { "type": "integer", "description": "Unix time, SECONDS, when the Solana box built this answer. Unlike the rest of the API (milliseconds)." } } }, "example": { "chain": "solana", "token": "7VertkgF9KLhxxJXHX6uaWuoYZTP9LdGj2bWmVXVpump", "trades": [ { "ts": 1791151156, "slot": 453384204, "side": "sell", "tokenAmount": 1581.186594, "quoteAmount": 0.161487883, "usd": 19.551313486445476, "priceUsd": 0.012402169398382247, "dex": "pumpswap", "pool": "CyJwKnLiiY4fmiwqMCSWFSHxo7T9Ubshgs2uRAuJCrk5", "wallet": "ckdRDD9onSwL9yHgjEc5VdRx9BPmcsyVH9TjKGYygkY", "tx": "5sT1cLSYjuD3BR4wNbGKTAcFgFLdY2FGxujWukJFQmgLm8i1qi37rQxdZS4EYyRdCuV35dU4Rn7GttkZmU4oe2op" }, { "ts": 1791151147, "slot": 453384173, "side": "buy", "tokenAmount": 2879.134063, "quoteAmount": 0.295798607, "usd": 35.812234413351845, "priceUsd": 0.012401339509037218, "dex": "pumpswap", "pool": "CyJwKnLiiY4fmiwqMCSWFSHxo7T9Ubshgs2uRAuJCrk5", "wallet": "3QZv9xcDELwLqB8SggDJHfVhMTn5YhKtXMCaKUucutm3", "tx": "Vz2VPQCo2j82g6mowse5961MnUEM6koE7VSaVhtVHQKsvkCHZ9HGVMTgbw92vDSJw1ThSDiVGkwn16EucjAK6Ny" } ], "updatedAt": 1791166444 } } } }, "400": { "description": "`BAD_ADDRESS` / `BAD_LIMIT` / `BAD_CURSOR`, or `UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/token/{address}/candles": { "get": { "tags": [ "Solana data" ], "operationId": "solTokenCandles", "summary": "Candles", "description": "OHLCV of ONE pool of the token, in USD: the main pool (traded in the last hour first, then the deepest) unless `pool` names another. Not a volume-weighted blend of every pool: use `/chains/solana/token/{address}` for totals across pools. The window holds `limit` buckets ending with the open one; buckets without a trade are absent. A swap under $1 adds to the volume but does not move the open, high, low or close. Cached 5 seconds for `1m`, 20 seconds otherwise.\n\nChord's own Solana tape, read-only. No key needed.\n\n- **What it reads.** The swap events of 11 venues: PumpSwap, the pump.fun bonding curve, Meteora DBC, Meteora DAMM v2, Meteora DLMM, Meteora pools (dynamic AMM v1), Raydium CLMM, Raydium CPMM, Raydium AMM v4, Raydium LaunchLab and Orca Whirlpool. Each swap is checked against the pool vaults' balance changes in the same transaction.\n- **What it does not read.** Prop AMMs (SolFi, HumidiFi and the like) and order books. SOL/USDC and other major pairs therefore show far less volume than the whole market; the numbers are accurate for pump.fun, Meteora and Raydium style tokens. Transfers are not seen either: wallet PnL is average cost inside the window.\n- **History.** Live since 2026-10-03 12:01 UTC, plus a backfill of the days before. `coverageSince` on `/chains/solana/overview` says from when totals are complete: quote that field, not a date.\n- **Addresses** are base58 and **case-sensitive**. Never lower-case a mint or a wallet: a lower-cased mint is a different string, refused with `400 BAD_ADDRESS` when it stops being base58 (an `L` becomes `l`) and answered `404 TOKEN_NOT_FOUND` otherwise. Solana has no numeric chain id here: the path segment is the literal `solana`.\n- **Units.** Token amounts are whole tokens (decimals already applied), `quoteAmount` is whole units of the pool's quote (SOL, USDC, USDT or the other token), prices and `*Usd` fields are US dollars. Timestamps, `updatedAt` included, are Unix **seconds**.\n- **Names are untrusted.** `symbol`, `name` and `image` are whatever the token's creator wrote; many mints share a symbol and there are no wash or impostor flags. Identify a token by its mint.\n- **Errors.** `400 BAD_*` for a bad parameter; `400 UNSUPPORTED_CHAIN` if Solana is not public on the deployment and the request has no `X-API-Key`; `503 CHAIN_DATA_UNAVAILABLE` when the Solana store cannot be read in time and `503 CHAIN_NOT_ENABLED` when the lane is off: retry later, never read either as \"no trades\".", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "description": "Token mint, base58, exactly as it appears on-chain." }, { "name": "tf", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1m", "5m", "15m", "1h", "4h", "1d" ], "default": "5m" }, "description": "Timeframe." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 }, "description": "Buckets in the window." }, { "name": "pool", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "description": "A pool of this token (from `/chains/solana/token/{address}` `pools`). Default: the main pool." } ], "responses": { "200": { "description": "`pool: null` with no candles = the tape has no priced pool for this mint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "const": "solana" }, "token": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "pool": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "timeframe": { "type": "string", "description": "" }, "candles": { "type": "array", "items": { "type": "object", "properties": { "t": { "type": "integer", "description": "Unix time, seconds, UTC." }, "o": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" }, "l": { "type": "number", "description": "" }, "c": { "type": "number", "description": "" }, "volumeUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" } } }, "description": "Oldest first; `t` is the bucket start." }, "updatedAt": { "type": "integer", "description": "Unix time, SECONDS, when the Solana box built this answer. Unlike the rest of the API (milliseconds)." } } }, "example": { "chain": "solana", "token": "7VertkgF9KLhxxJXHX6uaWuoYZTP9LdGj2bWmVXVpump", "pool": "CyJwKnLiiY4fmiwqMCSWFSHxo7T9Ubshgs2uRAuJCrk5", "timeframe": "1h", "candles": [ { "t": 1791140400, "o": 0.016581499823932228, "h": 0.0167915473875269, "l": 0.013856459444690225, "c": 0.014365569915305174, "volumeUsd": 336302.10729020054, "trades": 2009 }, { "t": 1791144000, "o": 0.014362537896257067, "h": 0.014962869347332729, "l": 0.011578863188337602, "c": 0.014393806600470372, "volumeUsd": 495642.36503098987, "trades": 2632 } ], "updatedAt": 1791166459 } } } }, "400": { "description": "`BAD_ADDRESS` / `BAD_TIMEFRAME` / `BAD_LIMIT`, or `UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/token/{address}/traders": { "get": { "tags": [ "Solana data" ], "operationId": "solTokenTraders", "summary": "Who traded the token", "description": "The wallets that traded the token over the window, biggest USD volume first (the top 100; `limit` slices them): bought, sold, net, trades, and an average-cost PnL over the window. The window is whole UTC hours: the current hour and the `hours` (1–48) before it, starting at `since`, so it covers a little more than `hours` × 3600 seconds. Closed hours come from an hourly (token, wallet) rollup and the current hour from the raw swaps; while the rollup has not reached back to `since` the whole window is read from raw, and the first read of a busy token can then take tens of seconds or answer `503`. The answer is cached on the Solana side: retry after a minute, or ask for fewer `hours`.\n\n- `heldAmount` is bought minus sold inside the window, not the wallet's balance.\n- `partial: true` = the wallet sold more than it bought in the window; those sells have no cost basis.\n\nChord's own Solana tape, read-only. No key needed.\n\n- **What it reads.** The swap events of 11 venues: PumpSwap, the pump.fun bonding curve, Meteora DBC, Meteora DAMM v2, Meteora DLMM, Meteora pools (dynamic AMM v1), Raydium CLMM, Raydium CPMM, Raydium AMM v4, Raydium LaunchLab and Orca Whirlpool. Each swap is checked against the pool vaults' balance changes in the same transaction.\n- **What it does not read.** Prop AMMs (SolFi, HumidiFi and the like) and order books. SOL/USDC and other major pairs therefore show far less volume than the whole market; the numbers are accurate for pump.fun, Meteora and Raydium style tokens. Transfers are not seen either: wallet PnL is average cost inside the window.\n- **History.** Live since 2026-10-03 12:01 UTC, plus a backfill of the days before. `coverageSince` on `/chains/solana/overview` says from when totals are complete: quote that field, not a date.\n- **Addresses** are base58 and **case-sensitive**. Never lower-case a mint or a wallet: a lower-cased mint is a different string, refused with `400 BAD_ADDRESS` when it stops being base58 (an `L` becomes `l`) and answered `404 TOKEN_NOT_FOUND` otherwise. Solana has no numeric chain id here: the path segment is the literal `solana`.\n- **Units.** Token amounts are whole tokens (decimals already applied), `quoteAmount` is whole units of the pool's quote (SOL, USDC, USDT or the other token), prices and `*Usd` fields are US dollars. Timestamps, `updatedAt` included, are Unix **seconds**.\n- **Names are untrusted.** `symbol`, `name` and `image` are whatever the token's creator wrote; many mints share a symbol and there are no wash or impostor flags. Identify a token by its mint.\n- **Errors.** `400 BAD_*` for a bad parameter; `400 UNSUPPORTED_CHAIN` if Solana is not public on the deployment and the request has no `X-API-Key`; `503 CHAIN_DATA_UNAVAILABLE` when the Solana store cannot be read in time and `503 CHAIN_NOT_ENABLED` when the lane is off: retry later, never read either as \"no trades\".", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "description": "Token mint, base58, exactly as it appears on-chain." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }, "description": "" }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 48, "default": 24 }, "description": "Whole UTC hours before the current one (see `since`)." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "const": "solana" }, "token": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "windowHours": { "type": "integer", "description": "" }, "since": { "type": "integer", "description": "Unix time, seconds, UTC." }, "priceUsd": { "type": [ "number", "null" ], "description": "" }, "traders": { "type": "array", "items": { "type": "object", "properties": { "wallet": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "boughtUsd": { "type": "number", "description": "" }, "soldUsd": { "type": "number", "description": "" }, "netUsd": { "type": "number", "description": "Bought minus sold, USD." }, "trades": { "type": "integer", "description": "" }, "lastTrade": { "type": "integer", "description": "Unix time, seconds, UTC." }, "heldAmount": { "type": "number", "description": "Whole tokens." }, "heldValueUsd": { "type": [ "number", "null" ], "description": "" }, "realizedPnlUsd": { "type": [ "number", "null" ], "description": "" }, "unrealizedPnlUsd": { "type": [ "number", "null" ], "description": "" }, "partial": { "type": "boolean", "description": "" } } } }, "updatedAt": { "type": "integer", "description": "Unix time, SECONDS, when the Solana box built this answer. Unlike the rest of the API (milliseconds)." } } }, "example": { "chain": "solana", "token": "7VertkgF9KLhxxJXHX6uaWuoYZTP9LdGj2bWmVXVpump", "windowHours": 24, "since": 1791079200, "priceUsd": 0.01420426088276189, "traders": [ { "wallet": "ARu4n5mFdZogZAravu7CcizaojWnS6oqka37gdLT5SZn", "boughtUsd": 2176754.8047437067, "soldUsd": 1884286.4740241242, "netUsd": 292468.3307195825, "trades": 11466, "lastTrade": 1791152541, "heldAmount": 18044940.3278099, "heldValueUsd": 256315.04003008266, "realizedPnlUsd": 30691.394381958165, "unrealizedPnlUsd": -66844.68507145798, "partial": false }, { "wallet": "MriyaNN8TMp6qRWjfr723PK7xgQK7yCt7Kg2v2PQu7X", "boughtUsd": 508194.52591024636, "soldUsd": 519052.2068625818, "netUsd": -10857.680952335417, "trades": 1436, "lastTrade": 1791152211, "heldAmount": 0, "heldValueUsd": 0, "realizedPnlUsd": 10307.184467280762, "unrealizedPnlUsd": 0, "partial": true } ], "updatedAt": 1791167327 } } } }, "400": { "description": "`BAD_ADDRESS` / `BAD_LIMIT` / `BAD_HOURS`, or `UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`TOKEN_NOT_FOUND`: this mint has not traded on a venue the tape reads since the tape started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/traders": { "get": { "tags": [ "Solana data" ], "operationId": "solTraders", "summary": "The day's traders", "description": "Wallets ranked by realized PnL or by volume over today's UTC day (`days=2` adds yesterday), across every token the tape reads. Bots are left out by rule (`botRule`: above 3,000 trades or 300 tokens a day), and so are wallets under $1,000 of volume. Realized PnL per token = the matched amount × (average sell − average buy) inside the window, summed; `winRate` = the share of tokens with both buys and sells that sold above their average buy. Early in the UTC day the board is short, and empty until the day has rows. Cached 5 minutes; a cold `days=2` board can take longer than the API waits and answer `503`: retry later.\n\nChord's own Solana tape, read-only. No key needed.\n\n- **What it reads.** The swap events of 11 venues: PumpSwap, the pump.fun bonding curve, Meteora DBC, Meteora DAMM v2, Meteora DLMM, Meteora pools (dynamic AMM v1), Raydium CLMM, Raydium CPMM, Raydium AMM v4, Raydium LaunchLab and Orca Whirlpool. Each swap is checked against the pool vaults' balance changes in the same transaction.\n- **What it does not read.** Prop AMMs (SolFi, HumidiFi and the like) and order books. SOL/USDC and other major pairs therefore show far less volume than the whole market; the numbers are accurate for pump.fun, Meteora and Raydium style tokens. Transfers are not seen either: wallet PnL is average cost inside the window.\n- **History.** Live since 2026-10-03 12:01 UTC, plus a backfill of the days before. `coverageSince` on `/chains/solana/overview` says from when totals are complete: quote that field, not a date.\n- **Addresses** are base58 and **case-sensitive**. Never lower-case a mint or a wallet: a lower-cased mint is a different string, refused with `400 BAD_ADDRESS` when it stops being base58 (an `L` becomes `l`) and answered `404 TOKEN_NOT_FOUND` otherwise. Solana has no numeric chain id here: the path segment is the literal `solana`.\n- **Units.** Token amounts are whole tokens (decimals already applied), `quoteAmount` is whole units of the pool's quote (SOL, USDC, USDT or the other token), prices and `*Usd` fields are US dollars. Timestamps, `updatedAt` included, are Unix **seconds**.\n- **Names are untrusted.** `symbol`, `name` and `image` are whatever the token's creator wrote; many mints share a symbol and there are no wash or impostor flags. Identify a token by its mint.\n- **Errors.** `400 BAD_*` for a bad parameter; `400 UNSUPPORTED_CHAIN` if Solana is not public on the deployment and the request has no `X-API-Key`; `503 CHAIN_DATA_UNAVAILABLE` when the Solana store cannot be read in time and `503 CHAIN_NOT_ENABLED` when the lane is off: retry later, never read either as \"no trades\".", "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pnl", "volume" ], "default": "pnl" }, "description": "Descending." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 2, "default": 1 }, "description": "1 = today (UTC), 2 = today and yesterday." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "const": "solana" }, "sort": { "type": "string", "description": "" }, "windowDays": { "type": "integer", "description": "" }, "botRule": { "type": "string", "description": "The rule that removed bots, in words." }, "traders": { "type": "array", "items": { "type": "object", "properties": { "wallet": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "realizedPnlUsd": { "type": "number", "description": "" }, "volumeUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "tokens": { "type": "integer", "description": "Tokens traded." }, "winRate": { "type": [ "number", "null" ], "description": "0–1." } } } }, "updatedAt": { "type": "integer", "description": "Unix time, SECONDS, when the Solana box built this answer. Unlike the rest of the API (milliseconds)." } } }, "example": { "chain": "solana", "sort": "pnl", "windowDays": 1, "botRule": "wallets above 3000 trades or 300 tokens a day are left out", "traders": [], "updatedAt": 1791166631 } } } }, "400": { "description": "`BAD_LIMIT` / `BAD_DAYS` / `BAD_SORT`, or `UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/smart-traders": { "get": { "tags": [ "Solana data" ], "operationId": "solSmartTraders", "summary": "Smart traders", "description": "The wallets that made repeated, verifiable profit over the last 1, 3 or 7 UTC days (today included): bots, launch wallets and lucky one-offs removed by named rules, then ranked by a luck-corrected `score`. Rebuilt every 10 minutes on the Solana side (`computedAt`); the request never computes, so it answers in milliseconds, and `503` for a few minutes after a deploy until the first build.\n\nHow a wallet gets on the board:\n\n- **Profit you can stand behind.** Realized PnL at average cost over the whole window (a position bought on day 1 and sold on day 3 counts), from swaps in pools quoted in SOL, USDC or USDT only. A position with more than 10 % of its amount traded through pools quoted in another token is left out (`unpricedTokens`), and so is one returning over 1,000× its cost or selling more than the token's deepest pool could pay (`suspectTokens`).\n- **A person, not a machine.** Removed by name (`checked.flags`): `cadence` (over 500 swaps on a day), `sniper` (over 150 tokens on a day), `burst` (8+ transactions inside a minute, in more minutes than the wallet has active days), `sameslot` (sells within 2 s of buying, 5+ and 5 %+ of its sells), `arb` (transactions that buy and sell one token), `scalp` (median hold under 60 s: gone before anyone could follow), `launch` (most closed positions first bought within 2 s of that pool's first swap: creator and bundle wallets).\n- **One operator, one row.** Wallets that made their first buy of the same 3+ tokens within 2 s of each other are one operator: the best score stays and carries `siblings`; a follower 30 s behind is not grouped.\n- **Not luck.** At least 5 tokens bought and sold, 10 swaps, $2,000 of volume, $1,000 realized and a 30 % win rate.\n- **Score** = realized × (0.35 + 0.65 × win rate shrunk toward 50 % with 20 phantom positions) × (0.5 + 0.5 × profitable days / active days) × (0.5 when one token made over 80 % of the profit, 0.75 over 60 %) × exp(−hours since the last trade / 48). `rules` repeats every threshold in words.\n\nCandidates are the top 250 wallets by realized PnL in the window, so `sort=roi` and `sort=winrate` reorder that verified set rather than search every wallet; `roi` only ranks wallets that put at least $1,000 to work. `from` is where the window really starts: never before `coverageSince`. Unrealized PnL (`unrealizedPnlUsd`, held amount marked at most at the deepest pool's liquidity) is shown, not ranked. Past profit over a few days is not a forecast.\n\nChord's own Solana tape, read-only. No key needed.\n\n- **What it reads.** The swap events of 11 venues: PumpSwap, the pump.fun bonding curve, Meteora DBC, Meteora DAMM v2, Meteora DLMM, Meteora pools (dynamic AMM v1), Raydium CLMM, Raydium CPMM, Raydium AMM v4, Raydium LaunchLab and Orca Whirlpool. Each swap is checked against the pool vaults' balance changes in the same transaction.\n- **What it does not read.** Prop AMMs (SolFi, HumidiFi and the like) and order books. SOL/USDC and other major pairs therefore show far less volume than the whole market; the numbers are accurate for pump.fun, Meteora and Raydium style tokens. Transfers are not seen either: wallet PnL is average cost inside the window.\n- **History.** Live since 2026-10-03 12:01 UTC, plus a backfill of the days before. `coverageSince` on `/chains/solana/overview` says from when totals are complete: quote that field, not a date.\n- **Addresses** are base58 and **case-sensitive**. Never lower-case a mint or a wallet: a lower-cased mint is a different string, refused with `400 BAD_ADDRESS` when it stops being base58 (an `L` becomes `l`) and answered `404 TOKEN_NOT_FOUND` otherwise. Solana has no numeric chain id here: the path segment is the literal `solana`.\n- **Units.** Token amounts are whole tokens (decimals already applied), `quoteAmount` is whole units of the pool's quote (SOL, USDC, USDT or the other token), prices and `*Usd` fields are US dollars. Timestamps, `updatedAt` included, are Unix **seconds**.\n- **Names are untrusted.** `symbol`, `name` and `image` are whatever the token's creator wrote; many mints share a symbol and there are no wash or impostor flags. Identify a token by its mint.\n- **Errors.** `400 BAD_*` for a bad parameter; `400 UNSUPPORTED_CHAIN` if Solana is not public on the deployment and the request has no `X-API-Key`; `503 CHAIN_DATA_UNAVAILABLE` when the Solana store cannot be read in time and `503 CHAIN_NOT_ENABLED` when the lane is off: retry later, never read either as \"no trades\".", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 3, 7 ], "default": 7 }, "description": "Window in UTC days, today included." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "score", "pnl", "roi", "winrate" ], "default": "score" }, "description": "Descending." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "const": "solana" }, "windowDays": { "type": "integer", "description": "1, 3 or 7." }, "sort": { "type": "string", "description": "" }, "from": { "type": "integer", "description": "Unix time, seconds, UTC." }, "coverageSince": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "computedAt": { "type": "integer", "description": "Unix time, seconds, UTC." }, "tookMs": { "type": "integer", "description": "How long the last build of this window took on the Solana side." }, "population": { "type": "object", "properties": { "profitable": { "type": "integer", "description": "Wallets over the floors with realized PnL in the window." }, "cadence": { "type": "integer", "description": "Of those, removed for over 500 swaps on a day." }, "sniper": { "type": "integer", "description": "Removed for over 150 tokens on a day." } } }, "checked": { "type": "object", "properties": { "candidates": { "type": "integer", "description": "Wallets read swap by swap." }, "kept": { "type": "integer", "description": "On the board." }, "flags": { "type": "object", "properties": {}, "description": "Candidates removed per rule: cadence, sniper, burst, sameslot, arb, scalp, launch. A wallet can carry several; `launch` is only looked up for wallets no other rule removed.", "additionalProperties": { "type": "integer", "description": "" } }, "suspect": { "type": "integer", "description": "Removed because most of the profit came from left-out positions." }, "ineligible": { "type": "integer", "description": "Under a floor once read exactly." }, "readErrors": { "type": "integer", "description": "Candidates whose swaps could not be read this cycle (back next cycle)." }, "clustered": { "type": "integer", "description": "Wallets dropped as a second wallet of an operator already on the board (see `siblings`)." } } }, "rules": { "type": "object", "properties": {}, "description": "Every threshold, in words.", "additionalProperties": { "type": "string", "description": "" } }, "traders": { "type": "array", "items": { "type": "object", "properties": { "wallet": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "score": { "type": "number", "description": "Luck-corrected, recency-weighted realized profit; the default order." }, "realizedPnlUsd": { "type": "number", "description": "" }, "roi": { "type": [ "number", "null" ], "description": "Realized ÷ cost of the sold amount; 0.5 = +50 %." }, "winRate": { "type": [ "number", "null" ], "description": "Share of closed tokens sold above their average buy, 0–1." }, "winRateAdj": { "type": "number", "description": "Win rate shrunk toward 0.5." }, "closedTokens": { "type": "integer", "description": "Tokens bought and sold in the window." }, "winningTokens": { "type": "integer", "description": "" }, "tokens": { "type": "integer", "description": "" }, "trades": { "type": "integer", "description": "" }, "volumeUsd": { "type": "number", "description": "" }, "activeDays": { "type": "integer", "description": "" }, "profitableDays": { "type": "integer", "description": "Days whose closed positions (by last sell) netted a profit." }, "medianHoldS": { "type": [ "number", "null" ], "description": "Median seconds between average buy and average sell, closed tokens." }, "unrealizedPnlUsd": { "type": "number", "description": "Held amount at the current price (capped at the deepest pool's liquidity) minus its average cost. Not ranked." }, "heldValueUsd": { "type": "number", "description": "" }, "costSoldUsd": { "type": "number", "description": "Cost of the sold amount at the average buy." }, "bestToken": { "type": [ "object", "null" ], "properties": { "token": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "symbol": { "type": [ "string", "null" ], "description": "Creator-chosen." }, "name": { "type": [ "string", "null" ], "description": "Creator-chosen." }, "image": { "type": [ "string", "null" ], "description": "" }, "realizedPnlUsd": { "type": "number", "description": "" } } }, "bestShare": { "type": [ "number", "null" ], "description": "The best token's share of realized PnL." }, "unpricedTokens": { "type": "integer", "description": "" }, "suspectTokens": { "type": "integer", "description": "" }, "launchTokens": { "type": "integer", "description": "Closed tokens first bought within 2 s of the pool's first swap." }, "siblings": { "type": "integer", "description": "Other wallets of the same operator left off the board: they made their first buy of the same 3+ tokens within 2 s of this one." }, "lastTrade": { "type": "integer", "description": "Unix time, seconds, UTC." } } } } } }, "example": { "chain": "solana", "windowDays": 7, "from": 1790726400, "coverageSince": 1790419777, "computedAt": 1791304962, "tookMs": 11141, "population": { "profitable": 16007, "cadence": 3755, "sniper": 86 }, "checked": { "candidates": 250, "kept": 25, "flags": { "cadence": 0, "sniper": 0, "burst": 92, "sameslot": 125, "arb": 8, "scalp": 101, "launch": 27 }, "suspect": 0, "ineligible": 69, "readErrors": 0, "clustered": 0 }, "rules": { "pricing": "PnL counts only swaps in pools quoted in SOL, USDC or USDT (direct USD); a position with more than 10 % of its amount traded through pools quoted in another token is left out (unpriced)", "averageCost": "realized = sold amount (up to what was bought in the window) × (average sell − average buy); tokens bought before the window are not priced", "suspect": "a position returning more than 1000× its cost, or one sell above $1,000,000 into a token whose deepest pool now holds less than 1/20 of it, is left out; a wallet whose profit came mostly from such positions is left out", "cadence": "more than 500 swaps on any day", "sniper": "more than 150 tokens on any day", "burst": "8+ transactions inside one minute, in 3+ different minutes", "sameslot": "5+ sells within 2 s of buying the same token (sandwich / bundle / launch sniper)", "arb": "10+ transactions (and 20 %+ of all) that buy and sell the same token", "cluster": "wallets that made their first buy of the same 3+ tokens within 2 s of each other are one operator: only the best score stays (siblings on its row, checked.clustered)", "scalp": "median hold under 60 s over 5+ closed positions (sold before anyone could follow)", "launch": "3+ closed positions, and at least half of them, first bought within 2 s of that pool's first swap (creator / bundle wallet)", "eligibility": "volume ≥ $2000, ≥ 5 tokens bought and sold, ≥ 10 swaps, realized ≥ $1000, win rate ≥ 30 %", "score": "realized × (0.35 + 0.65 × win rate shrunk toward 50 % with 20 phantom positions) × (0.5 + 0.5 × profitable days / active days) × (0.5 when one token made > 80 % of the profit, 0.75 when > 60 %) × exp(−hours since last trade / 48)" }, "traders": [ { "wallet": "9LXWa7V3AE15VfBupcx5gDts2ix3Y9NzbcKZKjkkq6hV", "score": 37132.17771163606, "realizedPnlUsd": 43978.0170266694, "roi": 0.4170270878884252, "winRate": 0.7761627906976745, "winRateAdj": 0.760989010989011, "closedTokens": 344, "winningTokens": 267, "tokens": 459, "trades": 1356, "volumeUsd": 314916.44803633285, "activeDays": 7, "profitableDays": 7, "medianHoldS": 177.9890558719635, "unrealizedPnlUsd": -61.60543642516731, "heldValueUsd": 2038.5111692911005, "costSoldUsd": 105456.02025361871, "bestToken": { "token": "Am6SB1xhuwyv6hENfR2uHj2fvKeo87KN8vVw28RcrmEa", "symbol": "Cassie", "name": "Cassie The Chimpanzee", "image": "https://metadata.j7tracker.io/images/1c2700b89272443f", "realizedPnlUsd": 7868.563813198551 }, "bestShare": 0.17892038671108912, "unpricedTokens": 62, "suspectTokens": 0, "launchTokens": 20, "siblings": 0, "lastTrade": 1791304899 }, { "wallet": "cATq48AALCiD2hECKZDgKHp3VoSHbXc4aDxSzgQLbc3", "score": 32503.036821818743, "realizedPnlUsd": 63356.15881453157, "roi": 0.5491717745407618, "winRate": 0.6666666666666666, "winRateAdj": 0.5853658536585366, "closedTokens": 21, "winningTokens": 14, "tokens": 25, "trades": 100, "volumeUsd": 308927.798739281, "activeDays": 7, "profitableDays": 4, "medianHoldS": 1102.3087236881256, "unrealizedPnlUsd": 0, "heldValueUsd": 0, "costSoldUsd": 115366.74270543561, "bestToken": { "token": "9m4Swt3D8aTzzeDEaA5xmCA8Sjd5uvWrhvMKTocjpump", "symbol": "GTA6 Coin", "name": "GTA6 Coin", "image": "https://gateway.pinata.cloud/ipfs/bafkreibbdrekbfek6cbxrzi4meqbxzjnxzaycvlfnghnde3kr2rrz3vxne", "realizedPnlUsd": 19491.505347944916 }, "bestShare": 0.3076497330749522, "unpricedTokens": 0, "suspectTokens": 0, "launchTokens": 7, "siblings": 0, "lastTrade": 1791285568 } ], "sort": "score" } } } }, "400": { "description": "`BAD_DAYS` / `BAD_SORT` / `BAD_LIMIT`, or `UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/wallet/{address}": { "get": { "tags": [ "Solana data" ], "operationId": "solWallet", "summary": "One wallet's tokens and PnL", "description": "What a wallet bought and sold per token over the last `days` UTC days (today included), with an average-cost PnL: realized on the sold part, unrealized on what is still held at the current price. Up to 200 tokens, biggest first. Say how far back the numbers go when you show them.\n\n- Transfers are not seen: a token that arrived by transfer and was then sold counts as a sell without a buy. Such rows carry `partial: true` (counted in `partialTokens`) and their sells have no realized PnL.\n- `heldAmount` and `heldValueUsd` are bought minus sold inside the window, not the on-chain balance.\n- `likelyBot` = more than 3,000 trades or 300 tokens a day.\n\nChord's own Solana tape, read-only. No key needed.\n\n- **What it reads.** The swap events of 11 venues: PumpSwap, the pump.fun bonding curve, Meteora DBC, Meteora DAMM v2, Meteora DLMM, Meteora pools (dynamic AMM v1), Raydium CLMM, Raydium CPMM, Raydium AMM v4, Raydium LaunchLab and Orca Whirlpool. Each swap is checked against the pool vaults' balance changes in the same transaction.\n- **What it does not read.** Prop AMMs (SolFi, HumidiFi and the like) and order books. SOL/USDC and other major pairs therefore show far less volume than the whole market; the numbers are accurate for pump.fun, Meteora and Raydium style tokens. Transfers are not seen either: wallet PnL is average cost inside the window.\n- **History.** Live since 2026-10-03 12:01 UTC, plus a backfill of the days before. `coverageSince` on `/chains/solana/overview` says from when totals are complete: quote that field, not a date.\n- **Addresses** are base58 and **case-sensitive**. Never lower-case a mint or a wallet: a lower-cased mint is a different string, refused with `400 BAD_ADDRESS` when it stops being base58 (an `L` becomes `l`) and answered `404 TOKEN_NOT_FOUND` otherwise. Solana has no numeric chain id here: the path segment is the literal `solana`.\n- **Units.** Token amounts are whole tokens (decimals already applied), `quoteAmount` is whole units of the pool's quote (SOL, USDC, USDT or the other token), prices and `*Usd` fields are US dollars. Timestamps, `updatedAt` included, are Unix **seconds**.\n- **Names are untrusted.** `symbol`, `name` and `image` are whatever the token's creator wrote; many mints share a symbol and there are no wash or impostor flags. Identify a token by its mint.\n- **Errors.** `400 BAD_*` for a bad parameter; `400 UNSUPPORTED_CHAIN` if Solana is not public on the deployment and the request has no `X-API-Key`; `503 CHAIN_DATA_UNAVAILABLE` when the Solana store cannot be read in time and `503 CHAIN_NOT_ENABLED` when the lane is off: retry later, never read either as \"no trades\".", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "description": "Wallet address, base58, exactly as it appears on-chain." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 45, "default": 7 }, "description": "Window in UTC days, today included." } ], "responses": { "200": { "description": "A wallet the tape has never seen answers zeros and an empty `positions`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "const": "solana" }, "wallet": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "windowDays": { "type": "integer", "description": "" }, "tokens": { "type": "integer", "description": "" }, "trades": { "type": "integer", "description": "" }, "volumeUsd": { "type": "number", "description": "" }, "boughtUsd": { "type": "number", "description": "" }, "soldUsd": { "type": "number", "description": "" }, "realizedPnlUsd": { "type": "number", "description": "" }, "unrealizedPnlUsd": { "type": "number", "description": "" }, "heldValueUsd": { "type": "number", "description": "" }, "winRate": { "type": [ "number", "null" ], "description": "Share of tokens with sells that closed in profit, 0–1." }, "partialTokens": { "type": "integer", "description": "Tokens with `partial: true`." }, "likelyBot": { "type": "boolean", "description": "" }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/SolPosition" }, "description": "Biggest bought + sold first." }, "updatedAt": { "type": "integer", "description": "Unix time, SECONDS, when the Solana box built this answer. Unlike the rest of the API (milliseconds)." } } }, "example": { "chain": "solana", "wallet": "3QZv9xcDELwLqB8SggDJHfVhMTn5YhKtXMCaKUucutm3", "windowDays": 7, "tokens": 3, "trades": 10, "volumeUsd": 249.92409078731498, "boughtUsd": 157.82642149850838, "soldUsd": 92.09766928880659, "realizedPnlUsd": 10.89172430885074, "unrealizedPnlUsd": -13.521686548756673, "heldValueUsd": 92.65951096979586, "winRate": 1, "partialTokens": 1, "likelyBot": false, "positions": [ { "token": "7VertkgF9KLhxxJXHX6uaWuoYZTP9LdGj2bWmVXVpump", "symbol": "Agency", "name": "Agency", "image": "https://ipfs.io/ipfs/bafybeicailrr3iobedoxprzs6evwq3nqxsezdhvxbhpseyhltfmufybxuq", "priceUsd": 0.012298957291368744, "boughtUsd": 139.35060978011185, "soldUsd": 62.536948288806585, "boughtAmount": 9685.829453, "soldAmount": 3589.699624, "buys": 5, "sells": 2, "heldAmount": 6096.129829, "heldValueUsd": 74.97604040951005, "realizedPnlUsd": 10.89172430885074, "unrealizedPnlUsd": -12.72934539064596, "partial": false, "lastDay": 1791072000 }, { "token": "So11111111111111111111111111111111111111112", "symbol": "SOL", "name": "Solana", "image": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/So11111111111111111111111111111111111111112/logo.png", "priceUsd": 120.9862, "boughtUsd": 0, "soldUsd": 29.560721, "boughtAmount": 0, "soldAmount": 0.247089203, "buys": 0, "sells": 1, "heldAmount": 0, "heldValueUsd": 0, "realizedPnlUsd": null, "unrealizedPnlUsd": 0, "partial": true, "lastDay": 1790985600 } ], "updatedAt": 1791166532 } } } }, "400": { "description": "`BAD_ADDRESS` / `BAD_DAYS`, or `UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/wallet/{address}/trades": { "get": { "tags": [ "Solana data" ], "operationId": "solWalletTrades", "summary": "A wallet's swaps", "description": "The wallet's newest swaps on the venues the tape reads, newest first, with the token and its symbol. Each page looks back at most seven days from `before` (or from now).\n\nChord's own Solana tape, read-only. No key needed.\n\n- **What it reads.** The swap events of 11 venues: PumpSwap, the pump.fun bonding curve, Meteora DBC, Meteora DAMM v2, Meteora DLMM, Meteora pools (dynamic AMM v1), Raydium CLMM, Raydium CPMM, Raydium AMM v4, Raydium LaunchLab and Orca Whirlpool. Each swap is checked against the pool vaults' balance changes in the same transaction.\n- **What it does not read.** Prop AMMs (SolFi, HumidiFi and the like) and order books. SOL/USDC and other major pairs therefore show far less volume than the whole market; the numbers are accurate for pump.fun, Meteora and Raydium style tokens. Transfers are not seen either: wallet PnL is average cost inside the window.\n- **History.** Live since 2026-10-03 12:01 UTC, plus a backfill of the days before. `coverageSince` on `/chains/solana/overview` says from when totals are complete: quote that field, not a date.\n- **Addresses** are base58 and **case-sensitive**. Never lower-case a mint or a wallet: a lower-cased mint is a different string, refused with `400 BAD_ADDRESS` when it stops being base58 (an `L` becomes `l`) and answered `404 TOKEN_NOT_FOUND` otherwise. Solana has no numeric chain id here: the path segment is the literal `solana`.\n- **Units.** Token amounts are whole tokens (decimals already applied), `quoteAmount` is whole units of the pool's quote (SOL, USDC, USDT or the other token), prices and `*Usd` fields are US dollars. Timestamps, `updatedAt` included, are Unix **seconds**.\n- **Names are untrusted.** `symbol`, `name` and `image` are whatever the token's creator wrote; many mints share a symbol and there are no wash or impostor flags. Identify a token by its mint.\n- **Errors.** `400 BAD_*` for a bad parameter; `400 UNSUPPORTED_CHAIN` if Solana is not public on the deployment and the request has no `X-API-Key`; `503 CHAIN_DATA_UNAVAILABLE` when the Solana store cannot be read in time and `503 CHAIN_NOT_ENABLED` when the lane is off: retry later, never read either as \"no trades\".", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "description": "Wallet address, base58, exactly as it appears on-chain." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Newest rows." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 4000000000 }, "description": "Exclusive cursor, Unix seconds: rows strictly older than it. Pass the last row's `ts` for the next page. Several swaps can share a second, so a page boundary can skip the rest of that second: overlap with `ts + 1` and drop rows whose `tx` you already have." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "const": "solana" }, "wallet": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "trades": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "integer", "description": "Unix time, seconds, UTC." }, "slot": { "type": "integer", "description": "" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "token": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "symbol": { "type": [ "string", "null" ], "description": "" }, "name": { "type": [ "string", "null" ], "description": "" }, "tokenAmount": { "type": "number", "description": "Whole tokens." }, "quoteAmount": { "type": "number", "description": "Whole units of the pool's quote." }, "usd": { "type": [ "number", "null" ], "description": "" }, "priceUsd": { "type": [ "number", "null" ], "description": "" }, "dex": { "type": "string", "description": "Venue id: `pumpswap` · `pumpfun` (bonding curve) · `meteora_dbc` · `meteora_damm_v2` · `meteora_dlmm` · `meteora_pools` (dynamic AMM v1) · `raydium_clmm` · `raydium_cpmm` · `raydium_v4` · `raydium_launchlab` · `orca` (Whirlpool)." }, "pool": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "tx": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{64,88}$", "description": "Transaction signature, base58." } } } }, "updatedAt": { "type": "integer", "description": "Unix time, SECONDS, when the Solana box built this answer. Unlike the rest of the API (milliseconds)." } } }, "example": { "chain": "solana", "wallet": "3QZv9xcDELwLqB8SggDJHfVhMTn5YhKtXMCaKUucutm3", "trades": [ { "ts": 1791151147, "slot": 453384173, "side": "buy", "token": "7VertkgF9KLhxxJXHX6uaWuoYZTP9LdGj2bWmVXVpump", "symbol": "Agency", "name": "Agency", "tokenAmount": 2879.134063, "quoteAmount": 0.295798607, "usd": 35.812234413351845, "priceUsd": 0.012401339509037218, "dex": "pumpswap", "pool": "CyJwKnLiiY4fmiwqMCSWFSHxo7T9Ubshgs2uRAuJCrk5", "tx": "Vz2VPQCo2j82g6mowse5961MnUEM6koE7VSaVhtVHQKsvkCHZ9HGVMTgbw92vDSJw1ThSDiVGkwn16EucjAK6Ny" }, { "ts": 1791141717, "slot": 453349000, "side": "buy", "token": "DoVAVzViX8Bjy3r15nwikSaSbzE6dV4ovd28aWpJpump", "symbol": "HIGGS", "name": "Higgspad", "tokenAmount": 2231.366315, "quoteAmount": 0.040323739, "usd": 4.90003471839652, "priceUsd": 0.0021763918544292736, "dex": "pumpswap", "pool": "BFrSZakeqNzVtM3EFhroo4eRhagmmWN8BRntiQKFH6Ru", "tx": "5yzFpQRh11MNX9dVWZsNGkHN4nD1XW7KQqWXD931tsYnc2rYggjaNkzZ4bCvddXoEama9pz1hqo2DH1f8i9UBVTr" } ], "updatedAt": 1791166571 } } } }, "400": { "description": "`BAD_ADDRESS` / `BAD_LIMIT` / `BAD_CURSOR`, or `UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/lp/pools": { "get": { "tags": [ "Solana data" ], "operationId": "solLpPools", "summary": "Liquidity pools by LP activity", "description": "Every pool where liquidity moved in the window, ranked: `fees` (claimed fees, default), `deposits`, `withdrawals`, `net` (net inflow), `lps` (distinct LPs), `tvl` or `fee_tvl` (fees claimed in the window per dollar of liquidity now). Each row has the pool's TVL estimate and swap volume from the swap tape (TVL is null until the pool has had a verified swap), deposits, withdrawals, claimed fees, counts and open positions. Cached 60 seconds.\n\n`feeTvlPct` is fees **claimed**, not fees accrued: the tape cannot see fees that sit unclaimed in a position, so it is not an APR. `sort=fee_tvl` starts from a $10,000 TVL floor (one claim on a thin pool would top the list); pass `minTvl=0` for no floor. `q` takes a ticker (any case, part of it is enough) or one pool or mint address (exact, case-sensitive).\n\nLiquidity on Solana from Chord's own tape: adds, removes, fee claims, position opens and closes, decoded from the same blocks as the swaps. No key needed.\n\n- **Venues.** Meteora DLMM, Meteora DAMM v2, Raydium CLMM and PumpSwap. Orca Whirlpools, Raydium CPMM / v4 and Meteora dynamic pools are not read yet.\n- **Since.** `since` is when LP decoding started (2026-10-06 15:53 UTC); windows never start before it. A position opened earlier is `partial: true` and carries no PnL.\n- **Fees are claimed fees.** An LP's fees appear when it claims them, so a window's fees understate what the pool earned, and one claim can hold days of fees.\n- **Positions.** One row per position account (DLMM / DAMM v2 position, Raydium CLMM position NFT, PumpSwap LP token account), rebuilt from all its events. `lower` / `upper` are DLMM bin ids or Raydium CLMM ticks; null = full range. Realized PnL = withdrawn + fees claimed − deposited, only for a position seen from its open to its close with every amount priced. An open position's current value is not in the events: none is given.\n- **Amounts** are whole tokens in the pool's own order (`mintA` / `mintB`); USD is valued when the event happened. Each add / remove / claim is checked against the pool vaults' balance changes in the same transaction (`verified`).\n- **Addresses** are base58 and case-sensitive, as on the other Solana routes.", "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "fees", "deposits", "withdrawals", "net", "lps", "tvl", "fee_tvl" ], "default": "fees" }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "" }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 168, "default": 24 }, "description": "Window in hours, never before `since`." }, { "name": "minTvl", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "description": "Leave out pools under this TVL in US dollars, and pools whose TVL is unknown. Default 0, or 10000 with `sort=fee_tvl`." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 64 }, "description": "A ticker, or one pool or mint address." }, { "name": "dex", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "meteora_dlmm", "meteora_damm_v2", "raydium_clmm", "pumpswap" ] }, "description": "One venue." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "const": "solana" }, "sort": { "type": "string", "description": "" }, "windowHours": { "type": "integer", "description": "" }, "since": { "type": "integer", "description": "Unix time, seconds, UTC." }, "pools": { "type": "integer", "description": "Pools with activity in the window." }, "total": { "type": "integer", "description": "Pools left after `minTvl`, `q` and `dex`." }, "minTvl": { "type": "number", "description": "The floor applied." }, "rows": { "type": "array", "items": { "type": "object", "properties": { "pool": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "dex": { "type": "string", "description": "`meteora_dlmm` · `meteora_damm_v2` · `raydium_clmm` · `pumpswap`." }, "mintA": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "symbolA": { "type": [ "string", "null" ], "description": "Creator-chosen." }, "mintB": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "symbolB": { "type": [ "string", "null" ], "description": "Creator-chosen." }, "tvlUsd": { "type": [ "number", "null" ], "description": "" }, "priceUsd": { "type": [ "number", "null" ], "description": "" }, "token": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "swapVolumeUsd": { "type": [ "number", "null" ], "description": "" }, "depositsUsd": { "type": "number", "description": "" }, "withdrawalsUsd": { "type": "number", "description": "" }, "netFlowUsd": { "type": "number", "description": "" }, "feesClaimedUsd": { "type": "number", "description": "" }, "adds": { "type": "integer", "description": "" }, "removes": { "type": "integer", "description": "" }, "claims": { "type": "integer", "description": "" }, "opens": { "type": "integer", "description": "" }, "closes": { "type": "integer", "description": "" }, "lps": { "type": "integer", "description": "" }, "openPositions": { "type": [ "integer", "null" ], "description": "" }, "feeTvlPct": { "type": [ "number", "null" ], "description": "Fees claimed in the window as a percent of `tvlUsd`. null when the TVL is unknown." }, "firstLpEvent": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "imageA": { "type": [ "string", "null" ], "description": "Token image as its creator set it. Untrusted." }, "imageB": { "type": [ "string", "null" ], "description": "" } } } }, "updatedAt": { "type": "integer", "description": "Unix time, SECONDS, when the Solana box built this answer. Unlike the rest of the API (milliseconds)." } } }, "example": { "chain": "solana", "sort": "fees", "windowHours": 24, "since": 1791301995, "pools": 862, "rows": [ { "pool": "7fDzFPYhdtNm5NbqvZYRcjB879DxH4dRjmMhbHSYqM5J", "dex": "meteora_damm_v2", "mintA": "TfLEzpE2rvwng5WPDP7XqsMoNLfgk2mKXNxJUvQs8c1", "symbolA": "LOCAL", "mintB": "So11111111111111111111111111111111111111112", "symbolB": "SOL", "tvlUsd": 27625.24059411423, "priceUsd": 0.00007144600292746474, "token": "TfLEzpE2rvwng5WPDP7XqsMoNLfgk2mKXNxJUvQs8c1", "swapVolumeUsd": 4454.320941113588, "depositsUsd": 0, "withdrawalsUsd": 0, "netFlowUsd": 0, "feesClaimedUsd": 4161.145469719044, "adds": 0, "removes": 0, "claims": 2, "opens": 0, "closes": 0, "lps": 1, "openPositions": 1 }, { "pool": "HbjYfcWZBjCBYTJpZkLGxqArVmZVu3mQcRudb6Wg1sVh", "dex": "meteora_dlmm", "mintA": "pumpCmXqMfrsAkQ5r49WcJnRayYRqmXz6ae8H7H9Dfn", "symbolA": "PUMP", "mintB": "So11111111111111111111111111111111111111112", "symbolB": "SOL", "tvlUsd": null, "priceUsd": 0.006306820783643733, "token": "pumpCmXqMfrsAkQ5r49WcJnRayYRqmXz6ae8H7H9Dfn", "swapVolumeUsd": 19055.704227499944, "depositsUsd": 7769.8327865424735, "withdrawalsUsd": 41.92886719122702, "netFlowUsd": 7727.903919351246, "feesClaimedUsd": 3075.699010802388, "adds": 11, "removes": 1, "claims": 10, "opens": 0, "closes": 0, "lps": 7, "openPositions": 7 } ], "updatedAt": 1791303661 } } } }, "400": { "description": "`BAD_LIMIT` / `BAD_HOURS` / `BAD_SORT` / `BAD_MIN_TVL` / `BAD_QUERY` / `BAD_DEX`, or `UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/lp/top": { "get": { "tags": [ "Solana data" ], "operationId": "solLpTop", "summary": "LP wallets", "description": "Wallets ranked over the LP positions active in the window: `fees` (claimed, default), `deposits` or `pnl` (realized). Many leaders are vaults and rebalancing bots; a short window is not a track record. Cached 60 seconds.\n\nThe board is **fee-checked**: a wallet whose realized profit is positive while the fees it claimed are under a tenth of that profit earned on the token's price (in practice one-sided liquidity on a token it launched) and is left out; `hidden` counts them. A launchpad account (500 or more positions with a pool of its own for at least every second one: the liquidity of what a launchpad launched) is left out with them; `operators` counts those. `all=1` keeps both in.\n\nLiquidity on Solana from Chord's own tape: adds, removes, fee claims, position opens and closes, decoded from the same blocks as the swaps. No key needed.\n\n- **Venues.** Meteora DLMM, Meteora DAMM v2, Raydium CLMM and PumpSwap. Orca Whirlpools, Raydium CPMM / v4 and Meteora dynamic pools are not read yet.\n- **Since.** `since` is when LP decoding started (2026-10-06 15:53 UTC); windows never start before it. A position opened earlier is `partial: true` and carries no PnL.\n- **Fees are claimed fees.** An LP's fees appear when it claims them, so a window's fees understate what the pool earned, and one claim can hold days of fees.\n- **Positions.** One row per position account (DLMM / DAMM v2 position, Raydium CLMM position NFT, PumpSwap LP token account), rebuilt from all its events. `lower` / `upper` are DLMM bin ids or Raydium CLMM ticks; null = full range. Realized PnL = withdrawn + fees claimed − deposited, only for a position seen from its open to its close with every amount priced. An open position's current value is not in the events: none is given.\n- **Amounts** are whole tokens in the pool's own order (`mintA` / `mintB`); USD is valued when the event happened. Each add / remove / claim is checked against the pool vaults' balance changes in the same transaction (`verified`).\n- **Addresses** are base58 and case-sensitive, as on the other Solana routes.", "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "fees", "deposits", "pnl", "win_rate", "ev", "positions", "avg_age", "last_activity" ], "default": "fees" }, "description": "" }, { "name": "unit", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "usd", "native" ], "default": "usd" }, "description": "`native` = the money fields of the answer in SOL: every deposit, withdrawal and claimed fee converted at the SOL price of its own minute, so a wallet that put SOL in and took the same SOL out reads flat whatever SOL did in dollars (win rate and expected value follow the unit). The fields keep their `…Usd` names; `unit` and `unitSymbol` in the answer say what they carry. `503 UNIT_NOT_READY` while positions are being folded again; another value is `400 BAD_UNIT`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "" }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 168, "default": 24 }, "description": "Window in hours, never before `since`." }, { "name": "all", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "0", "1" ] }, "description": "1 = keep the wallets the fee check and the launchpad rule leave out." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "const": "solana" }, "sort": { "type": "string", "description": "" }, "windowHours": { "type": "integer", "description": "" }, "since": { "type": "integer", "description": "Unix time, seconds, UTC." }, "feeChecked": { "type": "boolean", "description": "The fee check was applied." }, "hidden": { "type": "integer", "description": "Wallets of the window the fee check left out." }, "operators": { "type": "integer", "description": "Launchpad accounts of the window left out." }, "rows": { "type": "array", "items": { "type": "object", "properties": { "wallet": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "positions": { "type": "integer", "description": "" }, "open": { "type": "integer", "description": "" }, "pools": { "type": "integer", "description": "" }, "depositedUsd": { "type": "number", "description": "" }, "withdrawnUsd": { "type": "number", "description": "" }, "feesClaimedUsd": { "type": "number", "description": "" }, "realizedPnlUsd": { "type": [ "number", "null" ], "description": "" }, "realizedPositions": { "type": "integer", "description": "" }, "winRate": { "type": [ "number", "null" ], "description": "0–1." }, "evUsd": { "type": [ "number", "null" ], "description": "Mean result of a realized position; null with none." }, "avgAgeHours": { "type": [ "number", "null" ], "description": "Hours a position stays open, open ones counted to now." }, "avgDepositUsd": { "type": [ "number", "null" ], "description": "" }, "firstTs": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "lastTs": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." } } } }, "updatedAt": { "type": "integer", "description": "Unix time, SECONDS, when the Solana box built this answer. Unlike the rest of the API (milliseconds)." } } }, "example": { "chain": "solana", "sort": "fees", "windowHours": 24, "since": 1791750117, "feeChecked": true, "hidden": 235, "operators": 2, "rows": [ { "wallet": "6sWm5C5E25mZD98z7RAZZCqetT3rjWuLXRZsmimg6KEK", "positions": 1, "open": 1, "pools": 1, "depositedUsd": 0, "withdrawnUsd": 0, "feesClaimedUsd": 225969.36547100003, "realizedPnlUsd": null, "realizedPositions": 0, "winRate": null, "evUsd": null, "avgAgeHours": 74.6913888888889, "avgDepositUsd": null, "firstTs": 1791567628, "lastTs": 1791818882 }, { "wallet": "9SgR9w7ii7ZofZ5kgyb7hUwRVAkqRApdTZWcx4gsssCb", "positions": 2, "open": 2, "pools": 1, "depositedUsd": 0, "withdrawnUsd": 0, "feesClaimedUsd": 94307.16837727133, "realizedPnlUsd": null, "realizedPositions": 0, "winRate": null, "evUsd": null, "avgAgeHours": null, "avgDepositUsd": null, "firstTs": 1791429320, "lastTs": 1791791319 } ], "updatedAt": 1791836517 } } } }, "400": { "description": "`BAD_LIMIT` / `BAD_HOURS` / `BAD_SORT` / `BAD_ALL`, or `UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/lp/pool/{address}": { "get": { "tags": [ "Solana data" ], "operationId": "solLpPool", "summary": "One pool's liquidity", "description": "Deposits, withdrawals, net flow and claimed fees over the window, and by hour; open positions and their owners; the pair with decimals, TVL estimate and swap volume. Cached 20 seconds.\n\nLiquidity on Solana from Chord's own tape: adds, removes, fee claims, position opens and closes, decoded from the same blocks as the swaps. No key needed.\n\n- **Venues.** Meteora DLMM, Meteora DAMM v2, Raydium CLMM and PumpSwap. Orca Whirlpools, Raydium CPMM / v4 and Meteora dynamic pools are not read yet.\n- **Since.** `since` is when LP decoding started (2026-10-06 15:53 UTC); windows never start before it. A position opened earlier is `partial: true` and carries no PnL.\n- **Fees are claimed fees.** An LP's fees appear when it claims them, so a window's fees understate what the pool earned, and one claim can hold days of fees.\n- **Positions.** One row per position account (DLMM / DAMM v2 position, Raydium CLMM position NFT, PumpSwap LP token account), rebuilt from all its events. `lower` / `upper` are DLMM bin ids or Raydium CLMM ticks; null = full range. Realized PnL = withdrawn + fees claimed − deposited, only for a position seen from its open to its close with every amount priced. An open position's current value is not in the events: none is given.\n- **Amounts** are whole tokens in the pool's own order (`mintA` / `mintB`); USD is valued when the event happened. Each add / remove / claim is checked against the pool vaults' balance changes in the same transaction (`verified`).\n- **Addresses** are base58 and case-sensitive, as on the other Solana routes.", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "description": "Pool address, base58." }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 168, "default": 24 }, "description": "Window in hours, never before `since`." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "const": "solana" }, "pool": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "dex": { "type": "string", "description": "`meteora_dlmm` · `meteora_damm_v2` · `raydium_clmm` · `pumpswap`." }, "windowHours": { "type": "integer", "description": "" }, "since": { "type": "integer", "description": "Unix time, seconds, UTC." }, "mintA": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "symbolA": { "type": [ "string", "null" ], "description": "Creator-chosen." }, "mintB": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "symbolB": { "type": [ "string", "null" ], "description": "Creator-chosen." }, "decimalsA": { "type": "integer", "description": "" }, "decimalsB": { "type": "integer", "description": "" }, "tvlUsd": { "type": [ "number", "null" ], "description": "" }, "priceUsd": { "type": [ "number", "null" ], "description": "" }, "token": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "firstLpEvent": { "type": "integer", "description": "Unix time, seconds, UTC." }, "swapVolumeUsd": { "type": [ "number", "null" ], "description": "" }, "depositsUsd": { "type": "number", "description": "" }, "withdrawalsUsd": { "type": "number", "description": "" }, "netFlowUsd": { "type": "number", "description": "" }, "feesClaimedUsd": { "type": "number", "description": "" }, "openPositions": { "type": "integer", "description": "" }, "openOwners": { "type": "integer", "description": "" }, "hourly": { "type": "array", "items": { "type": "object", "properties": { "hour": { "type": "integer", "description": "Unix time, seconds, UTC." }, "depositsUsd": { "type": "number", "description": "" }, "withdrawalsUsd": { "type": "number", "description": "" }, "feesClaimedUsd": { "type": "number", "description": "" }, "adds": { "type": "integer", "description": "" }, "removes": { "type": "integer", "description": "" }, "claims": { "type": "integer", "description": "" }, "opens": { "type": "integer", "description": "" }, "closes": { "type": "integer", "description": "" }, "lps": { "type": "integer", "description": "" } } } }, "updatedAt": { "type": "integer", "description": "Unix time, SECONDS, when the Solana box built this answer. Unlike the rest of the API (milliseconds)." } } }, "example": { "chain": "solana", "pool": "HTvjzsfX3yU6BUodCjZ5vZkUrAxMDTrBs3CJaq43ashR", "dex": "meteora_dlmm", "windowHours": 24, "since": 1791301995, "mintA": "So11111111111111111111111111111111111111112", "symbolA": "SOL", "decimalsA": 9, "mintB": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "symbolB": "USDC", "decimalsB": 6, "tvlUsd": null, "priceUsd": 120.90833585378545, "token": "So11111111111111111111111111111111111111112", "firstLpEvent": 1791302002, "swapVolumeUsd": 657350.330032, "depositsUsd": 46262.672679370095, "withdrawalsUsd": 12314.010901404514, "netFlowUsd": 33948.66177796558, "feesClaimedUsd": 25.931564176688006, "openPositions": 22, "openOwners": 17, "hourly": [ { "hour": 1791298800, "depositsUsd": 30397.05064594894, "withdrawalsUsd": 7196.542626796252, "feesClaimedUsd": 0.370617802409548, "adds": 52, "removes": 28, "claims": 30, "opens": 24, "closes": 0, "lps": 10 }, { "hour": 1791302400, "depositsUsd": 15865.622033421156, "withdrawalsUsd": 5117.468274608262, "feesClaimedUsd": 25.56094637427846, "adds": 56, "removes": 35, "claims": 36, "opens": 27, "closes": 0, "lps": 15 } ], "updatedAt": 1791303661 } } } }, "400": { "description": "`BAD_ADDRESS` / `BAD_HOURS`, or `UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`POOL_NOT_FOUND`: no liquidity event in this pool since LP decoding started, or its venue is not read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/lp/pool/{address}/positions": { "get": { "tags": [ "Solana data" ], "operationId": "solLpPoolPositions", "summary": "A pool's positions", "description": "The pool's positions, most recently active first. Cached 20 seconds.\n\nLiquidity on Solana from Chord's own tape: adds, removes, fee claims, position opens and closes, decoded from the same blocks as the swaps. No key needed.\n\n- **Venues.** Meteora DLMM, Meteora DAMM v2, Raydium CLMM and PumpSwap. Orca Whirlpools, Raydium CPMM / v4 and Meteora dynamic pools are not read yet.\n- **Since.** `since` is when LP decoding started (2026-10-06 15:53 UTC); windows never start before it. A position opened earlier is `partial: true` and carries no PnL.\n- **Fees are claimed fees.** An LP's fees appear when it claims them, so a window's fees understate what the pool earned, and one claim can hold days of fees.\n- **Positions.** One row per position account (DLMM / DAMM v2 position, Raydium CLMM position NFT, PumpSwap LP token account), rebuilt from all its events. `lower` / `upper` are DLMM bin ids or Raydium CLMM ticks; null = full range. Realized PnL = withdrawn + fees claimed − deposited, only for a position seen from its open to its close with every amount priced. An open position's current value is not in the events: none is given.\n- **Amounts** are whole tokens in the pool's own order (`mintA` / `mintB`); USD is valued when the event happened. Each add / remove / claim is checked against the pool vaults' balance changes in the same transaction (`verified`).\n- **Addresses** are base58 and case-sensitive, as on the other Solana routes.", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "description": "Pool address, base58." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "closed", "all" ], "default": "all" }, "description": "Which positions." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "const": "solana" }, "pool": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "status": { "type": "string", "description": "" }, "since": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/SolLpPosition" } }, "updatedAt": { "type": "integer", "description": "Unix time, SECONDS, when the Solana box built this answer. Unlike the rest of the API (milliseconds)." } } }, "example": { "chain": "solana", "pool": "HTvjzsfX3yU6BUodCjZ5vZkUrAxMDTrBs3CJaq43ashR", "status": "open", "since": 1791301995, "positions": [ { "position": "6gDiPzm69sdQMAAMUjSwY8n1ruPXYpy6Yx5tTt3PBgPv", "dex": "meteora_dlmm", "pool": "HTvjzsfX3yU6BUodCjZ5vZkUrAxMDTrBs3CJaq43ashR", "owner": "GDzKV9YibjzWNtFCeGSAXntzv8e2tU1UcLPV1hoXxXJM", "mintA": "So11111111111111111111111111111111111111112", "symbolA": "SOL", "mintB": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "symbolB": "USDC", "lower": -21194, "upper": -21170, "status": "open", "openedAt": 1791303634, "closedAt": null, "firstEvent": 1791303634, "lastEvent": 1791303634, "events": 2, "depositedA": 0, "depositedB": 65.188341, "withdrawnA": 0, "withdrawnB": 0, "feesA": 0, "feesB": 0, "depositedUsd": 65.188341, "withdrawnUsd": 0, "feesClaimedUsd": 0, "realizedPnlUsd": null, "partial": false, "unpricedEvents": 0 }, { "position": "G8LWKkSM58cGfty8Huw7PAsaRz86LqyaysUhMLL8HdD3", "dex": "meteora_dlmm", "pool": "HTvjzsfX3yU6BUodCjZ5vZkUrAxMDTrBs3CJaq43ashR", "owner": "zmpMLRAH2Nt5ZDaax1jXH9QdmVRzw7rHm84sKpZa6wy", "mintA": "So11111111111111111111111111111111111111112", "symbolA": "SOL", "mintB": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "symbolB": "USDC", "lower": -21167, "upper": -21091, "status": "open", "openedAt": 1791302020, "closedAt": null, "firstEvent": 1791302020, "lastEvent": 1791303567, "events": 25, "depositedA": 22.506085353, "depositedB": 1668.168769, "withdrawnA": 16.697187434, "withdrawnB": 1367.959384, "feesA": 0.001835888, "feesB": 0.267907, "depositedUsd": 4385.0568295447565, "withdrawnUsd": 3383.4942419848394, "feesClaimedUsd": 0.48990795627555367, "realizedPnlUsd": null, "partial": false, "unpricedEvents": 0 } ], "updatedAt": 1791303662 } } } }, "400": { "description": "`BAD_ADDRESS` / `BAD_STATUS` / `BAD_LIMIT`, or `UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/lp/wallet/{address}": { "get": { "tags": [ "Solana data" ], "operationId": "solLpWallet", "summary": "A wallet's LP positions", "description": "The wallet's positions as owner (DLMM: the position's owner, not an operator acting for it), most recently active first, with totals over every position of the `status` asked: deposited, withdrawn, claimed fees, realized PnL and win rate over positions seen open to close. Cached 15 seconds.\n\nLiquidity on Solana from Chord's own tape: adds, removes, fee claims, position opens and closes, decoded from the same blocks as the swaps. No key needed.\n\n- **Venues.** Meteora DLMM, Meteora DAMM v2, Raydium CLMM and PumpSwap. Orca Whirlpools, Raydium CPMM / v4 and Meteora dynamic pools are not read yet.\n- **Since.** `since` is when LP decoding started (2026-10-06 15:53 UTC); windows never start before it. A position opened earlier is `partial: true` and carries no PnL.\n- **Fees are claimed fees.** An LP's fees appear when it claims them, so a window's fees understate what the pool earned, and one claim can hold days of fees.\n- **Positions.** One row per position account (DLMM / DAMM v2 position, Raydium CLMM position NFT, PumpSwap LP token account), rebuilt from all its events. `lower` / `upper` are DLMM bin ids or Raydium CLMM ticks; null = full range. Realized PnL = withdrawn + fees claimed − deposited, only for a position seen from its open to its close with every amount priced. An open position's current value is not in the events: none is given.\n- **Amounts** are whole tokens in the pool's own order (`mintA` / `mintB`); USD is valued when the event happened. Each add / remove / claim is checked against the pool vaults' balance changes in the same transaction (`verified`).\n- **Addresses** are base58 and case-sensitive, as on the other Solana routes.", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "description": "Wallet address, base58, exactly as it appears on-chain." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "closed", "all" ], "default": "all" }, "description": "Which positions." }, { "name": "unit", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "usd", "native" ], "default": "usd" }, "description": "`native` = the money fields of the answer in SOL: every deposit, withdrawal and claimed fee converted at the SOL price of its own minute, so a wallet that put SOL in and took the same SOL out reads flat whatever SOL did in dollars (win rate and expected value follow the unit). The fields keep their `…Usd` names; `unit` and `unitSymbol` in the answer say what they carry. `503 UNIT_NOT_READY` while positions are being folded again; another value is `400 BAD_UNIT`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 }, "description": "Rows; totals cover every position." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "const": "solana" }, "wallet": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "status": { "type": "string", "description": "" }, "since": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "positions": { "type": "integer", "description": "" }, "open": { "type": "integer", "description": "" }, "closed": { "type": "integer", "description": "" }, "pools": { "type": "integer", "description": "" }, "depositedUsd": { "type": "number", "description": "" }, "withdrawnUsd": { "type": "number", "description": "" }, "feesClaimedUsd": { "type": "number", "description": "" }, "realizedPnlUsd": { "type": [ "number", "null" ], "description": "" }, "realizedPositions": { "type": "integer", "description": "" }, "winRate": { "type": [ "number", "null" ], "description": "0–1." }, "evUsd": { "type": [ "number", "null" ], "description": "Mean result of a realized position." }, "avgAgeHours": { "type": [ "number", "null" ], "description": "" }, "avgDepositUsd": { "type": [ "number", "null" ], "description": "" }, "firstTs": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "lastTs": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "history": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "description": "YYYY-MM-DD, UTC" }, "profitUsd": { "type": "number", "description": "Result of the realized positions that ended on the day." }, "feesUsd": { "type": "number", "description": "Fees claimed by the positions that ended, or were last touched, on the day." }, "positions": { "type": "integer", "description": "" } } }, "description": "One row per day a position ended on, oldest first, whatever `status` was asked. Its sums are `realizedPnlUsd` and `feesClaimedUsd` of status=all." }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/SolLpPosition" } }, "updatedAt": { "type": "integer", "description": "Unix time, SECONDS, when the Solana box built this answer. Unlike the rest of the API (milliseconds)." } } }, "example": { "chain": "solana", "wallet": "GwBsj9GJdFrATQs1k9EYUyfaatKZDiViy8tkU9JP3TUL", "status": "all", "since": 1791301995, "positions": 750, "open": 10, "closed": 740, "pools": 26, "depositedUsd": 2649179.5405913335, "withdrawnUsd": 2647817.6755300546, "feesClaimedUsd": 18015.87641073856, "realizedPnlUsd": 3345.1307860846005, "realizedPositions": 722, "winRate": 0.5512465373961218, "evUsd": 4.633145133081164, "avgAgeHours": 2.460573222071869, "avgDepositUsd": 3575.1410804201532, "firstTs": 1790774387, "lastTs": 1791825711, "history": [ { "day": "2026-09-30", "profitUsd": 0, "feesUsd": 71.65268316036983, "positions": 2 }, { "day": "2026-10-01", "profitUsd": 0, "feesUsd": 7.083795820757369, "positions": 2 }, { "day": "2026-10-04", "profitUsd": 0, "feesUsd": 38.751457795784674, "positions": 2 } ], "rows": [ { "position": "69v9s6gQje3Rk8u3vwn8kSEAxX1BNciUJEhG5Vb2fcPA", "dex": "meteora_dlmm", "pool": "GgoFghiA6Ca7YNmG6dRxwKQWkZhRK8ND47EREz46arot", "owner": "GwBsj9GJdFrATQs1k9EYUyfaatKZDiViy8tkU9JP3TUL", "mintA": "WXMRyRZhsa19ety5erZhHg4N3xj3EVN92u94422teJp", "symbolA": "XMR", "mintB": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "symbolB": "USDC", "lower": -7544, "upper": -7544, "status": "closed", "openedAt": 1791825038, "closedAt": 1791825711, "firstEvent": 1791825038, "lastEvent": 1791825711, "events": 5, "depositedA": 0, "depositedB": 9871.870653, "withdrawnA": 15.009532666305, "withdrawnB": 1897.560215, "feesA": 0.017992659416, "feesB": 2.482098, "depositedUsd": 9871.870653, "withdrawnUsd": 9879.734769314513, "feesClaimedUsd": 12.050720244798956, "realizedPnlUsd": 19.91483655931188, "partial": false, "unpricedEvents": 0 }, { "position": "BpHs9ZbEoCTrM2P5JKY3cgxWhUTeMMUMa41jWiUjwQ9w", "dex": "meteora_dlmm", "pool": "GgoFghiA6Ca7YNmG6dRxwKQWkZhRK8ND47EREz46arot", "owner": "GwBsj9GJdFrATQs1k9EYUyfaatKZDiViy8tkU9JP3TUL", "mintA": "WXMRyRZhsa19ety5erZhHg4N3xj3EVN92u94422teJp", "symbolA": "XMR", "mintB": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "symbolB": "USDC", "lower": -7545, "upper": -7545, "status": "closed", "openedAt": 1791824988, "closedAt": 1791825034, "firstEvent": 1791824988, "lastEvent": 1791825034, "events": 5, "depositedA": 0, "depositedB": 9871.839615, "withdrawnA": 0, "withdrawnB": 9871.405961, "feesA": 0.000141564492, "feesB": 0.464692, "depositedUsd": 9871.839615, "withdrawnUsd": 9871.405961, "feesClaimedUsd": 0.5398261385532628, "realizedPnlUsd": 0.10617213855221053, "partial": false, "unpricedEvents": 0 } ], "updatedAt": 1791836517 } } } }, "400": { "description": "`BAD_ADDRESS` / `BAD_STATUS` / `BAD_LIMIT`, or `UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/lp/pool/{address}/events": { "get": { "tags": [ "Solana data" ], "operationId": "solLpPoolEvents", "summary": "A pool's liquidity events", "description": "Adds, removes, fee claims, opens and closes, newest first. A close row of a DLMM `close_position2` or a Raydium CLMM position has no `pool`: the instruction does not carry it.\n\nLiquidity on Solana from Chord's own tape: adds, removes, fee claims, position opens and closes, decoded from the same blocks as the swaps. No key needed.\n\n- **Venues.** Meteora DLMM, Meteora DAMM v2, Raydium CLMM and PumpSwap. Orca Whirlpools, Raydium CPMM / v4 and Meteora dynamic pools are not read yet.\n- **Since.** `since` is when LP decoding started (2026-10-06 15:53 UTC); windows never start before it. A position opened earlier is `partial: true` and carries no PnL.\n- **Fees are claimed fees.** An LP's fees appear when it claims them, so a window's fees understate what the pool earned, and one claim can hold days of fees.\n- **Positions.** One row per position account (DLMM / DAMM v2 position, Raydium CLMM position NFT, PumpSwap LP token account), rebuilt from all its events. `lower` / `upper` are DLMM bin ids or Raydium CLMM ticks; null = full range. Realized PnL = withdrawn + fees claimed − deposited, only for a position seen from its open to its close with every amount priced. An open position's current value is not in the events: none is given.\n- **Amounts** are whole tokens in the pool's own order (`mintA` / `mintB`); USD is valued when the event happened. Each add / remove / claim is checked against the pool vaults' balance changes in the same transaction (`verified`).\n- **Addresses** are base58 and case-sensitive, as on the other Solana routes.", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "description": "Pool address, base58." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 4000000000 }, "description": "Exclusive cursor, Unix seconds: rows strictly older than it. Pass the last row's `ts` for the next page. Several swaps can share a second, so a page boundary can skip the rest of that second: overlap with `ts + 1` and drop rows whose `tx` you already have." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "const": "solana" }, "pool": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "events": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "integer", "description": "Unix time, seconds, UTC." }, "slot": { "type": "integer", "description": "" }, "signature": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{64,88}$", "description": "Transaction signature, base58." }, "dex": { "type": "string", "description": "`meteora_dlmm` · `meteora_damm_v2` · `raydium_clmm` · `pumpswap`." }, "kind": { "type": "string", "enum": [ "add", "remove", "fee", "open", "close" ] }, "pool": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "position": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "owner": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "amountA": { "type": [ "number", "null" ], "description": "Whole tokens." }, "amountB": { "type": [ "number", "null" ], "description": "" }, "usd": { "type": [ "number", "null" ], "description": "" }, "lower": { "type": [ "integer", "null" ], "description": "" }, "upper": { "type": [ "integer", "null" ], "description": "" }, "verified": { "type": [ "boolean", "null" ], "description": "true = matches the vault balance changes; null = could not be checked (shared vault, first deposit of a new pool)" } } } }, "nextBefore": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." } } }, "example": { "chain": "solana", "pool": "HTvjzsfX3yU6BUodCjZ5vZkUrAxMDTrBs3CJaq43ashR", "events": [ { "ts": 1791303634, "slot": 453953506, "signature": "5bPcr5RdHzhoYFECwNaxp6FFwiv1xCcMxkGhLfrzZJaHos6UWJdnCey9FgUhfUC8kZqLgsrBy2ifzw8b9oQsyajc", "dex": "meteora_dlmm", "kind": "add", "pool": "HTvjzsfX3yU6BUodCjZ5vZkUrAxMDTrBs3CJaq43ashR", "position": "6gDiPzm69sdQMAAMUjSwY8n1ruPXYpy6Yx5tTt3PBgPv", "owner": "GDzKV9YibjzWNtFCeGSAXntzv8e2tU1UcLPV1hoXxXJM", "amountA": 0, "amountB": 65.188341, "usd": 65.188341, "lower": null, "upper": null, "verified": true }, { "ts": 1791303634, "slot": 453953506, "signature": "5bPcr5RdHzhoYFECwNaxp6FFwiv1xCcMxkGhLfrzZJaHos6UWJdnCey9FgUhfUC8kZqLgsrBy2ifzw8b9oQsyajc", "dex": "meteora_dlmm", "kind": "open", "pool": "HTvjzsfX3yU6BUodCjZ5vZkUrAxMDTrBs3CJaq43ashR", "position": "6gDiPzm69sdQMAAMUjSwY8n1ruPXYpy6Yx5tTt3PBgPv", "owner": "GDzKV9YibjzWNtFCeGSAXntzv8e2tU1UcLPV1hoXxXJM", "amountA": 0, "amountB": 0, "usd": null, "lower": -21194, "upper": -21170, "verified": null } ], "nextBefore": 1791303634 } } } }, "400": { "description": "`BAD_ADDRESS` / `BAD_LIMIT` / `BAD_CURSOR`, or `UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/lp/wallet/{address}/events": { "get": { "tags": [ "Solana data" ], "operationId": "solLpWalletEvents", "summary": "A wallet's liquidity events", "description": "Adds, removes, fee claims, opens and closes, newest first (the wallet as the position's owner). A close row of a DLMM `close_position2` or a Raydium CLMM position has no `pool`: the instruction does not carry it.\n\nLiquidity on Solana from Chord's own tape: adds, removes, fee claims, position opens and closes, decoded from the same blocks as the swaps. No key needed.\n\n- **Venues.** Meteora DLMM, Meteora DAMM v2, Raydium CLMM and PumpSwap. Orca Whirlpools, Raydium CPMM / v4 and Meteora dynamic pools are not read yet.\n- **Since.** `since` is when LP decoding started (2026-10-06 15:53 UTC); windows never start before it. A position opened earlier is `partial: true` and carries no PnL.\n- **Fees are claimed fees.** An LP's fees appear when it claims them, so a window's fees understate what the pool earned, and one claim can hold days of fees.\n- **Positions.** One row per position account (DLMM / DAMM v2 position, Raydium CLMM position NFT, PumpSwap LP token account), rebuilt from all its events. `lower` / `upper` are DLMM bin ids or Raydium CLMM ticks; null = full range. Realized PnL = withdrawn + fees claimed − deposited, only for a position seen from its open to its close with every amount priced. An open position's current value is not in the events: none is given.\n- **Amounts** are whole tokens in the pool's own order (`mintA` / `mintB`); USD is valued when the event happened. Each add / remove / claim is checked against the pool vaults' balance changes in the same transaction (`verified`).\n- **Addresses** are base58 and case-sensitive, as on the other Solana routes.", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "description": "Wallet address, base58." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 4000000000 }, "description": "Exclusive cursor, Unix seconds: rows strictly older than it. Pass the last row's `ts` for the next page. Several swaps can share a second, so a page boundary can skip the rest of that second: overlap with `ts + 1` and drop rows whose `tx` you already have." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "const": "solana" }, "owner": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "events": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "integer", "description": "Unix time, seconds, UTC." }, "slot": { "type": "integer", "description": "" }, "signature": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{64,88}$", "description": "Transaction signature, base58." }, "dex": { "type": "string", "description": "`meteora_dlmm` · `meteora_damm_v2` · `raydium_clmm` · `pumpswap`." }, "kind": { "type": "string", "enum": [ "add", "remove", "fee", "open", "close" ] }, "pool": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "position": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "owner": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "amountA": { "type": [ "number", "null" ], "description": "Whole tokens." }, "amountB": { "type": [ "number", "null" ], "description": "" }, "usd": { "type": [ "number", "null" ], "description": "" }, "lower": { "type": [ "integer", "null" ], "description": "" }, "upper": { "type": [ "integer", "null" ], "description": "" }, "verified": { "type": [ "boolean", "null" ], "description": "true = matches the vault balance changes; null = could not be checked (shared vault, first deposit of a new pool)" } } } }, "nextBefore": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." } } }, "example": { "chain": "solana", "owner": "GwBsj9GJdFrATQs1k9EYUyfaatKZDiViy8tkU9JP3TUL", "events": [ { "ts": 1791303527, "slot": 453953116, "signature": "843tuGhTxg7i7CEFuJsFfJPhxhRMcL4mr2gDaHifmm8d9Gfzd7AKgHXXj6gCzNgos9tyjcSLCVXrvwWKodsTq5u", "dex": "meteora_dlmm", "kind": "add", "pool": "5whNk71ua6aRtNKazDqEeAimmfzuX9epJcjh4isQKprn", "position": "9FSWX8ctaKQKYsTpxuuXEMWVXYm3NGm9cDCLYvs6zhE7", "owner": "GwBsj9GJdFrATQs1k9EYUyfaatKZDiViy8tkU9JP3TUL", "amountA": 87.25797003, "amountB": 0, "usd": 15125.346891374138, "lower": null, "upper": null, "verified": true }, { "ts": 1791303527, "slot": 453953116, "signature": "843tuGhTxg7i7CEFuJsFfJPhxhRMcL4mr2gDaHifmm8d9Gfzd7AKgHXXj6gCzNgos9tyjcSLCVXrvwWKodsTq5u", "dex": "meteora_dlmm", "kind": "open", "pool": "5whNk71ua6aRtNKazDqEeAimmfzuX9epJcjh4isQKprn", "position": "9FSWX8ctaKQKYsTpxuuXEMWVXYm3NGm9cDCLYvs6zhE7", "owner": "GwBsj9GJdFrATQs1k9EYUyfaatKZDiViy8tkU9JP3TUL", "amountA": 0, "amountB": 0, "usd": null, "lower": 688, "upper": 693, "verified": null } ], "nextBefore": 1791303527 } } } }, "400": { "description": "`BAD_ADDRESS` / `BAD_LIMIT` / `BAD_CURSOR`, or `UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains/solana/lp/position/{address}/events": { "get": { "tags": [ "Solana data" ], "operationId": "solLpPositionEvents", "summary": "One position's events", "description": "Adds, removes, fee claims, opens and closes, newest first. A close row of a DLMM `close_position2` or a Raydium CLMM position has no `pool`: the instruction does not carry it.\n\nLiquidity on Solana from Chord's own tape: adds, removes, fee claims, position opens and closes, decoded from the same blocks as the swaps. No key needed.\n\n- **Venues.** Meteora DLMM, Meteora DAMM v2, Raydium CLMM and PumpSwap. Orca Whirlpools, Raydium CPMM / v4 and Meteora dynamic pools are not read yet.\n- **Since.** `since` is when LP decoding started (2026-10-06 15:53 UTC); windows never start before it. A position opened earlier is `partial: true` and carries no PnL.\n- **Fees are claimed fees.** An LP's fees appear when it claims them, so a window's fees understate what the pool earned, and one claim can hold days of fees.\n- **Positions.** One row per position account (DLMM / DAMM v2 position, Raydium CLMM position NFT, PumpSwap LP token account), rebuilt from all its events. `lower` / `upper` are DLMM bin ids or Raydium CLMM ticks; null = full range. Realized PnL = withdrawn + fees claimed − deposited, only for a position seen from its open to its close with every amount priced. An open position's current value is not in the events: none is given.\n- **Amounts** are whole tokens in the pool's own order (`mintA` / `mintB`); USD is valued when the event happened. Each add / remove / claim is checked against the pool vaults' balance changes in the same transaction (`verified`).\n- **Addresses** are base58 and case-sensitive, as on the other Solana routes.", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "description": "Position address, base58." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 4000000000 }, "description": "Exclusive cursor, Unix seconds: rows strictly older than it. Pass the last row's `ts` for the next page. Several swaps can share a second, so a page boundary can skip the rest of that second: overlap with `ts + 1` and drop rows whose `tx` you already have." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "const": "solana" }, "position": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "events": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "integer", "description": "Unix time, seconds, UTC." }, "slot": { "type": "integer", "description": "" }, "signature": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{64,88}$", "description": "Transaction signature, base58." }, "dex": { "type": "string", "description": "`meteora_dlmm` · `meteora_damm_v2` · `raydium_clmm` · `pumpswap`." }, "kind": { "type": "string", "enum": [ "add", "remove", "fee", "open", "close" ] }, "pool": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "position": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "owner": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "amountA": { "type": [ "number", "null" ], "description": "Whole tokens." }, "amountB": { "type": [ "number", "null" ], "description": "" }, "usd": { "type": [ "number", "null" ], "description": "" }, "lower": { "type": [ "integer", "null" ], "description": "" }, "upper": { "type": [ "integer", "null" ], "description": "" }, "verified": { "type": [ "boolean", "null" ], "description": "true = matches the vault balance changes; null = could not be checked (shared vault, first deposit of a new pool)" } } } }, "nextBefore": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." } } }, "example": { "chain": "solana", "position": "BJMyRCurUG45Lst2tZf2RMVbxwCopyWzxzHjgQz5ET6m", "events": [ { "ts": 1791303523, "slot": 453953100, "signature": "2e9A11ocj5EURDZJj7DYtFPQN7D62Xjdg1sW9aAyN8RJ4RmFBf9N73D29G11zJnJGc8HUnzQQ1WkH1KWduaggb5p", "dex": "meteora_dlmm", "kind": "close", "pool": null, "position": "BJMyRCurUG45Lst2tZf2RMVbxwCopyWzxzHjgQz5ET6m", "owner": "GwBsj9GJdFrATQs1k9EYUyfaatKZDiViy8tkU9JP3TUL", "amountA": null, "amountB": null, "usd": null, "lower": null, "upper": null, "verified": null }, { "ts": 1791303523, "slot": 453953100, "signature": "2e9A11ocj5EURDZJj7DYtFPQN7D62Xjdg1sW9aAyN8RJ4RmFBf9N73D29G11zJnJGc8HUnzQQ1WkH1KWduaggb5p", "dex": "meteora_dlmm", "kind": "fee", "pool": "5whNk71ua6aRtNKazDqEeAimmfzuX9epJcjh4isQKprn", "position": "BJMyRCurUG45Lst2tZf2RMVbxwCopyWzxzHjgQz5ET6m", "owner": "GwBsj9GJdFrATQs1k9EYUyfaatKZDiViy8tkU9JP3TUL", "amountA": 0.03680336, "amountB": 0, "usd": 6.379515665752227, "lower": null, "upper": null, "verified": true } ], "nextBefore": 1791303523 } } } }, "400": { "description": "`BAD_ADDRESS` / `BAD_LIMIT` / `BAD_CURSOR`, or `UNSUPPORTED_CHAIN` (Solana is not public on this deployment and the request has no `X-API-Key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`CHAIN_DATA_UNAVAILABLE` (the Solana store did not answer in time) or `CHAIN_NOT_ENABLED` (the lane is off on this deployment). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sol/trade/config": { "get": { "tags": [ "Solana swaps" ], "operationId": "solTradeConfig", "summary": "May this caller trade", "description": "`enabled` = the lane is on in this deployment, `open` = open to everyone, `allowed` = open to the caller who asks (a beta account, or everyone once `open`). Never gated, never cached.\n\n**Open to everyone** since 2026-10-15, no key needed (an `X-API-Key` raises the rate limit). `/sol/trade/config` says whether the lane is on for the caller; when it is off the other routes answer `503 TRADE_NOT_ENABLED`.\n\nA quote is SOL against one token, bought or sold. For every quote Chord builds, for **your wallet**, the transaction of each route — `direct` (Chord's own router: Raydium AMM v4 / CPMM / CLMM, Orca Whirlpool, Meteora DLMM / DAMM v2, Meteora DBC, Raydium LaunchLab, pump.fun, PumpSwap; up to two pools), `jupiter` (Jupiter's swap API, no Jupiter fee) and `jupiter_meta` (Jupiter's order: Metis, its RFQ market makers, DFlow, OKX; Jupiter's fee inside the amount) — simulates each on the chain and returns the one that leaves the wallet with the most: tokens for a buy, SOL for a sell, after every fee. Ties go to `direct`, then `jupiter`. A route handing back under half of the input's market value is refused.\n\nAmounts are base units as decimal strings: lamports for SOL, the token's smallest unit otherwise. Addresses are base58, case-sensitive. Chord takes no fee on Solana today. Nothing is signed by Chord: you sign `quote.tx` unchanged and send it back.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "" }, "open": { "type": "boolean", "description": "" }, "allowed": { "type": "boolean", "description": "" } } }, "example": { "enabled": true, "open": false, "allowed": false } } } } } } }, "/sol/trade/quote": { "get": { "tags": [ "Solana swaps" ], "operationId": "solTradeQuote", "summary": "Best quote: Chord's route or Jupiter's", "description": "The quote of the route that leaves the wallet with the most, its unsigned transaction, and what every route offered (`compared`). `ok: false` with `quote: null` and a `reason` is an answer (no route for this token, size or wallet), not an error.\n\n**Open to everyone** since 2026-10-15, no key needed (an `X-API-Key` raises the rate limit). `/sol/trade/config` says whether the lane is on for the caller; when it is off the other routes answer `503 TRADE_NOT_ENABLED`.\n\nA quote is SOL against one token, bought or sold. For every quote Chord builds, for **your wallet**, the transaction of each route — `direct` (Chord's own router: Raydium AMM v4 / CPMM / CLMM, Orca Whirlpool, Meteora DLMM / DAMM v2, Meteora DBC, Raydium LaunchLab, pump.fun, PumpSwap; up to two pools), `jupiter` (Jupiter's swap API, no Jupiter fee) and `jupiter_meta` (Jupiter's order: Metis, its RFQ market makers, DFlow, OKX; Jupiter's fee inside the amount) — simulates each on the chain and returns the one that leaves the wallet with the most: tokens for a buy, SOL for a sell, after every fee. Ties go to `direct`, then `jupiter`. A route handing back under half of the input's market value is refused.\n\nAmounts are base units as decimal strings: lamports for SOL, the token's smallest unit otherwise. Addresses are base58, case-sensitive. Chord takes no fee on Solana today. Nothing is signed by Chord: you sign `quote.tx` unchanged and send it back.", "parameters": [ { "name": "mint", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "description": "The token." }, { "name": "side", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "buy", "sell" ] }, "description": "`buy` = SOL in, token out · `sell` = token in, SOL out." }, { "name": "amount", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,19}$" }, "description": "Input in base units: lamports for a buy, the token's smallest unit for a sell." }, { "name": "wallet", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "description": "The wallet that will sign: every route is simulated for it, so it must hold the input (and SOL for fees)." }, { "name": "slippageBps", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 100 }, "description": "Tolerance that sets `minOut`." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "" }, "quote": { "$ref": "#/components/schemas/SolTradeQuote", "type": [ null, "null" ] }, "reason": { "type": "string", "enum": [ "not_a_token", "bad_request", "no_pool", "no_template", "no_route", "wallet_cannot", "pool_limit", "no_output", "simulation_failed", "too_large", "error", "off" ], "description": "Why a route has no quote. `wallet_cannot` (no funds, or no token account), `pool_limit` (a size the pool refuses, or under half the market value) and `no_output` are about the request; `no_pool` = the route does not cover this token; `simulation_failed`, `too_large`, `error` = the route failed; `off` = not asked or switched off." }, "detail": { "type": "string", "description": "" }, "compared": { "type": "object", "properties": { "direct": { "oneOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "outAmount": { "type": "string", "pattern": "^\\d+$", "description": "Base units as a decimal string (lamports for SOL)." }, "measured": { "type": "string", "enum": [ "simulated", "quoted" ], "description": "`simulated` = read from a simulation of the route's own transaction; `quoted` = Jupiter's own figure, shown when a route already in hand gives at least that much, so Jupiter's transaction was not built." }, "networkFeeLamports": { "type": [ "integer", "null" ], "description": "" }, "units": { "type": [ "integer", "null" ], "description": "Compute units." }, "ms": { "type": "number", "description": "" } } }, { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "reason": { "type": "string", "enum": [ "not_a_token", "bad_request", "no_pool", "no_template", "no_route", "wallet_cannot", "pool_limit", "no_output", "simulation_failed", "too_large", "error", "off" ], "description": "Why a route has no quote. `wallet_cannot` (no funds, or no token account), `pool_limit` (a size the pool refuses, or under half the market value) and `no_output` are about the request; `no_pool` = the route does not cover this token; `simulation_failed`, `too_large`, `error` = the route failed; `off` = not asked or switched off." }, "detail": { "type": "string", "description": "What the route said, for a human." }, "ms": { "type": "number", "description": "" } } } ] }, "jupiter": { "oneOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "outAmount": { "type": "string", "pattern": "^\\d+$", "description": "Base units as a decimal string (lamports for SOL)." }, "measured": { "type": "string", "enum": [ "simulated", "quoted" ], "description": "`simulated` = read from a simulation of the route's own transaction; `quoted` = Jupiter's own figure, shown when a route already in hand gives at least that much, so Jupiter's transaction was not built." }, "networkFeeLamports": { "type": [ "integer", "null" ], "description": "" }, "units": { "type": [ "integer", "null" ], "description": "Compute units." }, "ms": { "type": "number", "description": "" } } }, { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "reason": { "type": "string", "enum": [ "not_a_token", "bad_request", "no_pool", "no_template", "no_route", "wallet_cannot", "pool_limit", "no_output", "simulation_failed", "too_large", "error", "off" ], "description": "Why a route has no quote. `wallet_cannot` (no funds, or no token account), `pool_limit` (a size the pool refuses, or under half the market value) and `no_output` are about the request; `no_pool` = the route does not cover this token; `simulation_failed`, `too_large`, `error` = the route failed; `off` = not asked or switched off." }, "detail": { "type": "string", "description": "What the route said, for a human." }, "ms": { "type": "number", "description": "" } } } ] }, "jupiterMeta": { "oneOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "outAmount": { "type": "string", "pattern": "^\\d+$", "description": "Base units as a decimal string (lamports for SOL)." }, "measured": { "type": "string", "enum": [ "simulated", "quoted" ], "description": "`simulated` = read from a simulation of the route's own transaction; `quoted` = Jupiter's own figure, shown when a route already in hand gives at least that much, so Jupiter's transaction was not built." }, "networkFeeLamports": { "type": [ "integer", "null" ], "description": "" }, "units": { "type": [ "integer", "null" ], "description": "Compute units." }, "ms": { "type": "number", "description": "" } } }, { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "reason": { "type": "string", "enum": [ "not_a_token", "bad_request", "no_pool", "no_template", "no_route", "wallet_cannot", "pool_limit", "no_output", "simulation_failed", "too_large", "error", "off" ], "description": "Why a route has no quote. `wallet_cannot` (no funds, or no token account), `pool_limit` (a size the pool refuses, or under half the market value) and `no_output` are about the request; `no_pool` = the route does not cover this token; `simulation_failed`, `too_large`, `error` = the route failed; `off` = not asked or switched off." }, "detail": { "type": "string", "description": "What the route said, for a human." }, "ms": { "type": "number", "description": "" } } } ] } }, "description": "What each route offered. `direct` is the better of the pump route and Chord's router." }, "ms": { "type": "number", "description": "" } } }, "example": { "ok": true, "quote": { "ok": true, "route": "direct", "mint": "98sMhvDwXj1RQi5c5Mndm3vPe9cBqPrbLaufMXFNMh5g", "side": "buy", "inAmount": "1000000000", "outAmount": "1291169314", "minOut": "1278257620", "slippageBps": 100, "feeLamports": "0", "feeBps": 0, "networkFeeLamports": 13462, "units": 53847, "walletLamportsDelta": "-1001501902", "tx": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAQAJF36MCIdgv94d3c8ywX8gm4JC7lKq8TH6zYjQ6ixtCwbybQ/ffN89KMzS1moKr3xD+eaLjFLD93Uu7/6fCChoRW+33r5/N5kXzVmVKDnDCPuAkyP2Gtb/z4vZXn9rJrNgnlYtVRIeQFP9RCTKJ4QcFXTmTFrjug4KMZNwxfvPi59T3FuLdqms3IWcwYxorNprzTnpS/UIS8cr22A9a0z5hMQguKAAE9blFXzMeY2Ul+aVjNz5CWJMPZFyDxSfYLteeLFBAdK4u9M26/E24V6FVw6ivZ7F6IKKhmtyA8AUTfymAHzJZSEoI1LREgsRMMb+c3W9Pk5HT+Ci3aCI/WgF+bbdWqpQ+Iq9Y9M30s68O5hGfLeLdlEbgXgDuUWpI64G0UeeEGWqwXbkX0swI7SX5eIdaHc3Qyw0ilOG3FwaVKK3wRwJ7Hd/cQIYGczxT34DxoMVJNeXfeJLQyrGn/5CRYApa3YIBFLBUkXofOcSUKM6WFvxPe9wsqWKl3DHs4sghgHyPnPlSprtPOAV8DiJLgrp8nHRCYh08HSC9eHtCKRKNckuzi1T27nDcSwt5D+6EBI+n21RbgNj47MiJk7XsmsDBkZv5SEXMv/srbpyw5vnvIzlu8X3EmssQ5s6QAAAAIyXJY9OJInxuz0QKRSODYMLWhOZ2v8QhASOe9jb6fhZBpuIV/6rgYT7aH9jRhjANdrEOdwa6ztVmKDwAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAbd9uHXZaGT2cvhRs7reawctIXtX1s3kTqM9YV+/wCpeOF/+c+e8osV49WDJ0Hs54BOB9XJf0LvM+1fBZx0kl8E6eEvvIToJskyzOniZAzOFVkMHGJzsJJXCLo7hSCwvAVKU1qZKSEGTSTocWDaOHx8NbXdvJK7geQfqEBBBUSNsnDWf6mMUc8CEwUTWJYrrzV0K+1ZydlEXpwNDIXHzZF54KJrKMEZBlNIu3jg6xTnaDFVOdmUnu4hys0zsh+wiAgOAAUCiUoBAA4ACQOghgEAAAAAAA8GAAEAEBESAQEPBgACABMREgEBEQIAAQwCAAAAAMqaOwAAAAASAQEBERQWAwQFBgECEBMHFAASEhUWFAgJCgsMDRxBSz9M61tbiADKmjsAAAAA1KkwTAAAAAAAAAAAEgMBAAABCQA=", "txBytes": 962, "blockhash": "9CkzxZDnrGUqa6v7wWKq3jMxYFkLvqE1c8ogo7DURJjq", "lastValidBlockHeight": 435407004, "simulatedSlot": 457371000, "ms": 269, "venue": "meteora_dlmm", "pool": "6oQ9wVex4mKZti2GsGCfD8FWTMMC9PLQkztRU5cd6MK8", "hops": [ { "label": "Meteora DLMM", "pool": "6oQ9wVex4mKZti2GsGCfD8FWTMMC9PLQkztRU5cd6MK8", "percent": 100 } ] }, "compared": { "direct": { "ok": true, "outAmount": "1291169314", "measured": "simulated", "networkFeeLamports": 13462, "units": 53847, "ms": 269 }, "jupiter": { "ok": true, "outAmount": "1291041752", "measured": "simulated", "networkFeeLamports": 23574, "units": 149660, "ms": 128 }, "jupiterMeta": { "ok": true, "outAmount": "1289637269", "measured": "simulated", "networkFeeLamports": 0, "units": 25294, "ms": 350 } }, "ms": 392 } } } }, "400": { "description": "`BAD_ADDRESS` / `BAD_SIDE` / `BAD_AMOUNT` / `BAD_SLIPPAGE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "`TRADE_BAD_ANSWER`: the Solana box answered something that is not the quote asked for (another mint, side, amount, tolerance or fee payer, or an unknown shape). Nothing is forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`TRADE_NOT_ENABLED` (the lane is off on this deployment, or not open to this caller yet) or `TRADE_UNAVAILABLE` (the Solana box did not answer). Retry later; do not read it as \"no route\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sol/trade/send": { "post": { "tags": [ "Solana swaps" ], "operationId": "solTradeSend", "summary": "Send the signed quote", "description": "Relays a transaction Chord quoted in the last three minutes, signed by the wallet it was quoted for — anything else is refused. Chord sends it to several RPC providers and again every 2 seconds until it lands or its blockhash expires; a `jupiter_meta` order goes through Jupiter's execute endpoint instead (Jupiter or the market maker adds its signature). Then poll `/sol/trade/tx/{signature}`.\n\n**Open to everyone** since 2026-10-15, no key needed (an `X-API-Key` raises the rate limit). `/sol/trade/config` says whether the lane is on for the caller; when it is off the other routes answer `503 TRADE_NOT_ENABLED`.\n\nA quote is SOL against one token, bought or sold. For every quote Chord builds, for **your wallet**, the transaction of each route — `direct` (Chord's own router: Raydium AMM v4 / CPMM / CLMM, Orca Whirlpool, Meteora DLMM / DAMM v2, Meteora DBC, Raydium LaunchLab, pump.fun, PumpSwap; up to two pools), `jupiter` (Jupiter's swap API, no Jupiter fee) and `jupiter_meta` (Jupiter's order: Metis, its RFQ market makers, DFlow, OKX; Jupiter's fee inside the amount) — simulates each on the chain and returns the one that leaves the wallet with the most: tokens for a buy, SOL for a sell, after every fee. Ties go to `direct`, then `jupiter`. A route handing back under half of the input's market value is refused.\n\nAmounts are base units as decimal strings: lamports for SOL, the token's smallest unit otherwise. Addresses are base58, case-sensitive. Chord takes no fee on Solana today. Nothing is signed by Chord: you sign `quote.tx` unchanged and send it back.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tx": { "type": "string", "description": "`quote.tx` signed by the wallet, base64. Do not change the message." } }, "required": [ "tx" ] }, "example": { "tx": "" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "" }, "signature": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{64,88}$", "description": "Transaction signature, base58." }, "status": { "$ref": "#/components/schemas/SolTradeTx" }, "error": { "type": "string", "description": "" }, "message": { "type": "string", "description": "" } } } } } }, "400": { "description": "`BAD_TRANSACTION` (not a transaction, or not base64) · `UNKNOWN_TRANSACTION` (not one a quote handed out in the last three minutes, or changed before signing — ask for a new quote) · `NOT_SIGNED` / `BAD_SIGNATURE` (not signed by the quoted wallet).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "`SEND_FAILED`: no RPC accepted the transaction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`TRADE_NOT_ENABLED` (the lane is off on this deployment, or not open to this caller yet) or `TRADE_UNAVAILABLE` (the Solana box did not answer). Retry later; do not read it as \"no route\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sol/trade/tx/{signature}": { "get": { "tags": [ "Solana swaps" ], "operationId": "solTradeTx", "summary": "Status of a sent swap", "description": "`pending` until the transaction is in a block, then `confirmed` / `finalized` with `receivedOut`, or `failed` / `expired` (its blockhash ran out; an RFQ order unseen for two minutes). Only transactions sent through `/sol/trade/send`.\n\n**Open to everyone** since 2026-10-15, no key needed (an `X-API-Key` raises the rate limit). `/sol/trade/config` says whether the lane is on for the caller; when it is off the other routes answer `503 TRADE_NOT_ENABLED`.\n\nA quote is SOL against one token, bought or sold. For every quote Chord builds, for **your wallet**, the transaction of each route — `direct` (Chord's own router: Raydium AMM v4 / CPMM / CLMM, Orca Whirlpool, Meteora DLMM / DAMM v2, Meteora DBC, Raydium LaunchLab, pump.fun, PumpSwap; up to two pools), `jupiter` (Jupiter's swap API, no Jupiter fee) and `jupiter_meta` (Jupiter's order: Metis, its RFQ market makers, DFlow, OKX; Jupiter's fee inside the amount) — simulates each on the chain and returns the one that leaves the wallet with the most: tokens for a buy, SOL for a sell, after every fee. Ties go to `direct`, then `jupiter`. A route handing back under half of the input's market value is refused.\n\nAmounts are base units as decimal strings: lamports for SOL, the token's smallest unit otherwise. Addresses are base58, case-sensitive. Chord takes no fee on Solana today. Nothing is signed by Chord: you sign `quote.tx` unchanged and send it back.", "parameters": [ { "name": "signature", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{64,88}$", "description": "Transaction signature, base58." }, "description": "From `/sol/trade/send`." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolTradeTx" } } } }, "400": { "description": "`BAD_SIGNATURE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`TX_NOT_FOUND`: not a transaction sent through this API, or done more than 15 minutes ago.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`TRADE_NOT_ENABLED` (the lane is off on this deployment, or not open to this caller yet) or `TRADE_UNAVAILABLE` (the Solana box did not answer). Retry later; do not read it as \"no route\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sol/trade/balances": { "get": { "tags": [ "Solana swaps" ], "operationId": "solTradeBalances", "summary": "A wallet's SOL and one token", "description": "For a swap form: lamports, and the token in the wallet's associated account (`amount`, what a sell spends) and in all its accounts of that mint (`total`).\n\n**Open to everyone** since 2026-10-15, no key needed (an `X-API-Key` raises the rate limit). `/sol/trade/config` says whether the lane is on for the caller; when it is off the other routes answer `503 TRADE_NOT_ENABLED`.\n\nA quote is SOL against one token, bought or sold. For every quote Chord builds, for **your wallet**, the transaction of each route — `direct` (Chord's own router: Raydium AMM v4 / CPMM / CLMM, Orca Whirlpool, Meteora DLMM / DAMM v2, Meteora DBC, Raydium LaunchLab, pump.fun, PumpSwap; up to two pools), `jupiter` (Jupiter's swap API, no Jupiter fee) and `jupiter_meta` (Jupiter's order: Metis, its RFQ market makers, DFlow, OKX; Jupiter's fee inside the amount) — simulates each on the chain and returns the one that leaves the wallet with the most: tokens for a buy, SOL for a sell, after every fee. Ties go to `direct`, then `jupiter`. A route handing back under half of the input's market value is refused.\n\nAmounts are base units as decimal strings: lamports for SOL, the token's smallest unit otherwise. Addresses are base58, case-sensitive. Chord takes no fee on Solana today. Nothing is signed by Chord: you sign `quote.tx` unchanged and send it back.", "parameters": [ { "name": "wallet", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "description": "" }, { "name": "mint", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "mint": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "lamports": { "type": "string", "pattern": "^\\d+$", "description": "Base units as a decimal string (lamports for SOL)." }, "token": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+$", "description": "Base units as a decimal string (lamports for SOL)." }, "total": { "type": "string", "pattern": "^\\d+$", "description": "Base units as a decimal string (lamports for SOL)." }, "decimals": { "type": [ "integer", "null" ], "description": "" } } }, "slot": { "type": "integer", "description": "" } } }, "example": { "wallet": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "mint": "98sMhvDwXj1RQi5c5Mndm3vPe9cBqPrbLaufMXFNMh5g", "lamports": "11175972108683952", "token": { "amount": "0", "total": "0", "decimals": 9 }, "slot": 457371001 } } } }, "400": { "description": "`BAD_ADDRESS`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`TRADE_NOT_ENABLED` (the lane is off on this deployment, or not open to this caller yet) or `TRADE_UNAVAILABLE` (the Solana box did not answer). Retry later; do not read it as \"no route\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sol/trade/holdings": { "get": { "tags": [ "Solana swaps" ], "operationId": "solTradeHoldings", "summary": "A wallet's SOL and tokens", "description": "SOL and every token the wallet holds (both token programs, accounts summed), at most 50 by value; `more` = left out. Name, image and price from Chord's tape (null for a token it never saw).\n\n**Open to everyone** since 2026-10-15, no key needed (an `X-API-Key` raises the rate limit). `/sol/trade/config` says whether the lane is on for the caller; when it is off the other routes answer `503 TRADE_NOT_ENABLED`.\n\nA quote is SOL against one token, bought or sold. For every quote Chord builds, for **your wallet**, the transaction of each route — `direct` (Chord's own router: Raydium AMM v4 / CPMM / CLMM, Orca Whirlpool, Meteora DLMM / DAMM v2, Meteora DBC, Raydium LaunchLab, pump.fun, PumpSwap; up to two pools), `jupiter` (Jupiter's swap API, no Jupiter fee) and `jupiter_meta` (Jupiter's order: Metis, its RFQ market makers, DFlow, OKX; Jupiter's fee inside the amount) — simulates each on the chain and returns the one that leaves the wallet with the most: tokens for a buy, SOL for a sell, after every fee. Ties go to `direct`, then `jupiter`. A route handing back under half of the input's market value is refused.\n\nAmounts are base units as decimal strings: lamports for SOL, the token's smallest unit otherwise. Addresses are base58, case-sensitive. Chord takes no fee on Solana today. Nothing is signed by Chord: you sign `quote.tx` unchanged and send it back.", "parameters": [ { "name": "wallet", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "description": "" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "lamports": { "type": "string", "pattern": "^\\d+$", "description": "Base units as a decimal string (lamports for SOL)." }, "slot": { "type": "integer", "description": "" }, "more": { "type": "integer", "description": "" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Base units as a decimal string (lamports for SOL)." }, "decimals": { "type": [ "integer", "null" ], "description": "" }, "symbol": { "type": [ "string", "null" ], "description": "" }, "name": { "type": [ "string", "null" ], "description": "" }, "image": { "type": [ "string", "null" ], "description": "" }, "priceUsd": { "type": [ "number", "null" ], "description": "" }, "valueUsd": { "type": [ "number", "null" ], "description": "" } } } } } }, "example": { "wallet": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "lamports": "11175972108683952", "slot": 457371002, "more": 3059, "tokens": [ { "mint": "BZLbGTNCSFfoth2GYDtwr7e4imWzpR5jqcUuGEwr646K", "amount": "9110839995100000", "decimals": 8, "symbol": "IO", "name": "IO", "image": "https://bafkreicnqsbhpzxiasdm5esr7fqi3vcjvcbfefo4sq4y3ff747rfqf7w7i.ipfs.nftstorage.link", "priceUsd": 0.16689062068413946, "valueUsd": 15205137.417361211 }, { "mint": "2qEHjDLDLbuBgRYvsxhc5D6uDWAivNFZGan56P1tpump", "amount": "305126997000000", "decimals": 6, "symbol": "Pnut", "name": "Peanut the Squirrel", "image": "https://ipfs.io/ipfs/QmNdTtJauw39u4DzGyTaZ35rRx4VgAxqb91wE89zjyHWd2", "priceUsd": 0.04610248419139405, "valueUsd": 14067112.555560041 } ] } } } }, "400": { "description": "`BAD_ADDRESS`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`TRADE_NOT_ENABLED` (the lane is off on this deployment, or not open to this caller yet) or `TRADE_UNAVAILABLE` (the Solana box did not answer). Retry later; do not read it as \"no route\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/stream/market": { "get": { "tags": [ "Streaming" ], "operationId": "streamMarket", "summary": "Server-sent events: prices", "description": "One `text/event-stream` feed, no key, EventSource-friendly with automatic reconnect. Events: `rh-ticker` (fresh prices for chain 4663, about every 10 s, only addresses whose price moved), `ticker` / `whales` / `defi` (Monad), `ping` every 5 s. Capacity 500 clients (`503` beyond). Arc and Robinhood Chain boards stream faster over the WebSocket `prices` channel — see Concepts → Streaming.", "responses": { "200": { "description": "`text/event-stream`", "content": { "text/event-stream": { "schema": { "type": "string" }, "example": "event: rh-ticker\ndata: {\"items\":[{\"address\":\"0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec\",\"priceUsd\":220.97,\"change24h\":-0.71}]}\n\nevent: ping\ndata: 1789891855\n" } } }, "503": { "description": "At capacity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ws/live": { "get": { "tags": [ "Streaming" ], "operationId": "wsLive", "summary": "WebSocket: live candles, trades and board feeds", "description": "Upgrade to a WebSocket. No key needed, rate-limit exempt, up to 8 channels per connection. With an API key (`X-API-Key`, or `?apiKey=` from a browser) the connection joins a separate pool: up to 64 channels per connection and 20 connections per key (`429` beyond). Subscribe with `{op:\"sub\", channel:\"candles\", token, tf}`, `{op:\"sub\", channel:\"trades\", token}` or `{op:\"sub\", channel:\"prices\", chain}` (chain `5042`, `4663` or `143`); the server pushes `candle`, `trades` and `prices` frames (every print within ~400 ms; on 5042 / 4663 each item also carries the token's live 24h volume and trade counts), `new` frames for tokens trading for the first time (5042 / 4663), `ping` every 25 s, and `error` with a code (`bad_op` · `bad_token` · `bad_tf` · `bad_chain` · `channel_cap`). Full protocol under Concepts → Streaming.", "responses": { "101": { "description": "Switching protocols." }, "429": { "description": "This API key already holds its maximum of live connections.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`WS_LIVE_DISABLED` or at capacity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/backtest": { "get": { "tags": [ "Backtests" ], "operationId": "backtest", "summary": "Backtest a strategy", "description": "One bar-close strategy replayed over stored candles of a Hyperliquid perp or an FX pair / metal. Simulated: nothing is traded.\n\n**Model** (the same text comes back in `assumptions`):\n- A signal is computed on a CLOSED bar and filled at the NEXT bar's open.\n- One position at a time, all-in (equity × `leverage`), long, short or both.\n- `feeBps` is charged per side on notional. Default 4.5 for Hyperliquid, 1 for FX.\n- `stopPct` / `takePct` are checked inside each bar against its high and low. When both could hit in the same bar the stop is taken first; a bar that opens beyond the level fills at its open.\n- A position still open at the last bar is closed at that bar's close (`reason: \"end\"`). Equity at or below zero ends the run.\n- No funding, no spread beyond the fee, no slippage. FX uses Dukascopy BID prices.\n\n**Strategies and their parameters** (pass only the ones you want to change):\n\n| `strategy` | Rule | Parameters (default) |\n| --- | --- | --- |\n| `supertrend` | Long while the Supertrend direction is up, short while it is down. | `atr` (10), `mult` (3) |\n| `ema_cross` | Long while EMA(`fast`) is above EMA(`slow`), short while below. | `fast` (20), `slow` (50) |\n| `rsi` | Long when RSI falls below `lower`, short when it rises above `upper`, flat again when RSI crosses back through 50. | `length` (14), `lower` (30), `upper` (70) |\n| `donchian` | Long on a close above the highest high of the previous `length` bars, short on a close below their lowest low; held until the opposite breakout. | `length` (20) |\n| `buy_hold` | Always long. | none |\n\n**Symbols**: any Hyperliquid perp by its coin id, matched without case (`BTC`, `eth`, `kPEPE`); a leading `$` and a trailing `USDT` / `USD` / `-PERP` are dropped. FX and metals: `EURUSD`, `GBPUSD`, `USDJPY`, `USDCHF`, `AUDUSD`, `USDCAD`, `USDSEK`, `NZDUSD`, `EURJPY`, `GBPJPY`, `EURGBP`, `XAUUSD` (also `gold`), `XAGUSD` (also `silver`).\n\n**How much history there is**: the window is the last `days` ending now, cut to what the store holds. Hyperliquid candles start from what its API served when the store was built (1m a few days, 15m about seven weeks, 1h about seven months, 4h and 1d years) and grow from there; FX has 1h bars since 2016 and 1m bars for about the last 400 days (`/fx/lake` shows how far each symbol is filled). Fewer than 50 bars in the window is a `400` whose message says what the store keeps. Read `from`, `to` and `bars` in the answer for the window that was really tested.", "parameters": [ { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string", "default": "BTC" }, "description": "A Hyperliquid perp coin id or an FX / metal symbol (list above)." }, { "name": "interval", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1m", "5m", "15m", "30m", "1h", "4h", "1d" ], "default": "1h" }, "description": "Bar size. 5m and 30m are resampled from finer stored bars." }, { "name": "strategy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "supertrend", "ema_cross", "rsi", "donchian", "buy_hold" ], "default": "supertrend" }, "description": "" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 3650, "default": 365 }, "description": "Length of the window, ending now." }, { "name": "side", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "long", "short", "both" ], "default": "both" }, "description": "Which signals are traded." }, { "name": "atr", "in": "query", "required": false, "schema": { "type": "number", "default": 10 }, "description": "`supertrend`: ATR length." }, { "name": "mult", "in": "query", "required": false, "schema": { "type": "number", "default": 3 }, "description": "`supertrend`: band width in ATRs." }, { "name": "fast", "in": "query", "required": false, "schema": { "type": "number", "default": 20 }, "description": "`ema_cross`: fast EMA length." }, { "name": "slow", "in": "query", "required": false, "schema": { "type": "number", "default": 50 }, "description": "`ema_cross`: slow EMA length." }, { "name": "length", "in": "query", "required": false, "schema": { "type": "number" }, "description": "`rsi`: RSI length (default 14). `donchian`: channel length in bars (default 20)." }, { "name": "lower", "in": "query", "required": false, "schema": { "type": "number", "default": 30 }, "description": "`rsi`: go long below this." }, { "name": "upper", "in": "query", "required": false, "schema": { "type": "number", "default": 70 }, "description": "`rsi`: go short above this." }, { "name": "feeBps", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "Fee per side in basis points of notional. Default 4.5 (Hyperliquid) or 1 (FX)." }, { "name": "stopPct", "in": "query", "required": false, "schema": { "type": "number", "exclusiveMinimum": 0 }, "description": "Stop-loss, percent from entry. Omitted = none." }, { "name": "takePct", "in": "query", "required": false, "schema": { "type": "number", "exclusiveMinimum": 0 }, "description": "Take-profit, percent from entry. Omitted = none." }, { "name": "leverage", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0.1, "maximum": 20, "default": 1 }, "description": "Position size as a multiple of equity. Values outside 0.1–20 are clamped." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "supertrend", "ema_cross", "rsi", "donchian", "buy_hold" ], "default": "supertrend" }, "params": { "type": "object", "additionalProperties": { "type": "number" }, "description": "The parameters the run used, defaults filled in." }, "side": { "type": "string", "description": "long, short or both." }, "metrics": { "type": "object", "properties": { "totalReturnPct": { "type": "number", "description": "Return of the strategy over the window, after fees." }, "buyHoldPct": { "type": "number", "description": "Return of holding the asset over the same bars." }, "cagrPct": { "type": [ "number", "null" ], "description": "Annualised return. Null when the tested window is shorter than three months, or equity ended at zero." }, "maxDrawdownPct": { "type": "number", "description": "Largest peak-to-trough fall of equity, as a positive number." }, "sharpe": { "type": [ "number", "null" ], "description": "Mean over standard deviation of per-bar returns, annualised by the bar size. Null when equity never moved." }, "trades": { "type": "integer", "description": "Closed trades in the window." }, "winRatePct": { "type": [ "number", "null" ], "description": "Share of trades that made money. Null with no trades." }, "profitFactor": { "type": [ "number", "null" ], "description": "Sum of winning returns over sum of losing returns. Null when nothing lost." }, "avgWinPct": { "type": [ "number", "null" ], "description": "Null with no winning trade." }, "avgLossPct": { "type": [ "number", "null" ], "description": "Negative. Null with no losing trade." }, "exposurePct": { "type": "number", "description": "Share of bars spent in a position." }, "feesPaidPct": { "type": "number", "description": "Sum of the fees charged (each side of each trade, times leverage), in percent." } } }, "equity": { "type": "array", "items": { "type": "object", "properties": { "t": { "type": "integer", "description": "Unix time in MILLISECONDS (every time field of this endpoint is; the rest of the API uses seconds)." }, "equity": { "type": "number", "description": "Strategy equity, starting at 1." }, "hold": { "type": "number", "description": "Buy-and-hold equity, starting at 1." } } }, "description": "The equity curve, thinned to about 300 points." }, "trades": { "type": "array", "items": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "long", "short" ] }, "entryT": { "type": "integer", "description": "Unix time in MILLISECONDS (every time field of this endpoint is; the rest of the API uses seconds)." }, "entry": { "type": "number", "description": "Fill price: the open of the bar after the signal." }, "exitT": { "type": "integer", "description": "Unix time in MILLISECONDS (every time field of this endpoint is; the rest of the API uses seconds)." }, "exit": { "type": "number", "description": "" }, "retPct": { "type": "number", "description": "Return of the trade after both fees, leverage applied." }, "reason": { "type": "string", "enum": [ "signal", "stop", "take", "end" ], "description": "`end` = still open at the last bar, closed there." }, "bars": { "type": "integer", "description": "Bars held." } } }, "description": "The most recent 200 trades, oldest first." }, "symbol": { "type": "string", "description": "The symbol as resolved: the Hyperliquid coin id or the FX symbol." }, "source": { "type": "string", "enum": [ "hyperliquid", "dukascopy" ] }, "interval": { "type": "string", "enum": [ "1m", "5m", "15m", "30m", "1h", "4h", "1d" ], "default": "1h" }, "from": { "type": "integer", "description": "Unix time in MILLISECONDS (every time field of this endpoint is; the rest of the API uses seconds)." }, "to": { "type": "integer", "description": "Unix time in MILLISECONDS (every time field of this endpoint is; the rest of the API uses seconds)." }, "bars": { "type": "integer", "description": "Bars the run used. `from` and `to` are the first and last of them." }, "assumptions": { "type": "string", "description": "The model of this run in one sentence: fill rule, fee, leverage, price source." } } }, "example": { "strategy": "supertrend", "params": { "atr": 10, "mult": 3 }, "side": "both", "metrics": { "totalReturnPct": -29.7396335093976, "buyHoldPct": -24.840856481481477, "cagrPct": -29.77364346765159, "maxDrawdownPct": 43.938798730789316, "sharpe": -0.67928989324471, "trades": 58, "winRatePct": 37.93103448275862, "profitFactor": 0.7686488016790433, "avgWinPct": 4.190301346373836, "avgLossPct": -3.3314820839884187, "exposurePct": 99.58847736625515, "feesPaidPct": 5.2199999999999935 }, "equity": [ { "t": 1760227200000, "equity": 1, "hold": 1.000244140625 }, { "t": 1760342400000, "equity": 1, "hold": 1.0321994357638888 } ], "trades": [ { "side": "long", "entryT": 1760356800000, "entry": 114153, "exitT": 1760601600000, "exit": 110526, "retPct": -3.267314656645025, "reason": "signal", "bars": 17 }, { "side": "short", "entryT": 1760601600000, "entry": 110526, "exitT": 1760947200000, "exit": 111160, "retPct": -0.6636206865353033, "reason": "signal", "bars": 24 } ], "symbol": "BTC", "source": "hyperliquid", "interval": "4h", "from": 1760212800000, "to": 1791705600000, "bars": 2188, "assumptions": "Signal on bar close, fill at next open; 4.5 bps fee per side; Hyperliquid perp candles, no funding; no slippage." } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/fx/lake": { "get": { "tags": [ "Backtests" ], "operationId": "fxLake", "summary": "FX store coverage", "description": "How far the FX / metal candle store behind `/backtest` is filled, per symbol: the last month of 1h bars and the last day of 1m bars. `state` is `running` while a fill pass is in progress.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "off", "running", "idle" ] }, "lastError": { "type": [ "string", "null" ], "description": "" }, "lastAt": { "type": "integer", "description": "Unix ms of the last fill pass, 0 when none ran in this process." }, "files": { "type": "integer", "description": "Files written by the last pass." }, "snapshotAt": { "type": "integer", "description": "Unix time, milliseconds — when the server built this answer." }, "from": { "type": "string", "description": "First month of the 1h store, `YYYY-MM`." }, "minuteDays": { "type": "integer", "description": "How many days back the 1m store reaches." }, "symbols": { "type": "object", "additionalProperties": { "type": "object", "properties": { "hourThrough": { "type": [ "string", "null" ], "description": "Last month with 1h bars, `YYYY-MM`." }, "minuteThrough": { "type": [ "string", "null" ], "description": "Last day with 1m bars, `YYYY-MM-DD`." } } }, "description": "Keyed by symbol." } } }, "example": { "state": "idle", "lastError": null, "lastAt": 0, "files": 0, "snapshotAt": 1791737879748, "from": "2016-01", "minuteDays": 400, "symbols": { "EURUSD": { "hourThrough": "2026-09", "minuteThrough": "2026-10-10" }, "GBPUSD": { "hourThrough": "2026-09", "minuteThrough": "2026-10-10" }, "USDJPY": { "hourThrough": "2026-09", "minuteThrough": "2026-10-10" }, "USDCHF": { "hourThrough": "2026-09", "minuteThrough": "2026-10-10" }, "AUDUSD": { "hourThrough": "2026-09", "minuteThrough": "2026-10-10" }, "USDCAD": { "hourThrough": "2026-09", "minuteThrough": "2026-10-10" }, "USDSEK": { "hourThrough": "2026-09", "minuteThrough": "2026-10-10" }, "NZDUSD": { "hourThrough": "2026-09", "minuteThrough": "2026-10-10" }, "EURJPY": { "hourThrough": "2026-09", "minuteThrough": "2026-10-10" }, "GBPJPY": { "hourThrough": "2026-09", "minuteThrough": "2026-10-10" }, "EURGBP": { "hourThrough": "2026-09", "minuteThrough": "2026-10-10" }, "XAUUSD": { "hourThrough": "2026-09", "minuteThrough": "2026-10-10" }, "XAGUSD": { "hourThrough": "2026-09", "minuteThrough": "2026-10-10" } } } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/me": { "get": { "tags": [ "Account and health" ], "operationId": "me", "summary": "Your key's plan and usage", "description": "The tier, limits and usage (today, this month) behind an API key. Keys are created on getchord.xyz/developer after a Google sign-in.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": [ "string", "null" ], "description": "" }, "tier": { "type": "string", "enum": [ "free", "builder", "pro" ] }, "limits": { "type": "object", "properties": { "rpm": { "type": "integer", "description": "" }, "monthly": { "type": "integer", "description": "" }, "priceUsd": { "type": "number", "description": "" }, "label": { "type": "string", "description": "" } } }, "usage": { "type": "object", "properties": { "today": { "type": "integer", "description": "" }, "month": { "type": "integer", "description": "" } } } } }, "example": { "email": "you@example.com", "tier": "free", "limits": { "rpm": 60, "monthly": 100000, "priceUsd": 0, "label": "Free" }, "usage": { "today": 41, "month": 1209 } } } } }, "401": { "description": "Missing or unknown credential (`UNAUTHORIZED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKey": [] } ] } }, "/chains": { "get": { "tags": [ "Agents and status" ], "operationId": "chainsDirectory", "summary": "Every chain and the route of each capability", "description": "The directory an agent starts from. One entry per chain Chord serves, with its constants (native asset, wrapped native, dollar anchors with real decimals, explorer) and, for each capability, the route that serves it on that chain. A capability the chain does not have is `null`: the data routes grew chain by chain, so this is the one place that says where to read what. Solana is listed with `id: null` and base58, case-sensitive addresses; its `quote` and `swap` are `/sol/trade/quote` and `/sol/trade/send` while its trade lane is open to everyone. A chain that is not public yet appears only for a caller with an API key.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chains": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Chain key, the value every `chain` parameter accepts.", "enum": [ "monad", "robinhood", "arc", "avalanche", "base", "bnb", "arbitrum", "ethereum", "solana" ] }, "id": { "type": [ "integer", "null" ], "description": "EVM chain id; null for Solana." }, "name": { "type": "string", "description": "" }, "short": { "type": "string", "description": "Short label." }, "addressFormat": { "type": "string", "description": "`evm` (0x, case-insensitive) or `base58` (case-sensitive).", "enum": [ "evm", "base58" ] }, "native": { "type": "object", "properties": { "symbol": { "type": "string", "description": "" }, "decimals": { "type": "integer", "description": "" } } }, "wrappedNative": { "type": "string", "description": "The token the native asset is stored under." }, "anchors": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string", "description": "" }, "address": { "type": "string", "description": "" }, "decimals": { "type": "integer", "description": "Read on chain. BNB Chain's dollar stables have 18." }, "stableUsd": { "type": [ "number", "null" ], "description": "1 for a dollar stable; null for a rate anchor." } } } }, "explorer": { "type": "string", "description": "" }, "blockTimeSec": { "type": "number", "description": "Measured average." }, "capabilities": { "type": "object", "properties": { "overview": { "type": [ "object", "null" ], "properties": { "method": { "type": "string", "description": "`GET` or `POST`." }, "path": { "type": "string", "description": "Path under the host, with `{address}` / `{wallet}` placeholders to fill." }, "query": { "type": "object", "additionalProperties": true, "description": "Fixed query values; `{address}` / `{wallet}` / `{q}` inside a value are placeholders too." } }, "description": "The route that serves this capability on this chain, or null when the chain does not have it." }, "tokens": { "type": [ "object", "null" ], "properties": { "method": { "type": "string", "description": "`GET` or `POST`." }, "path": { "type": "string", "description": "Path under the host, with `{address}` / `{wallet}` placeholders to fill." }, "query": { "type": "object", "additionalProperties": true, "description": "Fixed query values; `{address}` / `{wallet}` / `{q}` inside a value are placeholders too." } }, "description": "The route that serves this capability on this chain, or null when the chain does not have it." }, "search": { "type": [ "object", "null" ], "properties": { "method": { "type": "string", "description": "`GET` or `POST`." }, "path": { "type": "string", "description": "Path under the host, with `{address}` / `{wallet}` placeholders to fill." }, "query": { "type": "object", "additionalProperties": true, "description": "Fixed query values; `{address}` / `{wallet}` / `{q}` inside a value are placeholders too." } }, "description": "The route that serves this capability on this chain, or null when the chain does not have it." }, "token": { "type": [ "object", "null" ], "properties": { "method": { "type": "string", "description": "`GET` or `POST`." }, "path": { "type": "string", "description": "Path under the host, with `{address}` / `{wallet}` placeholders to fill." }, "query": { "type": "object", "additionalProperties": true, "description": "Fixed query values; `{address}` / `{wallet}` / `{q}` inside a value are placeholders too." } }, "description": "The route that serves this capability on this chain, or null when the chain does not have it." }, "trades": { "type": [ "object", "null" ], "properties": { "method": { "type": "string", "description": "`GET` or `POST`." }, "path": { "type": "string", "description": "Path under the host, with `{address}` / `{wallet}` placeholders to fill." }, "query": { "type": "object", "additionalProperties": true, "description": "Fixed query values; `{address}` / `{wallet}` / `{q}` inside a value are placeholders too." } }, "description": "The route that serves this capability on this chain, or null when the chain does not have it." }, "candles": { "type": [ "object", "null" ], "properties": { "method": { "type": "string", "description": "`GET` or `POST`." }, "path": { "type": "string", "description": "Path under the host, with `{address}` / `{wallet}` placeholders to fill." }, "query": { "type": "object", "additionalProperties": true, "description": "Fixed query values; `{address}` / `{wallet}` / `{q}` inside a value are placeholders too." } }, "description": "The route that serves this capability on this chain, or null when the chain does not have it." }, "wallet": { "type": [ "object", "null" ], "properties": { "method": { "type": "string", "description": "`GET` or `POST`." }, "path": { "type": "string", "description": "Path under the host, with `{address}` / `{wallet}` placeholders to fill." }, "query": { "type": "object", "additionalProperties": true, "description": "Fixed query values; `{address}` / `{wallet}` / `{q}` inside a value are placeholders too." } }, "description": "The route that serves this capability on this chain, or null when the chain does not have it." }, "walletTrades": { "type": [ "object", "null" ], "properties": { "method": { "type": "string", "description": "`GET` or `POST`." }, "path": { "type": "string", "description": "Path under the host, with `{address}` / `{wallet}` placeholders to fill." }, "query": { "type": "object", "additionalProperties": true, "description": "Fixed query values; `{address}` / `{wallet}` / `{q}` inside a value are placeholders too." } }, "description": "The route that serves this capability on this chain, or null when the chain does not have it." }, "smartMoney": { "type": [ "object", "null" ], "properties": { "method": { "type": "string", "description": "`GET` or `POST`." }, "path": { "type": "string", "description": "Path under the host, with `{address}` / `{wallet}` placeholders to fill." }, "query": { "type": "object", "additionalProperties": true, "description": "Fixed query values; `{address}` / `{wallet}` / `{q}` inside a value are placeholders too." } }, "description": "The route that serves this capability on this chain, or null when the chain does not have it." }, "holders": { "type": [ "object", "null" ], "properties": { "method": { "type": "string", "description": "`GET` or `POST`." }, "path": { "type": "string", "description": "Path under the host, with `{address}` / `{wallet}` placeholders to fill." }, "query": { "type": "object", "additionalProperties": true, "description": "Fixed query values; `{address}` / `{wallet}` / `{q}` inside a value are placeholders too." } }, "description": "The route that serves this capability on this chain, or null when the chain does not have it." }, "lpPools": { "type": [ "object", "null" ], "properties": { "method": { "type": "string", "description": "`GET` or `POST`." }, "path": { "type": "string", "description": "Path under the host, with `{address}` / `{wallet}` placeholders to fill." }, "query": { "type": "object", "additionalProperties": true, "description": "Fixed query values; `{address}` / `{wallet}` / `{q}` inside a value are placeholders too." } }, "description": "The route that serves this capability on this chain, or null when the chain does not have it." }, "lpPositions": { "type": [ "object", "null" ], "properties": { "method": { "type": "string", "description": "`GET` or `POST`." }, "path": { "type": "string", "description": "Path under the host, with `{address}` / `{wallet}` placeholders to fill." }, "query": { "type": "object", "additionalProperties": true, "description": "Fixed query values; `{address}` / `{wallet}` / `{q}` inside a value are placeholders too." } }, "description": "The route that serves this capability on this chain, or null when the chain does not have it." }, "quote": { "type": [ "object", "null" ], "properties": { "method": { "type": "string", "description": "`GET` or `POST`." }, "path": { "type": "string", "description": "Path under the host, with `{address}` / `{wallet}` placeholders to fill." }, "query": { "type": "object", "additionalProperties": true, "description": "Fixed query values; `{address}` / `{wallet}` / `{q}` inside a value are placeholders too." } }, "description": "The route that serves this capability on this chain, or null when the chain does not have it." }, "swap": { "type": [ "object", "null" ], "properties": { "method": { "type": "string", "description": "`GET` or `POST`." }, "path": { "type": "string", "description": "Path under the host, with `{address}` / `{wallet}` placeholders to fill." }, "query": { "type": "object", "additionalProperties": true, "description": "Fixed query values; `{address}` / `{wallet}` / `{q}` inside a value are placeholders too." } }, "description": "The route that serves this capability on this chain, or null when the chain does not have it." } } }, "mcp": { "type": "string", "description": "The hosted MCP endpoint pinned to this chain." } } } }, "capabilities": { "type": "array", "items": { "type": "string", "description": "" }, "description": "Every capability name, in table order." }, "updatedAt": { "type": "string", "description": "ISO time." } } }, "example": { "chains": [ { "key": "arc", "id": 5042, "name": "Arc", "short": "Arc", "addressFormat": "evm", "native": { "symbol": "USDC", "decimals": 18 }, "wrappedNative": "0x3600000000000000000000000000000000000000", "anchors": [ { "symbol": "USDC", "address": "0x3600000000000000000000000000000000000000", "decimals": 6, "stableUsd": 1 } ], "explorer": "https://explorer.arc.io", "blockTimeSec": 0.5, "capabilities": { "search": { "method": "GET", "path": "/v1/tokens/search", "query": { "chain": "5042", "q": "{q}" } }, "candles": { "method": "GET", "path": "/v1/candles", "query": { "chain": "5042", "token": "{address}" } }, "wallet": { "method": "GET", "path": "/v1/portfolio/{wallet}/pnl", "query": { "chain": "5042" } }, "walletTrades": { "method": "GET", "path": "/v1/portfolio/{wallet}/trades", "query": { "chain": "5042" } }, "lpPools": { "method": "GET", "path": "/v1/lp/pools", "query": { "chain": "5042" } }, "lpPositions": { "method": "GET", "path": "/v1/lp/positions", "query": { "chain": "5042", "owner": "{wallet}" } }, "overview": { "method": "GET", "path": "/v1/arc/overview" }, "tokens": { "method": "GET", "path": "/v1/arc/tokens" }, "token": { "method": "GET", "path": "/v1/arc/token/{address}" }, "trades": { "method": "GET", "path": "/v1/arc/token/{address}/trades" }, "smartMoney": { "method": "GET", "path": "/v1/smart-money/top", "query": { "chain": "5042", "source": "onchain" } }, "holders": { "method": "GET", "path": "/v1/arc/token/{address}/holders" }, "quote": { "method": "GET", "path": "/v1/meta/quote", "query": { "chain": "5042" } }, "swap": { "method": "POST", "path": "/v1/meta/swap" } }, "mcp": "https://api.getchord.xyz/v1/mcp?chain=arc" }, { "key": "base", "id": 8453, "name": "Base", "short": "Base", "addressFormat": "evm", "native": { "symbol": "ETH", "decimals": 18 }, "wrappedNative": "0x4200000000000000000000000000000000000006", "anchors": [ { "symbol": "WETH", "address": "0x4200000000000000000000000000000000000006", "decimals": 18, "stableUsd": null }, { "symbol": "USDC", "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "decimals": 6, "stableUsd": 1 } ], "explorer": "https://basescan.org", "blockTimeSec": 2, "capabilities": { "overview": { "method": "GET", "path": "/v1/chains/base/overview" }, "tokens": { "method": "GET", "path": "/v1/chains/base/tokens" }, "search": { "method": "GET", "path": "/v1/tokens/search", "query": { "chain": "8453", "q": "{q}" } }, "token": { "method": "GET", "path": "/v1/chains/base/token/{address}" }, "trades": { "method": "GET", "path": "/v1/chains/base/token/{address}/trades" }, "candles": { "method": "GET", "path": "/v1/candles", "query": { "chain": "8453", "token": "{address}" } }, "wallet": { "method": "GET", "path": "/v1/chains/base/wallet/{wallet}" }, "walletTrades": null, "smartMoney": null, "holders": null, "lpPools": null, "lpPositions": null, "quote": { "method": "GET", "path": "/v1/meta/quote", "query": { "chain": "8453" } }, "swap": { "method": "POST", "path": "/v1/meta/swap" } }, "mcp": "https://api.getchord.xyz/v1/mcp?chain=base" } ], "capabilities": [ "overview", "tokens", "search", "token", "trades", "candles", "wallet", "walletTrades", "smartMoney", "holders", "lpPools", "lpPositions", "quote", "swap" ], "updatedAt": "2026-10-11T17:33:08.447Z" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/health/chains": { "get": { "tags": [ "Agents and status" ], "operationId": "chainHealth", "summary": "Health of every chain, one generic row each", "description": "What the status page is built from, readable directly. `quotes.engine` is the routing engine's own state (`ok`, `starting` after a deploy, `stale` when its pool sync stopped, `down`); `quotes.canary` is the small quote the status probe sends. `data.ageSec` is how old the newest indexed trade is and `data.maxAgeSec` the age past which the chain's data counts as delayed. `quotes` is null where Chord does not route (Solana), `data` is null where no tape runs. Answers from a 15-second memo.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "at": { "type": "string", "description": "ISO time the rows were read." }, "chains": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "", "enum": [ "monad", "robinhood", "arc", "avalanche", "base", "bnb", "arbitrum", "ethereum", "solana" ] }, "id": { "type": [ "integer", "null" ], "description": "" }, "name": { "type": "string", "description": "" }, "quotes": { "type": [ "object", "null" ], "properties": { "engine": { "type": "string", "description": "" }, "latencyMs": { "type": [ "integer", "null" ], "description": "Round trip from the API to the engine." }, "lastSyncBlock": { "type": [ "integer", "null" ], "description": "" }, "canary": { "type": [ "object", "null" ], "properties": { "inputMint": { "type": "string", "description": "" }, "outputMint": { "type": "string", "description": "" }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." } }, "description": "10 units of the chain's first dollar stable into its wrapped native (Arc: into EURC)." } } }, "data": { "type": [ "object", "null" ], "properties": { "ageSec": { "type": [ "integer", "null" ], "description": "Null = the age could not be read." }, "maxAgeSec": { "type": "integer", "description": "" } } } } } } } }, "example": { "at": "2026-10-11T17:33:02.088Z", "chains": [ { "key": "monad", "id": 143, "name": "Monad", "quotes": { "engine": "ok", "latencyMs": 4, "lastSyncBlock": 112529162, "canary": { "inputMint": "0x754704bc059f8c67012fed69bc8a327a5aafb603", "outputMint": "0x3bd359c1119da7da1d913d1c4d2b7c461115433a", "amount": "10000000" } }, "data": { "ageSec": 10, "maxAgeSec": 600 } }, { "key": "robinhood", "id": 4663, "name": "Robinhood Chain", "quotes": { "engine": "ok", "latencyMs": 5, "lastSyncBlock": 86010669, "canary": { "inputMint": "0x5fc5360d0400a0fd4f2af552add042d716f1d168", "outputMint": "0x0bd7d308f8e1639fab988df18a8011f41eacad73", "amount": "10000000" } }, "data": { "ageSec": 4, "maxAgeSec": 2700 } } ] } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/status": { "get": { "tags": [ "Agents and status" ], "operationId": "statusSummary", "summary": "Uptime history, measured from outside Chord's servers", "description": "Served by Cloudflare, not by the API's own servers, so it answers while they do not. A probe runs every minute: it reads `GET /health/chains` and requests one small quote per chain down the public path. Components are `api`, `quotes:` and `data:`. Uptime is the share of SAMPLED minutes that were not down; `sampledMin` says how many minutes each window really holds, and a day with no samples has `level: null`: it is never counted as up. An incident opens on the second bad check in a row and closes on the second good one. The same data as a page: https://getchord.xyz/status", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "at": { "type": "string", "description": "ISO time." }, "overall": { "type": "string", "description": "", "enum": [ "operational", "degraded", "outage", "unknown" ] }, "lastProbeAgeSec": { "type": [ "integer", "null" ], "description": "Seconds since the last probe. Above about 180 every status reads `unknown`." }, "since": { "type": [ "string", "null" ], "description": "First UTC day with a sample." }, "probe": { "type": "object", "properties": { "from": { "type": "string", "description": "" }, "everySec": { "type": "integer", "description": "" }, "openAfterMin": { "type": "integer", "description": "" } } }, "components": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "`api`, `quotes:` or `data:`." }, "group": { "type": "string", "description": "", "enum": [ "api", "quotes", "data" ] }, "chain": { "type": [ "string", "null" ], "description": "" }, "name": { "type": "string", "description": "" }, "status": { "type": "string", "description": "", "enum": [ "operational", "degraded", "down", "unknown" ] }, "note": { "type": [ "string", "null" ], "description": "Why it is not operational." }, "ms": { "type": [ "integer", "null" ], "description": "Last probe: the API call, or the canary quote, in milliseconds. Null for data components." }, "ageSec": { "type": [ "integer", "null" ], "description": "Data components: seconds behind the chain." }, "uptime": { "type": "object", "properties": { "h24": { "type": [ "number", "null" ], "description": "" }, "d7": { "type": [ "number", "null" ], "description": "" }, "d30": { "type": [ "number", "null" ], "description": "" }, "d90": { "type": [ "number", "null" ], "description": "" } }, "description": "Percent of sampled minutes not down. Null = nothing sampled." }, "sampledMin": { "type": "object", "properties": { "h24": { "type": "integer", "description": "" }, "d7": { "type": "integer", "description": "" }, "d30": { "type": "integer", "description": "" }, "d90": { "type": "integer", "description": "" } }, "description": "Minutes actually sampled in each window." }, "avgMs30d": { "type": [ "integer", "null" ], "description": "" }, "days": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "description": "UTC day." }, "level": { "type": [ "integer", "null" ], "description": "Worst level that day: 0 down, 1 degraded, 2 operational; null = no samples." }, "downMin": { "type": "integer", "description": "" }, "degMin": { "type": "integer", "description": "" }, "sampled": { "type": "integer", "description": "" } } }, "description": "Oldest first, 90 entries." } } } }, "incidents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Component id." }, "name": { "type": "string", "description": "" }, "group": { "type": "string", "description": "" }, "start": { "type": "string", "description": "ISO." }, "end": { "type": [ "string", "null" ], "description": "ISO; null while open." }, "minutes": { "type": "integer", "description": "" }, "worst": { "type": "string", "description": "" }, "note": { "type": [ "string", "null" ], "description": "" } } }, "description": "Newest first, last 30 days." } } }, "example": { "at": "2026-10-11T17:33:09.133Z", "overall": "operational", "lastProbeAgeSec": 9, "since": "2026-10-11", "probe": { "from": "Cloudflare edge", "everySec": 60, "openAfterMin": 2 }, "incidents": [], "components": [ { "id": "api", "group": "api", "chain": null, "name": "API", "status": "operational", "note": null, "ms": 58, "ageSec": null, "uptime": { "h24": 100, "d7": 100, "d30": 100, "d90": 100 }, "sampledMin": { "h24": 9, "d7": 9, "d30": 9, "d90": 9 }, "avgMs30d": 119, "days": [ { "day": "2026-07-14", "level": null, "downMin": 0, "degMin": 0, "sampled": 0 }, { "day": "2026-07-15", "level": null, "downMin": 0, "degMin": 0, "sampled": 0 } ] }, { "id": "quotes:arc", "group": "quotes", "chain": "arc", "name": "Arc", "status": "operational", "note": null, "ms": 697, "ageSec": null, "uptime": { "h24": 100, "d7": 100, "d30": 100, "d90": 100 }, "sampledMin": { "h24": 9, "d7": 9, "d30": 9, "d90": 9 }, "avgMs30d": 683, "days": [ { "day": "2026-07-14", "level": null, "downMin": 0, "degMin": 0, "sampled": 0 }, { "day": "2026-07-15", "level": null, "downMin": 0, "degMin": 0, "sampled": 0 } ] }, { "id": "data:arc", "group": "data", "chain": "arc", "name": "Arc", "status": "operational", "note": null, "ms": null, "ageSec": 2, "uptime": { "h24": 100, "d7": 100, "d30": 100, "d90": 100 }, "sampledMin": { "h24": 9, "d7": 9, "d30": 9, "d90": 9 }, "avgMs30d": null, "days": [ { "day": "2026-07-14", "level": null, "downMin": 0, "degMin": 0, "sampled": 0 }, { "day": "2026-07-15", "level": null, "downMin": 0, "degMin": 0, "sampled": 0 } ] } ] } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/stats": { "get": { "tags": [ "Agents and status" ], "operationId": "agentStats", "summary": "Agent traffic per chain", "description": "How much programmatic traffic a chain sees through Chord, by the surface it came through: `mcp` (the hosted MCP), `api` (an API key), `x402` and `wallet` (not live yet), `anon` (keyless scripts), and `web` (people in Chord's own app; their board reads are not counted). `agents` adds up everything that is not `web`. Counts are requests answered 2xx; `swapTx` is swap transactions BUILT; what executed is under `onchain`, read from the router's events on each chain. `callers` is distinct callers over the window. `since` is the first day with any count: the counters started on 2026-10-11, earlier days are unknown, not zero.", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "description": "", "enum": [ "all", "monad", "robinhood", "arc", "avalanche", "base", "bnb", "arbitrum", "ethereum", "solana" ] }, "description": "A chain key or id, or `all` (every chain plus chain-free calls such as Ask). Default `all`." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 }, "description": "Window in UTC days, today included." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "description": "" }, "days": { "type": "integer", "description": "" }, "from": { "type": "string", "description": "UTC day." }, "to": { "type": "string", "description": "UTC day." }, "agents": { "$ref": "#/components/schemas/AgentCounts" }, "web": { "$ref": "#/components/schemas/AgentCounts" }, "bySource": { "type": "object", "properties": { "mcp": { "$ref": "#/components/schemas/AgentCounts" }, "x402": { "$ref": "#/components/schemas/AgentCounts" }, "wallet": { "$ref": "#/components/schemas/AgentCounts" }, "api": { "$ref": "#/components/schemas/AgentCounts" }, "anon": { "$ref": "#/components/schemas/AgentCounts" }, "web": { "$ref": "#/components/schemas/AgentCounts" } } }, "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "description": "" }, "calls": { "type": "integer", "description": "" }, "reads": { "type": "integer", "description": "" }, "quotes": { "type": "integer", "description": "" }, "swapTx": { "type": "integer", "description": "" }, "asks": { "type": "integer", "description": "" } } }, "description": "Oldest first; programmatic callers only." }, "since": { "type": [ "string", "null" ], "description": "" }, "onchain": { "type": [ "object", "null" ], "properties": { "swaps": { "type": "integer", "description": "Swaps executed through Chord's router in the window, from the router's own `Swap` events." }, "wallets": { "type": "integer", "description": "Distinct `sender` addresses. A swap relayed by another contract has that contract as sender." }, "volumeUsd": { "type": "number", "description": "USD of the swaps that have a dollar-stable leg (that leg's own amount)." }, "unpriced": { "type": "integer", "description": "Swaps with no stable leg: counted in `swaps`, not in `volumeUsd`. Never estimated." }, "bySource": { "type": "object", "additionalProperties": true, "description": "Swaps whose transaction was built through a known surface in the two hours before it landed, by surface. The rest are unlabelled." }, "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "description": "" }, "swaps": { "type": "integer", "description": "" }, "volumeUsd": { "type": "number", "description": "" } } }, "description": "Oldest first." }, "coverage": { "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "integer", "description": "" }, "fromBlock": { "type": [ "integer", "null" ], "description": "First block this record covers. Swaps before it are not known, not zero." }, "cursor": { "type": [ "integer", "null" ], "description": "Last block read." } } } } }, "description": "What actually executed on chain. Null for Solana (Chord has no router there) and when the record cannot be read." }, "updatedAt": { "type": "string", "description": "ISO time." } } }, "example": { "chain": "arc", "days": 7, "from": "2026-10-05", "to": "2026-10-11", "agents": { "calls": 9, "reads": 7, "quotes": 2, "swapTx": 0, "asks": 0, "callers": 2 }, "web": { "calls": 0, "reads": 0, "quotes": 0, "swapTx": 0, "asks": 0, "callers": 0 }, "bySource": { "mcp": { "calls": 6, "reads": 6, "quotes": 0, "swapTx": 0, "asks": 0, "callers": 1 }, "x402": { "calls": 0, "reads": 0, "quotes": 0, "swapTx": 0, "asks": 0, "callers": 0 }, "wallet": { "calls": 0, "reads": 0, "quotes": 0, "swapTx": 0, "asks": 0, "callers": 0 }, "api": { "calls": 1, "reads": 1, "quotes": 0, "swapTx": 0, "asks": 0, "callers": 1 }, "anon": { "calls": 2, "reads": 0, "quotes": 2, "swapTx": 0, "asks": 0, "callers": 1 }, "web": { "calls": 0, "reads": 0, "quotes": 0, "swapTx": 0, "asks": 0, "callers": 0 } }, "daily": [ { "day": "2026-10-05", "calls": 0, "reads": 0, "quotes": 0, "swapTx": 0, "asks": 0 }, { "day": "2026-10-06", "calls": 0, "reads": 0, "quotes": 0, "swapTx": 0, "asks": 0 } ], "since": "2026-10-11", "onchain": { "swaps": 1, "wallets": 1, "volumeUsd": 190, "unpriced": 0, "bySource": {}, "daily": [ { "day": "2026-10-05", "swaps": 0, "volumeUsd": 0 }, { "day": "2026-10-06", "swaps": 0, "volumeUsd": 0 } ], "coverage": [ { "chain": 5042, "fromBlock": 20268312, "cursor": 25453341 } ] }, "updatedAt": "2026-10-11T18:22:55.946Z" } } } }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mcp": { "post": { "tags": [ "Agents and status" ], "operationId": "mcp", "summary": "Hosted MCP server", "description": "Model Context Protocol over stateless Streamable HTTP: POST one JSON-RPC message (or a batch of up to 20), get JSON back. Methods: `initialize`, `ping`, `tools/list`, `tools/call`. 17 tools; every data tool takes a `chain`. `?chain=` pins a default chain and names the server `chord-`. The handshake and the tool list need no credentials and are not metered; a tool call is an ordinary request to this API made as the caller, so it is limited and metered exactly like the REST call it wraps. Send a key as `X-API-Key`, `Authorization: Bearer`, or `?apiKey=`. A tool-level failure is a normal result with `isError: true` and a sentence the model can act on. Guide: https://getchord.xyz/docs/agents/mcp/", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "description": "", "enum": [ "monad", "robinhood", "arc", "avalanche", "base", "bnb", "arbitrum", "ethereum", "solana" ] }, "description": "Default chain for this endpoint." }, { "name": "apiKey", "in": "query", "required": false, "schema": { "type": "string", "description": "" }, "description": "Your key, for connectors that cannot set a header." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "A JSON-RPC 2.0 message, or an array of them." }, "example": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "chord_search", "arguments": { "query": "EURC" } } } } } }, "responses": { "200": { "description": "The JSON-RPC response. A tool result carries one text block: `{chain, route, data}` as JSON.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "JSON-RPC 2.0 response." }, "example": { "jsonrpc": "2.0", "id": 1, "result": { "content": [ { "type": "text", "text": "{\"chain\":\"arc\",\"route\":\"GET /v1/tokens/search\",\"data\":{\"chain\":5042,\"q\":\"EURC\",\"tokens\":[{\"address\":\"0xbef5f6d51cb62b58e6a8f77868681825c6fe21c1\",\"symbol\":\"EURC\",\"name\":\"Euro Coin\",\"decimals\":6,\"logoURI\":\"https://assets.coingecko.com/coins/images/26045/small/euro.png\",\"verified\":true}]}}" } ] } } } } }, "202": { "description": "A notification: nothing to answer." }, "400": { "description": "Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mcp/tools.json": { "get": { "tags": [ "Agents and status" ], "operationId": "mcpTools", "summary": "The MCP tools as a function-calling manifest", "description": "The same tool list as OpenAI-style function definitions, for frameworks that take a manifest instead of speaking MCP. Always current: it is printed from the list the MCP server serves.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "" }, "version": { "type": "string", "description": "" }, "base_url": { "type": "string", "description": "" }, "mcp": { "type": "string", "description": "The hosted MCP endpoint." }, "auth": { "type": "object", "properties": { "header": { "type": "string", "description": "" }, "required": { "type": "boolean", "description": "" } } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "" }, "function": { "type": "object", "properties": { "name": { "type": "string", "description": "" }, "description": { "type": "string", "description": "" }, "parameters": { "type": "object", "additionalProperties": true, "description": "JSON Schema of the arguments." } } } } } } } }, "example": { "name": "chord", "version": "1.0.0", "base_url": "https://api.getchord.xyz", "mcp": "https://api.getchord.xyz/v1/mcp", "auth": { "header": "X-API-Key", "required": false }, "tools": [ { "type": "function", "function": { "name": "chord_chains", "description": "The chains Chord serves, with their native asset, anchors and which capabilities each one has (overview, tokens, trades, candles, wallet PnL, smart money, holders, LP, quote, swap). Call this first when unsure what a chain supports.", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "chord_status", "description": "Live health of every chain: routing engine state, how old the newest indexed trade is, and the public status page link.", "parameters": { "type": "object", "properties": {} } } } ] } } } } } } }, "/health": { "get": { "tags": [ "Account and health" ], "operationId": "health", "summary": "Service health", "description": "Engine, cache and pool-sync state. `503` when the routing engine is unreachable.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "" }, "version": { "type": "string", "description": "" }, "uptime": { "type": "number", "description": "Seconds." }, "engine": { "type": "object", "properties": { "status": { "type": "string", "description": "" }, "latencyMs": { "type": "integer", "description": "" } } }, "redis": { "type": "object", "properties": { "status": { "type": "string", "description": "" } } }, "poolCount": { "type": "integer", "description": "" }, "lastSyncBlock": { "type": "integer", "description": "" } } }, "example": { "status": "ok", "version": "0.1.0", "uptime": 494.311362193, "engine": { "status": "ok", "latencyMs": 1 }, "redis": { "status": "ok" }, "poolCount": 1649, "lastSyncBlock": 106412042 } } } }, "503": { "description": "The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Optional on every read. A key from getchord.xyz/developer raises the rate limit to your plan and meters usage per key. Required for `?only=` on quotes and for the Ask agent API." }, "Session": { "type": "http", "scheme": "bearer", "description": "A Google sign-in session minted by the app (`nts_…`). Only the browser surfaces use it; agents use `ApiKey`." } }, "schemas": { "AgentCounts": { "type": "object", "properties": { "calls": { "type": "integer", "description": "Requests answered 2xx." }, "reads": { "type": "integer", "description": "" }, "quotes": { "type": "integer", "description": "" }, "swapTx": { "type": "integer", "description": "Swap transactions built, not executed." }, "asks": { "type": "integer", "description": "Questions to the analyst." }, "callers": { "type": "integer", "description": "Distinct callers in the window." } }, "description": "Counts for one surface or a sum of surfaces." }, "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine code, e.g. `INVALID_PARAMS`, `NOT_READY`, `RATE_LIMIT_EXCEEDED`." }, "message": { "type": "string", "description": "For humans." }, "statusCode": { "type": "integer", "description": "HTTP status, when included." } }, "description": "Every non-2xx body.", "required": [ "error" ], "example": { "error": "INVALID_PARAMS", "message": "amount must be an integer string in the token's smallest unit" } }, "Coverage": { "type": "object", "properties": { "recentAt": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "stale": { "type": "boolean", "description": "True when the most recent rolled-up hour is older than the lane's freshness bar." }, "floorHour": { "type": [ "integer", "null" ], "description": "Oldest hour the rollup has reached so far." }, "genesisHour": { "type": [ "integer", "null" ], "description": "The chain's first indexed hour." }, "backfillComplete": { "type": "boolean", "description": "True once the rollup reaches genesis — before that, long windows undercount." } }, "description": "How fresh and how deep the rolled-up data is. Trust these flags, not the clock." }, "TokenLite": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "symbol": { "type": [ "string", "null" ], "description": "Symbol from the contract, or null while unresolved." }, "decimals": { "type": [ "integer", "null" ], "description": "ERC-20 decimals." }, "logo": { "type": [ "string", "null" ], "description": "Logo URL, or null." }, "impostor": { "type": "boolean", "description": "True when the symbol copies the chain's anchor (a token called USDC that is not the USDC predeploy). Flagged, never hidden." } }, "description": "A token as it appears inside a pool row." }, "ArcTokenRow": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "symbol": { "type": [ "string", "null" ], "description": "" }, "name": { "type": [ "string", "null" ], "description": "" }, "decimals": { "type": [ "integer", "null" ], "description": "" }, "logoURI": { "type": [ "string", "null" ], "description": "Logo through Chord's proxy (`/v1/logo/5042/{address}`, 128 px WebP)." }, "logoUriRaw": { "type": [ "string", "null" ], "description": "The upstream logo URL the proxy fetched, when there is one." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "`stablecoin`, `fx`, `stock`, … — from the curated list; empty for unlisted tokens." }, "listed": { "type": "boolean", "description": "On the curated Arc token list (metadata and logo vetted)." }, "priceUsd": { "type": [ "number", "null" ], "description": "Last trade price on the token's dominant venue, USD." }, "change24hPct": { "type": [ "number", "null" ], "description": "" }, "volume24h": { "type": "number", "description": "USD, every venue, no dust floor." }, "buyVolume24h": { "type": "number", "description": "" }, "sellVolume24h": { "type": "number", "description": "" }, "trades24h": { "type": "integer", "description": "" }, "buys24h": { "type": "integer", "description": "" }, "sells24h": { "type": "integer", "description": "" }, "traders": { "type": "integer", "description": "Distinct attributed wallets over the board's day window. Routers, executors and bots are not wallets." }, "lastTradeTs": { "type": "integer", "description": "Unix time, seconds, UTC." }, "totalSupply": { "type": [ "number", "null" ], "description": "`totalSupply()` in whole tokens. Null when unreadable." }, "marketCapUsd": { "type": [ "number", "null" ], "description": "totalSupply × price — fully diluted, since nothing on-chain says what is locked." }, "pools": { "type": "object", "properties": { "v3": { "type": "integer", "description": "" }, "v2": { "type": "integer", "description": "" }, "v4": { "type": "integer", "description": "" }, "byDex": { "type": "object", "properties": {}, "description": "Pool count per venue id (`uniswap_v3`, `uniswap_v4`, `pools_trade`, `slipstream_fork`, `v3fork_<8hex>`, …).", "additionalProperties": { "type": "integer" } } }, "description": "Indexed pools holding the token." }, "routable": { "type": "boolean", "description": "The engine can quote this token today (at least one pool against a routing anchor)." }, "flags": { "type": "array", "items": { "type": "string", "enum": [ "wash", "impostor" ] }, "description": "Honesty flags. `wash` = a day's volume carried by one or two wallets; `impostor` = an unlisted token wearing a listed symbol. Absent when clean." } }, "description": "One token on Arc with its 24-hour tape." }, "ArcTrendingRow": { "allOf": [ { "$ref": "#/components/schemas/ArcTokenRow" }, { "type": "object", "properties": { "score": { "type": "number", "description": "Trending score (higher = hotter)." }, "volNow": { "type": "number", "description": "USD in the 2-hour window." }, "tradesNow": { "type": "integer", "description": "" }, "change1hPct": { "type": [ "number", "null" ], "description": "" }, "momentum": { "type": [ "number", "null" ], "description": "" } } } ] }, "ArcGraduatedRow": { "allOf": [ { "$ref": "#/components/schemas/ArcTokenRow" }, { "type": "object", "properties": { "launchedAt": { "type": "integer", "description": "Unix time, seconds, UTC." }, "launcher": { "type": "string", "description": "Contract the creating transaction called (`create` = a raw deploy)." }, "launcherName": { "type": [ "string", "null" ], "description": "Name from the launcher registry, when known." }, "creator": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "ageSec": { "type": "integer", "description": "" } } } ] }, "RhTokenRow": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "symbol": { "type": "string", "description": "" }, "name": { "type": "string", "description": "" }, "decimals": { "type": "integer", "description": "" }, "logoURI": { "type": [ "string", "null" ], "description": "" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "`stock`, `bridged`, `stablecoin`, …" }, "listed": { "type": "boolean", "description": "" }, "priceUsd": { "type": [ "number", "null" ], "description": "" }, "change24hPct": { "type": [ "number", "null" ], "description": "" }, "liquidityUsd": { "type": [ "number", "null" ], "description": "" }, "volume24h": { "type": "number", "description": "" }, "buyVolume24h": { "type": "number", "description": "" }, "sellVolume24h": { "type": "number", "description": "" }, "trades24h": { "type": "integer", "description": "" }, "buys24h": { "type": "integer", "description": "" }, "sells24h": { "type": "integer", "description": "" }, "traders": { "type": "integer", "description": "Attributed wallets only." }, "lastTradeTs": { "type": "integer", "description": "Unix time, seconds, UTC." } }, "description": "One token on Robinhood Chain with its 24-hour tape." }, "RhStockRow": { "allOf": [ { "$ref": "#/components/schemas/RhTokenRow" }, { "type": "object", "properties": { "navUsd": { "type": [ "number", "null" ], "description": "The issuer's published exchange rate at last refresh; null when none is published." }, "basisPct": { "type": [ "number", "null" ], "description": "On-chain price versus NAV, percent." }, "offHours7d": { "type": "object", "properties": { "volUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "sharePct": { "type": "number", "description": "" } }, "description": "Activity outside the NYSE regular session (09:30–16:00 New York, weekdays) over the last seven days." } } } ] }, "RouteLeg": { "type": "object", "properties": { "percent": { "type": "integer", "description": "Share of the input this leg carries." }, "swapInfo": { "type": "object", "properties": { "dex": { "type": "string", "description": "Venue id (see Resources → Venue ids)." }, "pool": { "type": "string", "description": "Pool address, or the 32-byte pool id on Uniswap V4." }, "inputMint": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "outputMint": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "inputAmount": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "outputAmount": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "adapter": { "type": "string", "description": "The router adapter that executes this leg — from the engine, never hardcode." }, "extraData": { "type": "string", "description": "Adapter-specific calldata for the leg." }, "feeAmount": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "feeMint": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." } } } }, "description": "One leg of the route." }, "QuoteResponse": { "type": "object", "properties": { "inputMint": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "outputMint": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "inputAmount": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "outputAmount": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "otherAmountThreshold": { "type": "string", "pattern": "^\\d+$", "description": "Minimum output after fee and slippage — the number the transaction enforces." }, "slippageBps": { "type": "integer", "description": "" }, "priceImpactPct": { "type": "string", "description": "Percent, as a string, against the spot rate of the same route." }, "routePlan": { "type": "array", "items": { "$ref": "#/components/schemas/RouteLeg" }, "description": "Empty with `outputAmount` \"0\" = no route (an honest answer, never a fabricated price)." }, "noRouteReason": { "type": "string", "description": "Only when `routePlan` is empty: `INSUFFICIENT_LIQUIDITY` (try a smaller amount) or `NO_POOLS`." }, "gasEstimate": { "type": "string", "description": "Gas units, from the venue quoter or the RPC." }, "gasCostUSD": { "type": "string", "description": "" }, "blockNumber": { "type": "integer", "description": "" }, "timeTaken": { "type": "number", "description": "Engine seconds." }, "feeBps": { "type": "integer", "description": "Protocol fee on the output token, per token on-chain (`FeeCollector.feeBpsFor`): 5 bps by default on every chain, 0 on the stablecoins and majors a chain exempts (USDC / EURC on Arc, WETH / USDG and stocks on Robinhood Chain), capped at 100." }, "feeAmount": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "feeMint": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "feeTier": { "type": "string", "description": "`major` · `stable` · `standard` · `meme` · `new`." }, "preliminary": { "type": "boolean", "description": "Present only on `fast=1` answers: single-hop, ~400 ms, replace it with the full quote." } } }, "SwapTx": { "type": "object", "properties": { "to": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "data": { "type": "string", "description": "Calldata." }, "value": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "gasLimit": { "type": "string", "description": "" }, "chainId": { "type": "integer", "description": "" } }, "description": "Unsigned transaction against the router." }, "MetaAttempt": { "type": "object", "properties": { "provider": { "type": "string", "description": "`chord`, `kyberswap`, `monorail`, `lifi` or `relay`." }, "status": { "type": "string", "description": "`ok`, or why this provider did not produce the answer: `no_route`, `timeout`, `http_error`, `rate_limited`, `invalid_response`, `not_allowlisted`, `calldata_mismatch`, `min_out_too_low`, `value_gap`, `unsafe_token`, `simulation_failed`, `unverified`, `breaker_open`, `skipped`; for Chord also `engine_error`, `engine_timeout`, `engine_down`, `route_refused`, `build_failed`, `chain_not_live`." }, "ms": { "type": "integer", "description": "Time spent on this provider." }, "error": { "type": [ "string", "null" ], "description": "Short reason from a fixed vocabulary, never provider text." } }, "description": "One provider that was asked, in order." }, "MetaQuote": { "type": "object", "properties": { "chain": { "type": "integer", "description": "Chain id." }, "tokenIn": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenOut": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amountIn": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "taker": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "The wallet the transaction was built and simulated for; null on a price-only quote." }, "slippageBps": { "type": "integer", "description": "The slippage `minAmountOut` reflects." }, "provider": { "type": [ "string", "null" ], "description": "Who answered: `chord` (Chord's own router), `kyberswap`, `monorail`, `lifi`, `relay`. `null` = no provider has a route." }, "fallbackReason": { "type": [ "string", "null" ], "description": "`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`." }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/MetaAttempt" }, "description": "Every provider asked, in order." }, "amountOut": { "type": "string", "pattern": "^\\d+$", "description": "What the taker receives after every fee, smallest unit of `tokenOut`. (`/quote`'s `outputAmount` is before Chord's fee; this is after.)" }, "minAmountOut": { "type": "string", "pattern": "^\\d+$", "description": "The minimum the transaction enforces, from the slippage you asked for." }, "priceImpactPct": { "type": [ "string", "null" ], "description": "Percent, when the provider states one." }, "valueLossPct": { "type": [ "number", "null" ], "description": "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`." }, "feeBps": { "type": "integer", "description": "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`." }, "feeRecipient": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "route": { "type": "object", "properties": { "venues": { "type": "array", "items": { "type": "string", "description": "" }, "description": "Venue names." } } }, "tx": { "type": [ "object", "null" ], "properties": { "to": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "data": { "type": "string", "description": "Calldata." }, "value": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "gas": { "type": [ "string", "null" ], "description": "Gas limit to sign with." }, "chainId": { "type": "integer", "description": "" } }, "description": "The UNSIGNED transaction. `null` without `taker`. `to` is the Chord router when `provider` is `chord`, the provider's own router otherwise." }, "approval": { "type": [ "object", "null" ], "properties": { "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "spender": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "resetFirst": { "type": "boolean", "description": "Present only for a token that reverts `approve(x > 0)` while its allowance is non-zero (USDT on Ethereum). `true` = the taker has a left-over allowance: send `approve(spender, 0)` first, then this approval." } }, "description": "The approval to send first. `null` for a native input or when the taker's allowance already covers the amount." }, "simulation": { "type": [ "object", "null" ], "properties": { "ok": { "type": [ "boolean", "null" ], "description": "`true` = ran and delivered at least `minAmountOut`; `null` = no verdict (only ever returned on the Chord path)." }, "amountOut": { "type": "string", "pattern": "^\\d+$", "description": "Amount in the token's smallest unit, as a decimal string. Never a float." }, "gasUsed": { "type": "integer", "description": "" }, "revert": { "type": "string", "description": "" }, "reason": { "type": "string", "description": "" } }, "description": "The transaction run as the taker (with the input supplied when the taker does not hold it), measuring the taker's own balance change. `null` without `taker`." }, "safety": { "type": [ "object", "null" ], "properties": { "source": { "type": "string", "description": "`goplus`" }, "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "worstFlag": { "type": "string", "description": "`none`, `low`, `medium`, `high`." }, "honeypot": { "type": [ "boolean", "null" ], "description": "" }, "buyTaxPct": { "type": [ "number", "null" ], "description": "" }, "sellTaxPct": { "type": [ "number", "null" ], "description": "" }, "risks": { "type": "array", "items": { "type": "string", "description": "" } } }, "description": "A security scan of the unknown token, present when the value check could not run on a fallback answer." }, "warnings": { "type": "array", "items": { "type": "string", "description": "" }, "description": "`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." }, "quoteId": { "type": "string", "description": "Pass to `POST /meta/swap` within 2 minutes." }, "expiresAt": { "type": "integer", "description": "Unix time, seconds, UTC." } }, "description": "The same shape whichever provider answered." }, "Candle": { "type": "object", "properties": { "t": { "type": "integer", "description": "Unix time, seconds, UTC." }, "o": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" }, "l": { "type": "number", "description": "" }, "c": { "type": "number", "description": "" }, "v": { "type": "number", "description": "USD volume in the bucket." } } }, "TradeRow": { "type": "object", "properties": { "tx": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$", "description": "Transaction hash." }, "logIndex": { "type": "integer", "description": "" }, "dex": { "type": "string", "description": "" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "tokenAmt": { "type": "number", "description": "" }, "usd": { "type": "number", "description": "" }, "priceUsd": { "type": "number", "description": "" }, "ts": { "type": "integer", "description": "Unix time, seconds, UTC." }, "wallet": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." } } }, "StatsWindow": { "type": "object", "properties": { "change": { "type": "number", "description": "Percent." }, "txns": { "type": "integer", "description": "" }, "buys": { "type": "integer", "description": "" }, "sells": { "type": "integer", "description": "" }, "buyVol": { "type": "number", "description": "" }, "sellVol": { "type": "number", "description": "" }, "makers": { "type": "integer", "description": "" }, "buyers": { "type": "integer", "description": "" }, "sellers": { "type": "integer", "description": "" } } }, "SmartWallet": { "type": "object", "properties": { "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "pnlUsd": { "type": "number", "description": "Realized plus open PnL at current prices." }, "realizedUsd": { "type": "number", "description": "" }, "unrealizedUsd": { "type": "number", "description": "" }, "volumeUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "tokensTraded": { "type": "integer", "description": "" }, "winningTokens": { "type": "integer", "description": "" }, "winRate": { "type": "number", "description": "0–1." }, "topToken": { "type": "object", "properties": { "symbol": { "type": [ "string", "null" ], "description": "" }, "pnlUsd": { "type": "number", "description": "" } } }, "lastActiveTs": { "type": "integer", "description": "Unix time, seconds, UTC." }, "pnlMeme": { "type": "number", "description": "" }, "pnlMajor": { "type": "number", "description": "" }, "memeVol": { "type": "number", "description": "" }, "archetype": { "type": "string", "description": "`degen` · `allrounder` · `majors` …" }, "memeShare": { "type": "number", "description": "" }, "winRateAdj": { "type": "number", "description": "Luck-corrected win rate." }, "smartScore": { "type": "number", "description": "The ranking key: realized-weighted, luck-corrected, recency-decayed profit." } } }, "PnlToken": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "symbol": { "type": [ "string", "null" ], "description": "" }, "logo": { "type": [ "string", "null" ], "description": "" }, "realizedUsd": { "type": "number", "description": "" }, "unrealizedUsd": { "type": "number", "description": "" }, "totalUsd": { "type": "number", "description": "" }, "costRemaining": { "type": "number", "description": "" }, "curValue": { "type": "number", "description": "" }, "curAmount": { "type": "number", "description": "" }, "avgCost": { "type": "number", "description": "Average cost per token, USD." }, "roiPct": { "type": [ "number", "null" ], "description": "" }, "untrackedAmount": { "type": "number", "description": "Balance that arrived by transfer (no cost basis)." }, "untrackedValue": { "type": "number", "description": "" } } }, "LpEvent": { "type": "object", "properties": { "tx": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$", "description": "Transaction hash." }, "logIndex": { "type": "integer", "description": "" }, "pool": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "dex": { "type": "string", "description": "" }, "kind": { "type": "string", "enum": [ "add", "remove", "collect" ] }, "wallet": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "token": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenAmt": { "type": "number", "description": "" }, "anchor": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "anchorAmt": { "type": "number", "description": "" }, "usd": { "type": "number", "description": "Dollars that entered or left the pool." }, "priced": { "type": "boolean", "description": "False when the event could not be valued (no anchor side)." }, "tickLower": { "type": [ "integer", "null" ], "description": "" }, "tickUpper": { "type": [ "integer", "null" ], "description": "" }, "block": { "type": "integer", "description": "" }, "ts": { "type": "integer", "description": "Unix time, seconds, UTC." }, "manager": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenId": { "type": [ "string", "null" ], "description": "Position NFT id, for managed positions." } } }, "PoolListRow": { "type": "object", "properties": { "pool": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "dex": { "type": "string", "description": "" }, "kind": { "type": "string", "enum": [ "v2", "clmm", "v4" ] }, "feeBps": { "type": [ "number", "null" ], "description": "" }, "hooks": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "lpAccess": { "type": "string", "enum": [ "open", "hooked", "unknown" ], "description": "`hooked` = a V4 hook can refuse adds." }, "tickSpacing": { "type": [ "integer", "null" ], "description": "" }, "token0": { "$ref": "#/components/schemas/TokenLite" }, "token1": { "$ref": "#/components/schemas/TokenLite" }, "tokenSide": { "type": [ "integer", "null" ], "description": "Which side is the non-anchor token (0 or 1)." }, "tvlUsd": { "type": [ "number", "null" ], "description": "" }, "tvlSrc": { "type": [ "string", "null" ], "description": "Where TVL came from (`onchain`, `dexscreener`, …)." }, "tvlAt": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "vol": { "type": "object", "properties": { "h1": { "type": "number", "description": "" }, "h6": { "type": "number", "description": "" }, "h24": { "type": "number", "description": "" }, "d7": { "type": "number", "description": "" } } }, "fees": { "type": "object", "properties": { "h1": { "type": [ "number", "null" ], "description": "" }, "h6": { "type": [ "number", "null" ], "description": "" }, "h24": { "type": [ "number", "null" ], "description": "" } }, "description": "volume × the pool's fee tier." }, "feeTvlPct": { "type": "object", "properties": { "h1": { "type": [ "number", "null" ], "description": "" }, "h6": { "type": [ "number", "null" ], "description": "" }, "h24": { "type": [ "number", "null" ], "description": "" } }, "description": "fees ÷ TVL, percent." }, "aprPct": { "type": [ "number", "null" ], "description": "24h fee/TVL × 365 — a full-range yardstick, not a promise." }, "trades24h": { "type": "integer", "description": "" }, "wallets24h": { "type": "integer", "description": "" }, "priceUsd": { "type": [ "number", "null" ], "description": "" }, "lpAdd24h": { "type": "number", "description": "" }, "lpRemove24h": { "type": "number", "description": "" }, "providers24h": { "type": "integer", "description": "" }, "firstSeenTs": { "type": "integer", "description": "Unix time, seconds, UTC." }, "createdTs": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "lastTradeHour": { "type": "integer", "description": "" }, "turnover24h": { "type": [ "number", "null" ], "description": "24h volume ÷ TVL." }, "suspect": { "type": "boolean", "description": "Wash or launch-farm printing (volume without traders, dust TVL under real volume, turnover no honest pool reaches). Hidden by default; `flagged=1` shows them." }, "score": { "type": "integer", "description": "0–100 health score (traders, TVL, yield sanity, LP flow, age, penalties)." }, "marketCapUsd": { "type": [ "number", "null" ], "description": "The tracked token's price × its total supply on this chain (for a bridged token: what was bridged here). On the list only; `null` when the pool tracks neither side, the tracked side is the native coin, or the supply is not on record yet." } } }, "LpPosition": { "type": "object", "properties": { "manager": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tokenId": { "type": "string", "description": "" }, "pool": { "type": [ "string", "null" ], "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "dex": { "type": [ "string", "null" ], "description": "" }, "kind": { "type": "string", "enum": [ "v3", "v4" ] }, "owner": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "token": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "anchor": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "tickLower": { "type": [ "integer", "null" ], "description": "" }, "tickUpper": { "type": [ "integer", "null" ], "description": "" }, "symbol": { "type": [ "string", "null" ], "description": "" }, "anchorSymbol": { "type": [ "string", "null" ], "description": "" }, "logo": { "type": [ "string", "null" ], "description": "" }, "inUsd": { "type": "number", "description": "Dollars added." }, "outUsd": { "type": "number", "description": "Dollars removed." }, "feesUsd": { "type": "number", "description": "Fees collected." }, "adds": { "type": "integer", "description": "" }, "removes": { "type": "integer", "description": "" }, "collects": { "type": "integer", "description": "" }, "openedTs": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "lastTs": { "type": "integer", "description": "Unix time, seconds, UTC." }, "closedTs": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "burned": { "type": "boolean", "description": "" }, "status": { "type": "string", "enum": [ "open", "closed" ] }, "valueUsd": { "type": [ "number", "null" ], "description": "Live value of the liquidity (open positions)." }, "uncollectedUsd": { "type": [ "number", "null" ], "description": "Uncollected fees (V3)." }, "inRange": { "type": [ "boolean", "null" ], "description": "" }, "pnlUsd": { "type": [ "number", "null" ], "description": "Liquidity leg only." }, "pnlPct": { "type": [ "number", "null" ], "description": "" }, "ageHours": { "type": [ "number", "null" ], "description": "" }, "edgePct": { "type": [ "number", "null" ], "description": "Distance from the price to the nearest range edge, percent." }, "jit": { "type": "boolean", "description": "Opened and closed within seconds — a swap trick, shown but not scored." }, "unreconciled": { "type": "boolean", "description": "Dollars out exceed dollars in by far — the tape missed an add; shown, never scored." } } }, "LpLeaderRow": { "type": "object", "properties": { "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "winRatePct": { "type": [ "number", "null" ], "description": "" }, "feesUsd": { "type": "number", "description": "" }, "pools": { "type": "integer", "description": "" }, "evUsd": { "type": [ "number", "null" ], "description": "Expected value per position." }, "avgAgeHours": { "type": [ "number", "null" ], "description": "" }, "avgInvestedUsd": { "type": [ "number", "null" ], "description": "" }, "avgMonthlyProfitUsd": { "type": [ "number", "null" ], "description": "" }, "windows": { "type": "object", "properties": { "d7": { "type": "object", "properties": { "positions": { "type": "integer", "description": "" }, "profitUsd": { "type": "number", "description": "" }, "feesUsd": { "type": "number", "description": "" } } }, "d30": { "type": "object", "properties": { "positions": { "type": "integer", "description": "" }, "profitUsd": { "type": "number", "description": "" }, "feesUsd": { "type": "number", "description": "" } } }, "all": { "type": "object", "properties": { "positions": { "type": "integer", "description": "" }, "profitUsd": { "type": "number", "description": "" }, "feesUsd": { "type": "number", "description": "" } } } }, "description": "Per window: the positions that ended or were last touched in it, the profit they made and the fees they collected over their life." }, "open": { "type": "integer", "description": "" }, "closed": { "type": "integer", "description": "" }, "wins": { "type": "integer", "description": "" }, "firstTs": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "lastTs": { "type": "integer", "description": "Unix time, seconds, UTC." }, "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "description": "YYYY-MM-DD" }, "profitUsd": { "type": "number", "description": "" } } }, "description": "Last 7 days." }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "symbol": { "type": [ "string", "null" ], "description": "" }, "logo": { "type": [ "string", "null" ], "description": "" }, "inUsd": { "type": "number", "description": "" }, "positions": { "type": "integer", "description": "" } } }, "description": "What the wallet provides to, by dollars in." } } }, "SimResult": { "type": "object", "properties": { "pool": { "type": "string", "pattern": "^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$", "description": "A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id." }, "dex": { "type": "string", "description": "" }, "feeBps": { "type": [ "number", "null" ], "description": "" }, "tvlUsd": { "type": [ "number", "null" ], "description": "" }, "days": { "type": "integer", "description": "" }, "hours": { "type": "integer", "description": "Candles replayed." }, "hoursInRange": { "type": "integer", "description": "" }, "inRangePct": { "type": "number", "description": "" }, "exits": { "type": "integer", "description": "Times the price left the range." }, "lower": { "type": "number", "description": "" }, "upper": { "type": "number", "description": "" }, "unreliable": { "type": [ "string", "null" ], "description": "Why the number should not be trusted, when it should not." }, "entryPrice": { "type": "number", "description": "" }, "exitPrice": { "type": "number", "description": "" }, "priceChangePct": { "type": "number", "description": "" }, "feesUsd": { "type": "number", "description": "" }, "lpValueEndUsd": { "type": "number", "description": "" }, "holdValueEndUsd": { "type": "number", "description": "" }, "ilUsd": { "type": "number", "description": "Impermanent loss (negative = loss)." }, "netVsHoldUsd": { "type": "number", "description": "" }, "totalReturnUsd": { "type": "number", "description": "" }, "totalReturnPct": { "type": "number", "description": "" }, "feeAprPct": { "type": "number", "description": "" }, "capitalEfficiency": { "type": "number", "description": "Versus full range." }, "shareOfPoolPct": { "type": "number", "description": "" }, "note": { "type": "string", "description": "" } }, "description": "One range, backtested on Chord's own candles and the pool's real fee tier." }, "LauncherStat": { "type": "object", "properties": { "launcher": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "name": { "type": [ "string", "null" ], "description": "" }, "site": { "type": [ "string", "null" ], "description": "" }, "logo": { "type": [ "string", "null" ], "description": "" }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "v2", "v3", "v4" ] } }, "shapes": { "type": "array", "items": { "type": "object", "properties": { "hooks": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "fee": { "type": [ "integer", "null" ], "description": "" }, "tickSpacing": { "type": [ "integer", "null" ], "description": "" }, "pools": { "type": "integer", "description": "" } } }, "description": "The pool templates this launcher creates." }, "pools1h": { "type": "integer", "description": "" }, "pools24h": { "type": "integer", "description": "" }, "creators24h": { "type": "integer", "description": "Distinct creator wallets." }, "firstSeen": { "type": "integer", "description": "Unix time, seconds, UTC." }, "lastSeen": { "type": "integer", "description": "Unix time, seconds, UTC." }, "swaps24h": { "type": [ "integer", "null" ], "description": "" }, "volume24h": { "type": [ "number", "null" ], "description": "" }, "wallets24h": { "type": [ "integer", "null" ], "description": "" }, "activePools24h": { "type": [ "integer", "null" ], "description": "" } } }, "IngestFloor": { "type": "object", "properties": { "minTradeUsd": { "type": "number", "description": "Trades under this USD value (at index time) are not in the index, so every count, volume and candle covers trades at or above it. 0 = every priced trade." }, "history": { "type": "array", "items": { "type": "object", "properties": { "usd": { "type": "number", "description": "Floor in force." }, "fromTs": { "type": "integer", "description": "Unix time, seconds, UTC." } } }, "description": "Floors in force over time, oldest first. Empty when the chain was never floored. Raising a floor does not remove older, smaller rows." } }, "description": "The tape's ingest floor. BNB Chain runs at $100 today; Avalanche and Base at 0." }, "ChainCoverage": { "type": "object", "properties": { "recentAt": { "type": "integer", "description": "Unix time, seconds, UTC." }, "stale": { "type": "boolean", "description": "True when the last rollup pass is more than 30 minutes old." } }, "description": "When the rollup last ran." }, "ChainTokenRow": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address, hex, case-insensitive." }, "symbol": { "type": [ "string", "null" ], "description": "Read from the contract. Null while unresolved." }, "name": { "type": [ "string", "null" ], "description": "" }, "decimals": { "type": [ "integer", "null" ], "description": "" }, "logoURI": { "type": "null", "description": "Always null on these chains for now." }, "priceUsd": { "type": [ "number", "null" ], "description": "Last print on the token's busiest venue, USD." }, "change24hPct": { "type": [ "number", "null" ], "description": "" }, "volume24h": { "type": "number", "description": "USD, every venue, trades at or above the ingest floor." }, "buyVolume24h": { "type": "number", "description": "" }, "sellVolume24h": { "type": "number", "description": "" }, "trades24h": { "type": "integer", "description": "" }, "buys24h": { "type": "integer", "description": "" }, "sells24h": { "type": "integer", "description": "" }, "dominantDex": { "type": [ "string", "null" ], "description": "Venue id with the most 24-hour volume." }, "lastTradeTs": { "type": "integer", "description": "Unix time, seconds, UTC." } }, "description": "One token on a chain-keyed chain with its 24-hour tape. No curated list, no honesty flags, no trader counts yet." }, "ChainVenueShare": { "type": "object", "properties": { "dex": { "type": "string", "description": "Venue id." }, "volUsd": { "type": "number", "description": "" }, "trades": { "type": "integer", "description": "" }, "tokens": { "type": "integer", "description": "" }, "sharePct": { "type": "number", "description": "" } }, "description": "One venue's share of the window." }, "SolTokenRow": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "symbol": { "type": [ "string", "null" ], "description": "Creator-chosen; null until the metadata worker has read it." }, "name": { "type": [ "string", "null" ], "description": "Creator-chosen." }, "image": { "type": [ "string", "null" ], "description": "Image URL from the token's metadata, as published by its creator." }, "decimals": { "type": [ "integer", "null" ], "description": "" }, "priceUsd": { "type": [ "number", "null" ], "description": "Last price on the token's main pool (traded in the last hour first, then the deepest)." }, "change24hPct": { "type": [ "number", "null" ], "description": "Price now against the main pool's close 24 hours ago." }, "volume24hUsd": { "type": "number", "description": "USD over the 24-hour window, every pool the tape reads." }, "trades24h": { "type": "integer", "description": "" }, "buys24h": { "type": "integer", "description": "" }, "buyVolume24hUsd": { "type": "number", "description": "" }, "liquidityUsd": { "type": [ "number", "null" ], "description": "Main pool: twice its quote-side reserve in USD, from the last swap whose event carried the reserve. An estimate; null when unknown." }, "marketCapUsd": { "type": [ "number", "null" ], "description": "Price × supply: fully diluted." }, "pool": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "dex": { "type": [ "string", "null" ], "description": "Venue id: `pumpswap` · `pumpfun` (bonding curve) · `meteora_dbc` · `meteora_damm_v2` · `meteora_dlmm` · `meteora_pools` (dynamic AMM v1) · `raydium_clmm` · `raydium_cpmm` · `raydium_v4` · `raydium_launchlab` · `orca` (Whirlpool)." }, "firstSeen": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "oneWayPct": { "type": [ "number", "null" ], "description": "Percent of the 24-hour dollar volume traded by wallets that went one way: each wallet's smaller side (bought or sold, in USD) under half its larger side. The rest is wallets buying and selling about the same amounts back and forth: arbitrage, market making or wash trading. Null when not measured." }, "screen": { "type": [ "string", "null" ], "enum": [ "volume bot", "impostor" ], "description": "Why the boards leave this token out, or null. `volume bot`: under 10 % of its 24-hour volume came from one-way wallets and it is not a deep market (at least $250k of SOL / stable liquidity turned over at most 10× in the window). `impostor`: the ticker of SOL, USDC or USDT, look-alike letters included, on another mint." } }, "description": "One Solana token with its 24-hour tape." }, "SolPosition": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "symbol": { "type": [ "string", "null" ], "description": "" }, "name": { "type": [ "string", "null" ], "description": "" }, "image": { "type": [ "string", "null" ], "description": "" }, "priceUsd": { "type": [ "number", "null" ], "description": "Current price on the main pool." }, "boughtUsd": { "type": "number", "description": "" }, "soldUsd": { "type": "number", "description": "" }, "boughtAmount": { "type": "number", "description": "Whole tokens." }, "soldAmount": { "type": "number", "description": "Whole tokens." }, "buys": { "type": "integer", "description": "" }, "sells": { "type": "integer", "description": "" }, "heldAmount": { "type": "number", "description": "Bought minus sold inside the window, whole tokens (never below 0). Not the on-chain balance." }, "heldValueUsd": { "type": [ "number", "null" ], "description": "" }, "realizedPnlUsd": { "type": [ "number", "null" ], "description": "Matched amount × (average sell − average buy). Null when the window has sells but no buys." }, "unrealizedPnlUsd": { "type": [ "number", "null" ], "description": "Held amount × (price − average buy)." }, "partial": { "type": "boolean", "description": "Sold more than it bought inside the window: part of the position was bought before the window (or arrived by transfer), so those sells carry no cost basis." }, "lastDay": { "type": "integer", "description": "Unix time, seconds, UTC." } }, "description": "One token in a wallet's window." }, "SolLpPosition": { "type": "object", "properties": { "position": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "dex": { "type": "string", "description": "`meteora_dlmm` · `meteora_damm_v2` · `raydium_clmm` · `pumpswap`." }, "pool": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "owner": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "mintA": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "symbolA": { "type": [ "string", "null" ], "description": "Creator-chosen." }, "mintB": { "type": [ "string", "null" ], "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "symbolB": { "type": [ "string", "null" ], "description": "Creator-chosen." }, "lower": { "type": [ "integer", "null" ], "description": "DLMM bin id or CLMM tick." }, "upper": { "type": [ "integer", "null" ], "description": "" }, "status": { "type": "string", "enum": [ "open", "closed" ] }, "openedAt": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "closedAt": { "type": [ "integer", "null" ], "description": "Unix time, seconds, UTC." }, "firstEvent": { "type": "integer", "description": "Unix time, seconds, UTC." }, "lastEvent": { "type": "integer", "description": "Unix time, seconds, UTC." }, "events": { "type": "integer", "description": "" }, "depositedA": { "type": [ "number", "null" ], "description": "Whole tokens." }, "depositedB": { "type": [ "number", "null" ], "description": "" }, "withdrawnA": { "type": [ "number", "null" ], "description": "" }, "withdrawnB": { "type": [ "number", "null" ], "description": "" }, "feesA": { "type": [ "number", "null" ], "description": "Claimed." }, "feesB": { "type": [ "number", "null" ], "description": "Claimed." }, "depositedUsd": { "type": "number", "description": "" }, "withdrawnUsd": { "type": "number", "description": "" }, "feesClaimedUsd": { "type": "number", "description": "" }, "realizedPnlUsd": { "type": [ "number", "null" ], "description": "Withdrawn + fees − deposited; null unless closed, not partial and fully priced." }, "partial": { "type": "boolean", "description": "The tape did not see the open (opened before `since`); PumpSwap: more came out than the tape saw going in." }, "unpricedEvents": { "type": "integer", "description": "Value events without a USD price." } }, "description": "One Solana LP position." }, "SolTradeQuote": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "route": { "type": "string", "enum": [ "direct", "jupiter", "jupiter_meta" ], "description": "`direct` = Chord's own route (pump pools or Chord's router) · `jupiter` = Jupiter's swap API · `jupiter_meta` = Jupiter's order (RFQ makers, DFlow, OKX)." }, "mint": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "inAmount": { "type": "string", "pattern": "^\\d+$", "description": "What the wallet puts in: lamports for a buy, the token's smallest unit for a sell." }, "outAmount": { "type": "string", "pattern": "^\\d+$", "description": "What the simulation of `tx` delivered to the wallet: tokens for a buy, lamports for a sell (wSOL counted as SOL), after every fee." }, "minOut": { "type": "string", "pattern": "^\\d+$", "description": "The least the transaction accepts before it fails, from `slippageBps`." }, "slippageBps": { "type": "integer", "description": "" }, "feeLamports": { "type": "string", "pattern": "^\\d+$", "description": "Chord's fee. 0 today." }, "feeBps": { "type": "integer", "description": "Chord's fee rate. 0 today." }, "networkFeeLamports": { "type": "integer", "description": "Base + priority fee the wallet pays; 0 when Jupiter or a market maker pays (`gasless`)." }, "units": { "type": "integer", "description": "Compute units of the simulation." }, "walletLamportsDelta": { "type": "string", "pattern": "^-?\\d+$", "description": "The wallet's whole SOL change in the simulation, network fee and rent of new accounts included." }, "tx": { "type": "string", "description": "The unsigned v0 transaction, base64 — exactly what was simulated. Sign it unchanged and POST it to `/sol/trade/send`." }, "txBytes": { "type": "integer", "description": "" }, "blockhash": { "type": "string", "description": "" }, "lastValidBlockHeight": { "type": "integer", "description": "After this block height the transaction can no longer land." }, "simulatedSlot": { "type": "integer", "description": "" }, "ms": { "type": "number", "description": "" }, "venue": { "type": "string", "description": "`direct` only: where it trades (the largest leg when the order is split): `pumpswap`, `pumpfun`, `raydium_v4`, `raydium_cpmm`, `raydium_clmm`, `orca`, `meteora_dlmm`, `meteora_damm_v2`, `meteora_dbc`, `raydium_launchlab`." }, "layout": { "type": "string", "description": "`direct` on a pump pool: the instruction layout copied." }, "solBased": { "type": "boolean", "description": "A PumpSwap pool whose base is SOL." }, "pool": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "partial": { "type": "boolean", "description": "A pump.fun curve had fewer tokens left than the input buys: the quote takes all it has, for at most `inAmount`." }, "hops": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Venue." }, "pool": { "type": "string", "description": "Pool." }, "percent": { "type": "number", "description": "Share of the input, %." } } }, "description": "The legs: Chord's router (one or two pools) or Jupiter's route plan." }, "router": { "type": "string", "description": "`jupiter_meta`: which router won Jupiter's auction (`metis`, `jupiterz`, `dflow`, `okx`)." }, "gasless": { "type": "boolean", "description": "`jupiter_meta`: Jupiter or the market maker pays the network fee; the wallet is a second signer." }, "expireAt": { "type": "integer", "description": "`jupiter_meta` RFQ quotes: Unix seconds the market maker's price lives to. Ask again when under ten seconds are left." } }, "description": "One executable quote.", "required": [ "ok", "route", "mint", "side", "inAmount", "outAmount", "minOut", "tx" ] }, "SolTradeTx": { "type": "object", "properties": { "signature": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{64,88}$", "description": "Transaction signature, base58." }, "status": { "type": "string", "enum": [ "pending", "confirmed", "finalized", "failed", "expired" ] }, "route": { "type": "string", "enum": [ "direct", "jupiter", "jupiter_meta" ], "description": "`direct` = Chord's own route (pump pools or Chord's router) · `jupiter` = Jupiter's swap API · `jupiter_meta` = Jupiter's order (RFQ makers, DFlow, OKX)." }, "mint": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "wallet": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana address, base58, case-sensitive. Never lower-case it." }, "sentAt": { "type": "integer", "description": "Unix seconds." }, "sends": { "type": "integer", "description": "How many times Chord sent it (every 2 seconds until it lands or its blockhash expires)." }, "slot": { "type": [ "integer", "null" ], "description": "" }, "error": { "type": [ "string", "null" ], "description": "" }, "quotedOut": { "type": "string", "pattern": "^\\d+$", "description": "Base units as a decimal string (lamports for SOL)." }, "receivedOut": { "type": [ "string", "null" ], "pattern": "^-?\\d+$", "description": "What the wallet really got, read from the landed transaction with the quote's measure." }, "confirmedAt": { "type": [ "integer", "null" ], "description": "Unix seconds." } }, "description": "A sent swap." } } } }