notional

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

REST
https://api.notinal.xyz/v1

Every 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.

Request
curl https://api.notinal.xyz/v1/coins/0x7e57000000000000000000000000000000000005
Response
{
  "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:

JavaScript
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:

Response headers
HTTP/2 200
content-type: application/json; charset=utf-8
x-ratelimit-limit: 120
x-ratelimit-remaining: 117
x-ratelimit-reset: 1790992860
HeaderMeaning
x-ratelimit-limitRequests allowed per minute: 120.
x-ratelimit-remainingRequests left in the current minute.
x-ratelimit-resetWhen 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:

404 Not Found
{
  "error": {
    "code": "not_found",
    "message": "No coin at 0x7e57000000000000000000000000000000000099.",
    "status": 404
  }
}
StatusCodeMeaning
400invalid_requestA parameter is missing or not valid. The message names it.
404not_foundThere is no coin, pool or route at that path.
429rate_limitedToo many requests. Wait for the seconds in Retry-After.
500internal_errorSomething failed on our side. Retry with a growing delay.
503unavailableThe 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:

A page of a list
{
  "data": [ … ],
  "nextCursor": "eyJhIjoiMHg2YjYyOTkxMDU4OWE4OTkyNDVlMmNjZGFmMDQ3ZDBkYTFjYjA0OGNmIn0"
}
  • limit sets the page size: 1 to 100, 50 if you leave it out.
  • To get the next page, send the same request with cursor set to nextCursor. On the last page nextCursor is null.
  • 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.
Every pool, page by page
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.

Welcome to notional

notional is an interface to smart contracts on HyperEVM. You stay in control of your wallet, every transaction is final, and memecoins and tokenized stocks can lose all of their value.