API basics
Base URL, chains and addresses, units, base and quote, pagination, errors.
Base URL
| Where | Base URL | |
|---|---|---|
| Through the console | https://app.aurelia.build/api | Same origin as these docs: the console forwards /api/* to the API, WebSocket included. The examples use it. |
| The API, locally | http://localhost:7070 | The API's own port, published on loopback by docker compose. |
| The API, in production | https://<api-domain> | The domain your deployment gives the API service. |
All endpoints are GET, take no body and answer JSON; live data is one WebSocket, /live. Data routes, /plans and /health allow any origin (CORS), so a web page on another site can call them with a key or JWT; the console's own session cookie only works on its own origin.
Chains and addresses
| Chain | Id | Addresses |
|---|---|---|
| BSC | evm:56 | 0x and 40 hex digits. Answers use lowercase; a checksummed address is accepted. |
| Solana | solana | Base58, case-sensitive: send it exactly. |
| Base | evm:8453 | 0x and 40 hex digits. Answers use lowercase; a checksummed address is accepted. |
| Robinhood Chain | evm:4663 | 0x and 40 hex digits. Answers use lowercase; a checksummed address is accepted. |
| Ethereum | evm:1 | 0x and 40 hex digits. Answers use lowercase; a checksummed address is accepted. |
A chain is named in the path (/tokens/:chain/:address), in a query (/trades?chain=, chains=) or in a batch item. Native BNB, ETH or SOL has the address native wherever a token object names it. Addresses are not format-checked: a malformed one reads as unknown.
Batch lists (tokens= on /tokens and /prices, wallets= on /wallets) are comma-separated <chain>:<address> items, split on the last colon: evm:56:0xbb4c…, solana:So111…. An unknown token comes back null in its place.
Units
- Token amounts are decimal strings with decimals applied, such as
"0.109729208291499538". They are exact: parse them with a decimal library if you do arithmetic. - USD values and prices are JSON numbers. Price changes and shares are fractions:
0.05is 5%. - Times (
time,…At,at) are unix milliseconds. Candles use unix seconds:from,toand each bar'st. - Blocks are block numbers on BSC and slots on Solana.
Base, quote and side
Every swap has a base, the token being priced, and a quote. The quote is picked by fixed priority: a stablecoin, then the wrapped native token (WBNB, WSOL), then the token that was priced first, then token0. A pool keeps the same base, so its price and candles are one series.
USD prices come from direct trades: $1 for a stablecoin; for WBNB, WSOL and other tokens, a price set by recent trades against a stablecoin or the native token. A swap with neither is priced through its quote's recent price, else its base's; without one it stays unpriced (priced: false) rather than guessed.
A trade is told from one token's side: the token asked for (token=), else the swap's base. buy means the trader received that token, sell that they paid it. Token stats count the swaps where the token was the base; traders count both sides.
Pagination
Lists take limit and cursor, and end with next: pass it back as cursor for the next page. next is an opaque string, null at the end. A filtered page can come back short, or empty, before the end: it examined a bounded part of the list, and next continues after it. Follow next until it is null.
Two pages:
curl -s 'https://app.aurelia.build/api/trades?chain=evm:56&token=0xa9fcda9bd321adeb7cbbbd30ef2dd0ed1d657777&limit=2'
# … "next": "1790618554904.1000749.0.4"
curl -s 'https://app.aurelia.build/api/trades?chain=evm:56&token=0xa9fcda9bd321adeb7cbbbd30ef2dd0ed1d657777&limit=2&cursor=1790618554904.1000749.0.4'Wallets in lists
Every row that names a wallet carries its labels beside it: trades, traders, holders, portfolios, a token's creator, a wallet's funder, a transfer's counterparty. A wallet without a label has [].
Errors
| Status | When | Body |
|---|---|---|
| 400 | A parameter is invalid, unknown, repeated, or of another mode | {"error":"limit must be 1-200"} |
| 404 | An unknown token or pool | {"error":"unknown token"} |
| 422 | An answer that could not be exact: a BSC wallet that touched more than 2,000 tokens; an address that is not a mint; candles of a token that is the base of no pool; native BNB history; history before indexing reached the balances | {"error":"…"} |
| 502 | The chain could not be read (a portfolio, holders, a Solana wallet's activity or history) | {"error":"the chain could not be read: …"} |
| 503 | A chain's read budget is spent (holders, Solana activity and history), with Retry-After; /health when a service is down | {"error":"…"} |
| 401 | No credentials, or a bad, expired or revoked key or JWT | {"error":"unauthorized"} |
| 402 | Your credits left cannot pay for the request | {"error":"insufficient_balance"} |
| 429 | Over the burst limit | {"error":"rate_limited","retryAfter":1} |
Error bodies are JSON with an error message meant for people: branch on the status. An unknown route answers 404 with the plain text NOT_FOUND. On the socket, an error ends one subscription, not the socket (see the socket).
Every request needs an account: sign in and create a key on your account. Your account gets 10,000 free credits once, to spend however you like. Authentication and limits covers keys, credits, paying and the headers that report what is left.