REST reference
Every endpoint of the notional API, with its parameters, a request and the response it returns. Paths are relative to https://api.notinal.xyz/v1; see the API overview for limits, errors and paging.
| Endpoint | Returns |
|---|---|
GET/coins | Coins launched on notional, newest first or sorted. |
GET/coins | One coin, in full. |
GET/coins | A coin's trades, newest first. |
GET/coins | Who holds a coin, largest first. |
GET/coins | Price candles for a coin's chart. |
GET/pools | NLP pools with their liquidity, volume and APR. |
GET/pools | One NLP pool, in full. |
GET/pools | Swaps, deposits and withdrawals in a pool, newest first. |
GET/stats | Totals across notional: users, volume, fees and liquidity. |
GET/staking | What is staked, under which locks, and the rewards. |
List coins
GET/coins
Coins launched on notional, a page at a time.
Query parameters
| Parameter | Type | Description |
|---|---|---|
sort | string | created, newest first, is the default. marketCap, volume24h and change24h sort largest first. |
pair | string | Only coins that trade against this asset, such as HYPE, USDC or GME. |
graduated | boolean | true for graduated coins only, false for coins still on their curve. |
limit | integer | Items per page, 1 to 100. Default 50. |
cursor | string | The nextCursor of the previous page. |
curl "https://api.notinal.xyz/v1/coins?sort=marketCap&limit=2"{
"data": [
{
"address": "0x7e57000000000000000000000000000000000004",
"symbol": "TEST4",
"name": "test4",
"pair": "USDC",
"image": "https://notinal.xyz/tokens/test4.svg",
"creator": "0x4e5f60718293a4b5c6d7e8f9012a3b4c5d6e7f80",
"createdAt": 1790992440,
"priceUsd": "0.00000376",
"marketCapUsd": "3760.00",
"volume24hUsd": "720.00",
"change24h": 7.5,
"holders": 16,
"curveProgress": 5,
"graduated": false
},
{
"address": "0x7e57000000000000000000000000000000000001",
"symbol": "TEST1",
"name": "test1",
"pair": "GME",
"image": "https://notinal.xyz/tokens/test1.svg",
"creator": "0x91b2c3d4e5f60718293a4b5c6d7e8f9012a3b4c5",
"createdAt": 1790981640,
"priceUsd": "0.00000365",
"marketCapUsd": "3650.00",
"volume24hUsd": "640.00",
"change24h": 4.2,
"holders": 14,
"curveProgress": 5,
"graduated": false
}
],
"nextCursor": "eyJzIjoibWFya2V0Q2FwIiwidiI6IjM2NTAiLCJhIjoiMHg3ZTU3MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAxIn0"
}The coin object
| Field | Type | Description |
|---|---|---|
address | string | The coin's contract address. |
symbol | string | Its ticker. Tickers are not unique; the address is. |
name | string | Its name. |
pair | string | The symbol of the asset it trades against: HYPE, USDC or a stock. |
image | string | The URL of its image. |
creator | string | The address that launched it. |
createdAt | number | When it launched, in Unix seconds. |
priceUsd | string | The price of one coin, in USD. |
marketCapUsd | string | The price times the supply of 1,000,000,000. |
volume24hUsd | string | USD traded over the last 24 hours. |
change24h | number | The price change over the last 24 hours, in percent. |
holders | number | Addresses holding any of the coin. |
curveProgress | number | How much of the curve has sold, 0 to 100. 100 once graduated. |
graduated | boolean | Whether the coin has moved from its curve to a HyperSwap pool. |
Get a coin
GET/coins
One coin with its description, links and market. Returns 404 if no coin was launched at the address.
Path parameters
| Parameter | Type | Description |
|---|---|---|
address | string | The coin's contract address. |
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
}Fields
Everything in the coin object, and:
| Field | Type | Description |
|---|---|---|
description | string | The creator's description. Empty if none was given. |
links | object | x, telegram and website: URLs, or null when not set. |
supply | string | The total supply, in whole coins. Always 1,000,000,000. |
pricePair | string | The price of one coin in its pair asset. |
liquidityUsd | string | What backs the price, in USD: the curve's reserve, or the pool's after graduation. |
creatorFeesUsd | string | Fees paid to the creator so far, in USD. |
graduationPool | string or null | The HyperSwap pool the coin's liquidity is locked in. null until it graduates. |
List a coin's trades
GET/coins
A coin's trades, on its curve and, after graduation, in its pool. Newest first.
Parameters
| Parameter | Type | Description |
|---|---|---|
address | string | The coin's contract address. |
side | string | buy or sell. Both if left out. |
trader | string | Only trades by this address. |
limit | integer | Items per page, 1 to 100. Default 50. |
cursor | string | The nextCursor of the previous page. |
curl "https://api.notinal.xyz/v1/coins/0x7e57000000000000000000000000000000000005/trades?limit=3"{
"data": [
{
"time": 1790992659,
"side": "buy",
"coinAmount": "7464875.4",
"pairAmount": "0.1177667",
"priceUsd": "0.00000362851",
"valueUsd": "27.09",
"trader": "0x1b3021a71c884b2ebb936521d06a004125ad6e64",
"tx": "0x882a45b33cfb15a3fc09d72b843f7f2436b2b35a306db34ff2bf51b98b6cd576"
},
{
"time": 1790992647,
"side": "buy",
"coinAmount": "2577022.2",
"pairAmount": "0.040655387",
"priceUsd": "0.00000362851",
"valueUsd": "9.35",
"trader": "0x1b3021a71c884b2ebb936521d06a004125ad6e64",
"tx": "0xc52b0bb2c04a91be01c5cedbd325c22d679863f82e7acaf746a6fbac76f6eacc"
},
{
"time": 1790992612,
"side": "buy",
"coinAmount": "5882413.3",
"pairAmount": "0.09175003",
"priceUsd": "0.00000358739",
"valueUsd": "21.10",
"trader": "0x69b6f952495b376773bd975bea682c4aef3fa8fd",
"tx": "0x63b8d3e70bfbbe8e0f28dd1522e22cb06620b3dac9818d1626654ee97844db7d"
}
],
"nextCursor": "eyJ0IjoxNzkwOTkyNjEyLCJpIjoyfQ"
}The trade object
| Field | Type | Description |
|---|---|---|
time | number | When the trade was made, in Unix seconds. |
side | string | buy or sell, from the trader's side. |
coinAmount | string | Coins bought or sold. |
pairAmount | string | The pair asset paid for them, or received for them. |
priceUsd | string | The coin's price at the trade, in USD. |
valueUsd | string | What the trade was worth, in USD. |
trader | string | The address that traded. |
tx | string | The transaction hash. |
List a coin's holders
GET/coins
Who holds a coin, largest holding first. Contracts are labelled: the bonding curve, the pool a graduated coin trades in, and the coin's creator.
Parameters
| Parameter | Type | Description |
|---|---|---|
address | string | The coin's contract address. |
limit | integer | Items per page, 1 to 100. Default 50. |
cursor | string | The nextCursor of the previous page. |
curl "https://api.notinal.xyz/v1/coins/0x7e57000000000000000000000000000000000005/holders?limit=3"{
"holders": 8,
"data": [
{
"address": "0x23dd7bfd395597e56a02a045f11697d0858fcd18",
"label": "Bonding curve",
"balance": "770000000",
"share": 77
},
{
"address": "0x06681ce6e5f6caee856015c6868f6e6941a2cf24",
"label": null,
"balance": "36537554",
"share": 3.65
},
{
"address": "0x94ff70105c6e8642de42aba3455814d50a4549b6",
"label": null,
"balance": "34613663",
"share": 3.46
}
],
"nextCursor": "eyJzIjoic2hhcmUiLCJ2IjoiMy40NiIsImEiOiIweDk0ZmY3MDEwNWM2ZTg2NDJkZTQyYWJhMzQ1NTgxNGQ1MGE0NTQ5YjYifQ"
}Fields
| Field | Type | Description |
|---|---|---|
holders | number | How many addresses hold the coin in all. |
address | string | The holding address. |
label | string or null | Bonding curve, Pool or Creator; null for everyone else. |
balance | string | Coins held. |
share | number | The share of the supply held, in percent. |
Get a coin's candles
GET/coins
Price candles for a coin, oldest first, to draw its chart. A candle exists for every interval since the coin launched, even one with no trades.
Parameters
| Parameter | Type | Description |
|---|---|---|
address | string | The coin's contract address. |
interval | string | 1m, 5m, 15m or 1h. Default 5m. |
from | number | The earliest candle to return, in Unix seconds. |
to | number | The latest candle to return, in Unix seconds. Default now. |
limit | integer | Candles to return, 1 to 500, counting back from to. Default 500. |
curl "https://api.notinal.xyz/v1/coins/0x7e57000000000000000000000000000000000005/candles?interval=5m&to=1790992500&limit=3"{
"interval": "5m",
"data": [
{
"time": 1790991900,
"open": "0.00000369047",
"high": "0.00000382604",
"low": "0.00000354921",
"close": "0.00000375577",
"volumeUsd": "61.85"
},
{
"time": 1790992200,
"open": "0.00000375577",
"high": "0.00000376298",
"low": "0.00000352029",
"close": "0.00000359777",
"volumeUsd": "22.72"
},
{
"time": 1790992500,
"open": "0.00000359777",
"high": "0.00000365323",
"low": "0.0000035",
"close": "0.00000358715",
"volumeUsd": "57.54"
}
]
}The candle object
| Field | Type | Description |
|---|---|---|
time | number | The start of the candle, in Unix seconds. |
open, high, low, close | string | The coin's price in USD over the candle. |
volumeUsd | string | USD traded during the candle. |
List pools
GET/pools
NLP pools, a page at a time.
Query parameters
| Parameter | Type | Description |
|---|---|---|
sort | string | tvl is the default. volume24h, apr and created sort largest or newest first. |
kind | string | volatile, stable or stock. |
token | string | Only pools holding this token, by symbol, such as HYPE. |
limit | integer | Items per page, 1 to 100. Default 50. |
cursor | string | The nextCursor of the previous page. |
curl "https://api.notinal.xyz/v1/pools?sort=tvl&limit=2"{
"data": [
{
"address": "0x7197b1af3521b92ed8f1ce8dba175cdd55373388",
"kind": "volatile",
"base": {
"symbol": "HYPE",
"name": "Hyperliquid",
"priceUsd": "89",
"reserve": "56.60764"
},
"quote": {
"symbol": "USDC",
"name": "USD Coin",
"priceUsd": "1",
"reserve": "4801.92"
},
"feeBps": 5,
"price": "89",
"tvlUsd": "9840.00",
"volume24hUsd": "6120.00",
"fees24hUsd": "3.06",
"apr": 11.35,
"createdAt": 1790474400
},
{
"address": "0xdc95f0134ec2bcf3889e683c5f55eba29b1ce046",
"kind": "stable",
"base": {
"symbol": "USDC",
"name": "USD Coin",
"priceUsd": "1",
"reserve": "3702.65"
},
"quote": {
"symbol": "USDT0",
"name": "USDT0",
"priceUsd": "1",
"reserve": "3747.35"
},
"feeBps": 1,
"price": "1",
"tvlUsd": "7450.00",
"volume24hUsd": "4380.00",
"fees24hUsd": "0.44",
"apr": 2.15,
"createdAt": 1790474400
}
],
"nextCursor": "eyJ0IjoxNzkwOTkyNjY5LCJsIjozfQ"
}The pool object
| Field | Type | Description |
|---|---|---|
address | string | The pool's contract address. |
kind | string | volatile, stable or stock. |
base, quote | object | The two tokens: symbol, name, priceUsd, and reserve, how much of it the pool holds. |
feeBps | number | The fee on every swap, in basis points: 30 is 0.30%. |
price | string | One base token, priced in the quote token. |
tvlUsd | string | The value of everything in the pool, in USD. |
volume24hUsd | string | USD swapped over the last 24 hours. |
fees24hUsd | string | Fees paid by swaps over the last 24 hours, in USD. |
apr | number | The last 24 hours of fees, all of which go to liquidity providers, times 365, over the TVL, in percent. |
createdAt | number | When the pool was created, in Unix seconds. |
Get a pool
GET/pools
One NLP pool, with a week of volume and fees. Returns 404 if there is no NLP pool at the address.
Path parameters
| Parameter | Type | Description |
|---|---|---|
address | string | The pool's contract address. |
curl https://api.notinal.xyz/v1/pools/0x7197b1af3521b92ed8f1ce8dba175cdd55373388{
"address": "0x7197b1af3521b92ed8f1ce8dba175cdd55373388",
"kind": "volatile",
"base": {
"symbol": "HYPE",
"name": "Hyperliquid",
"priceUsd": "89",
"reserve": "56.60764"
},
"quote": {
"symbol": "USDC",
"name": "USD Coin",
"priceUsd": "1",
"reserve": "4801.92"
},
"feeBps": 5,
"price": "89",
"tvlUsd": "9840.00",
"volume24hUsd": "6120.00",
"fees24hUsd": "3.06",
"apr": 11.35,
"createdAt": 1790474400,
"tickSpacing": 10,
"volume7dUsd": "32857.94",
"fees7dUsd": "16.43",
"swaps24h": 42
}Fields
Everything in the pool object, and:
| Field | Type | Description |
|---|---|---|
tickSpacing | number | The step between prices a range can start or end at. It is set by the fee tier. |
volume7dUsd | string | USD swapped over the last 7 days. |
fees7dUsd | string | Fees paid over the last 7 days, in USD. |
swaps24h | number | Swaps over the last 24 hours. |
List a pool's transactions
GET/pools
Swaps, deposits and withdrawals in a pool, newest first.
Parameters
| Parameter | Type | Description |
|---|---|---|
address | string | The pool's contract address. |
type | string | swap, add or remove. All three if left out. |
account | string | Only transactions by this address. |
limit | integer | Items per page, 1 to 100. Default 50. |
cursor | string | The nextCursor of the previous page. |
curl "https://api.notinal.xyz/v1/pools/0x7197b1af3521b92ed8f1ce8dba175cdd55373388/transactions?limit=3"{
"data": [
{
"type": "swap",
"time": 1790990480,
"account": "0x9f2cda609d7587b9442a36a5009e3d519c4d1ee1",
"baseAmount": "4.8310803",
"quoteAmount": "-429.96615",
"valueUsd": "429.97",
"tx": "0xc6fc7ad07f7f7c8fe6cb640c970cf78fb41b55fb8ac242e55e8d0c5f02293fbf"
},
{
"type": "swap",
"time": 1790982839,
"account": "0x884d704f020d1f95b546a2801249c32a06d10f21",
"baseAmount": "1.8169599",
"quoteAmount": "-161.70943",
"valueUsd": "161.71",
"tx": "0x48731e40a33f91113a893451029d6562faab708f52a91d7bb101b79b5cac1883"
},
{
"type": "swap",
"time": 1790981773,
"account": "0x6a396d603eb39f0054a210c0b2d14b33a7a220a6",
"baseAmount": "-0.53432488",
"quoteAmount": "47.554914",
"valueUsd": "47.55",
"tx": "0x4982df39be51ff80f5b96c8f457d6577340080095dce41f3f54f5025b4fb8774"
}
],
"nextCursor": "eyJ0IjoxNzkwOTkyNTMxLCJpIjoyfQ"
}The transaction object
| Field | Type | Description |
|---|---|---|
type | string | swap, add for a deposit, or remove for a withdrawal. |
time | number | When it happened, in Unix seconds. |
account | string | The address that sent it. |
baseAmount, quoteAmount | string | How much of each token moved, from the pool's side: positive into the pool, negative out of it. |
valueUsd | string | What it was worth, in USD. |
tx | string | The transaction hash. |
Get protocol stats
GET/stats
Totals across notional since its first pool opened, and the last 24 hours. These are the numbers on Stats.
curl https://api.notinal.xyz/v1/stats{
"asOf": 1790992800,
"users": 63,
"transactions": 780,
"coinsLaunched": 6,
"coinsGraduated": 0,
"tvlUsd": "31460.00",
"volume24hUsd": "17523.00",
"fees24hUsd": "38.45",
"volumeUsd": {
"total": "77218.75",
"launchpad": "2600.00",
"nlp": "74618.75"
},
"feesUsd": {
"total": "79.79",
"liquidityProviders": "53.79",
"creators": "13.00",
"protocol": "13.00",
"builders": "0.00"
},
"feeSplit": {
"stakers": 0.5,
"treasury": 0.3,
"nlpVault": 0.2
}
}Fields
| Field | Type | Description |
|---|---|---|
asOf | number | The moment the numbers describe, in Unix seconds. |
users | number | Addresses that have traded, provided liquidity or staked. |
transactions | number | Transactions sent to notional's contracts. |
coinsLaunched, coinsGraduated | number | Coins launched, and how many graduated. |
tvlUsd | string | Everything held in NLP pools, in USD. |
volume24hUsd, fees24hUsd | string | Volume over the last 24 hours, and every fee traders paid on it. |
volumeUsd | object | All-time volume: total, and its launchpad and nlp parts. |
feesUsd | object | All-time fees: total, and who received them. liquidityProviders is pool swap fees, creators and protocol are the two halves of the curve fee, and builders is builder fees. |
feeSplit | object | How the fee distributor splits the protocol fees, as fractions of 1. See Fees. |
Get staking
GET/staking
NOTIONAL staked under each lock, the APR each lock earns at today's pace, and the reward payouts. These are the numbers on Stake.
curl https://api.notinal.xyz/v1/staking{
"token": "0x7e57000000000000000000000000000000000000",
"rewardAsset": "HYPE",
"stakers": 17,
"totalStaked": "137162421",
"totalWeight": "194924119.65",
"locks": [
{
"days": 0,
"multiplier": 1,
"staked": "55913889",
"apr": 202.86
},
{
"days": 30,
"multiplier": 1.25,
"staked": "42247001",
"apr": 253.57
},
{
"days": 90,
"multiplier": 1.6,
"staked": "8958184",
"apr": 324.57
},
{
"days": 180,
"multiplier": 2,
"staked": "18261656",
"apr": 405.71
},
{
"days": 365,
"multiplier": 3,
"staked": "11781691",
"apr": 608.57
}
],
"cooldownDays": 7,
"lastPayout": null,
"thisWeek": {
"amount": "0.073033708",
"amountUsd": "6.50"
},
"nextPayoutAt": 1791158400
}Fields
| Field | Type | Description |
|---|---|---|
token | string | The NOTIONAL token's address. |
rewardAsset | string | What rewards are paid in: HYPE. |
stakers | number | Addresses with NOTIONAL staked. |
totalStaked | string | NOTIONAL staked, in whole tokens. |
totalWeight | string | Staked NOTIONAL times each stake's lock multiplier. |
locks | array | One entry per lock: days (0 is flexible), multiplier, staked and apr in percent. |
cooldownDays | number | Days between asking to unstake and withdrawing. |
lastPayout | object or null | The latest weekly payout: paidAt, amount in HYPE and amountUsd. null until the first payout. |
thisWeek | object | The running week's rewards so far: amount in HYPE and amountUsd. |
nextPayoutAt | number | When the running week is paid out, in Unix seconds. |
