API overview
The notional API serves coins, trades, pools and protocol numbers as JSON, and pushes live updates over a WebSocket. It is open: public endpoints need no key and no sign-up.
Base URL
https://api.notinal.xyz/v1Every path in the REST reference is relative to it. Live updates come over the WebSocket at wss://api.notinal.xyz/v1/ws.
Your first request
Ask for a coin by its contract address. No headers are needed.
curl https://api.notinal.xyz/v1/coins/0x7e57000000000000000000000000000000000005{
"address": "0x7e57000000000000000000000000000000000005",
"symbol": "TEST5",
"name": "test5",
"pair": "AAPL",
"image": "https://notinal.xyz/tokens/test5.svg",
"creator": "0x5f60718293a4b5c6d7e8f9012a3b4c5d6e7f8091",
"createdAt": 1790991480,
"priceUsd": "0.00000354",
"marketCapUsd": "3540.00",
"volume24hUsd": "260.00",
"change24h": -1.1,
"holders": 8,
"curveProgress": 5,
"graduated": false,
"description": "A test coin paired with Apple.",
"links": {
"x": null,
"telegram": null,
"website": null
},
"supply": "1000000000",
"pricePair": "0.0000000153913",
"liquidityUsd": "991.20",
"creatorFeesUsd": "1.30",
"graduationPool": null
}The same request from JavaScript, in a browser or in Node:
const response = await fetch("https://api.notinal.xyz/v1/coins/0x7e57000000000000000000000000000000000005");
if (!response.ok) throw new Error(`notional API: ${response.status}`);
const coin = await response.json();Authentication
Public endpoints need no key, and every endpoint in these docs is public. The API sends CORS headers that allow any origin, so you can call it straight from a web page.
Requests and responses
- Requests are HTTPS GETs with query parameters. Responses are JSON in UTF-8, gzipped if you ask.
- Field names are camelCase. Addresses are lower-case hex strings.
- Times are Unix seconds, as numbers.
- Prices, amounts and USD values are decimal strings, such as
"0.000006", so nothing is lost to floating point. Amounts are in whole tokens:"1.5"HYPE is one and a half HYPE, not 1.5 wei. Counts and percentages are numbers. - New fields can appear in v1 at any time, so ignore fields you do not know. A change that could break a client comes as a new version, and v1 keeps working.
Rate limits
Each IP address can make 120 requests per minute. Every response says where you stand in its headers:
HTTP/2 200
content-type: application/json; charset=utf-8
x-ratelimit-limit: 120
x-ratelimit-remaining: 117
x-ratelimit-reset: 1790992860| Header | Meaning |
|---|---|
x-ratelimit-limit | Requests allowed per minute: 120. |
x-ratelimit-remaining | Requests left in the current minute. |
x-ratelimit-reset | When the count starts again, in Unix seconds. |
Past the limit, requests fail with status 429 and a retry-after header in seconds. Wait that long before you try again. If you are polling for new trades or prices, subscribe on the WebSocket instead: its updates do not count against the limit.
Errors
Errors come with an HTTP status and the same JSON body every time:
{
"error": {
"code": "not_found",
"message": "No coin at 0x7e57000000000000000000000000000000000099.",
"status": 404
}
}| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | A parameter is missing or not valid. The message names it. |
| 404 | not_found | There is no coin, pool or route at that path. |
| 429 | rate_limited | Too many requests. Wait for the seconds in Retry-After. |
| 500 | internal_error | Something failed on our side. Retry with a growing delay. |
| 503 | unavailable | The API is catching up with the chain. Retry shortly. |
Branch on code, not on message: messages are for people and can change.
Pagination
Lists come one page at a time, with a cursor for the next page:
{
"data": [ … ],
"nextCursor": "eyJhIjoiMHg2YjYyOTkxMDU4OWE4OTkyNDVlMmNjZGFmMDQ3ZDBkYTFjYjA0OGNmIn0"
}limitsets the page size: 1 to 100, 50 if you leave it out.- To get the next page, send the same request with
cursorset tonextCursor. On the last pagenextCursorisnull. - Cursors are opaque. Pass them back unchanged. They mark a position, not a page number, so new trades arriving while you page do not shift what you see.
async function allPools() {
const pools = [];
let cursor = null;
do {
const url = new URL("https://api.notinal.xyz/v1/pools");
url.searchParams.set("limit", "100");
if (cursor !== null) url.searchParams.set("cursor", cursor);
const response = await fetch(url);
if (!response.ok) throw new Error(`notional API: ${response.status}`);
const page = await response.json();
pools.push(...page.data);
cursor = page.nextCursor;
} while (cursor !== null);
return pools;
}Freshness
The API follows HyperEVM block by block. A trade usually appears in the API, and on the WebSocket, within two seconds of its block.
Next
- REST reference: every endpoint, with its parameters and an example.
- WebSocket: trades, candles, pools and launches as they happen.
- Contracts: read the chain yourself, or trade through the Router.
