notional

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.

EndpointReturns
GET/coinsCoins launched on notional, newest first or sorted.
GET/coins/{address}One coin, in full.
GET/coins/{address}/tradesA coin's trades, newest first.
GET/coins/{address}/holdersWho holds a coin, largest first.
GET/coins/{address}/candlesPrice candles for a coin's chart.
GET/poolsNLP pools with their liquidity, volume and APR.
GET/pools/{address}One NLP pool, in full.
GET/pools/{address}/transactionsSwaps, deposits and withdrawals in a pool, newest first.
GET/statsTotals across notional: users, volume, fees and liquidity.
GET/stakingWhat is staked, under which locks, and the rewards.

List coins

GET/coins

Coins launched on notional, a page at a time.

Query parameters

ParameterTypeDescription
sortstringcreated, newest first, is the default. marketCap, volume24h and change24h sort largest first.
pairstringOnly coins that trade against this asset, such as HYPE, USDC or GME.
graduatedbooleantrue for graduated coins only, false for coins still on their curve.
limitintegerItems per page, 1 to 100. Default 50.
cursorstringThe nextCursor of the previous page.
Request
curl "https://api.notinal.xyz/v1/coins?sort=marketCap&limit=2"
Response
{
  "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

FieldTypeDescription
addressstringThe coin's contract address.
symbolstringIts ticker. Tickers are not unique; the address is.
namestringIts name.
pairstringThe symbol of the asset it trades against: HYPE, USDC or a stock.
imagestringThe URL of its image.
creatorstringThe address that launched it.
createdAtnumberWhen it launched, in Unix seconds.
priceUsdstringThe price of one coin, in USD.
marketCapUsdstringThe price times the supply of 1,000,000,000.
volume24hUsdstringUSD traded over the last 24 hours.
change24hnumberThe price change over the last 24 hours, in percent.
holdersnumberAddresses holding any of the coin.
curveProgressnumberHow much of the curve has sold, 0 to 100. 100 once graduated.
graduatedbooleanWhether the coin has moved from its curve to a HyperSwap pool.

Get a coin

GET/coins/{address}

One coin with its description, links and market. Returns 404 if no coin was launched at the address.

Path parameters

ParameterTypeDescription
addressstringThe coin's contract address.
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
}

Fields

Everything in the coin object, and:

FieldTypeDescription
descriptionstringThe creator's description. Empty if none was given.
linksobjectx, telegram and website: URLs, or null when not set.
supplystringThe total supply, in whole coins. Always 1,000,000,000.
pricePairstringThe price of one coin in its pair asset.
liquidityUsdstringWhat backs the price, in USD: the curve's reserve, or the pool's after graduation.
creatorFeesUsdstringFees paid to the creator so far, in USD.
graduationPoolstring or nullThe HyperSwap pool the coin's liquidity is locked in. null until it graduates.

List a coin's trades

GET/coins/{address}/trades

A coin's trades, on its curve and, after graduation, in its pool. Newest first.

Parameters

ParameterTypeDescription
addressstringThe coin's contract address.
sidestringbuy or sell. Both if left out.
traderstringOnly trades by this address.
limitintegerItems per page, 1 to 100. Default 50.
cursorstringThe nextCursor of the previous page.
Request
curl "https://api.notinal.xyz/v1/coins/0x7e57000000000000000000000000000000000005/trades?limit=3"
Response
{
  "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

FieldTypeDescription
timenumberWhen the trade was made, in Unix seconds.
sidestringbuy or sell, from the trader's side.
coinAmountstringCoins bought or sold.
pairAmountstringThe pair asset paid for them, or received for them.
priceUsdstringThe coin's price at the trade, in USD.
valueUsdstringWhat the trade was worth, in USD.
traderstringThe address that traded.
txstringThe transaction hash.

List a coin's holders

GET/coins/{address}/holders

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

ParameterTypeDescription
addressstringThe coin's contract address.
limitintegerItems per page, 1 to 100. Default 50.
cursorstringThe nextCursor of the previous page.
Request
curl "https://api.notinal.xyz/v1/coins/0x7e57000000000000000000000000000000000005/holders?limit=3"
Response
{
  "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

FieldTypeDescription
holdersnumberHow many addresses hold the coin in all.
addressstringThe holding address.
labelstring or nullBonding curve, Pool or Creator; null for everyone else.
balancestringCoins held.
sharenumberThe share of the supply held, in percent.

Get a coin's candles

GET/coins/{address}/candles

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

ParameterTypeDescription
addressstringThe coin's contract address.
intervalstring1m, 5m, 15m or 1h. Default 5m.
fromnumberThe earliest candle to return, in Unix seconds.
tonumberThe latest candle to return, in Unix seconds. Default now.
limitintegerCandles to return, 1 to 500, counting back from to. Default 500.
Request
curl "https://api.notinal.xyz/v1/coins/0x7e57000000000000000000000000000000000005/candles?interval=5m&to=1790992500&limit=3"
Response
{
  "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

FieldTypeDescription
timenumberThe start of the candle, in Unix seconds.
open, high, low, closestringThe coin's price in USD over the candle.
volumeUsdstringUSD traded during the candle.

List pools

GET/pools

NLP pools, a page at a time.

Query parameters

ParameterTypeDescription
sortstringtvl is the default. volume24h, apr and created sort largest or newest first.
kindstringvolatile, stable or stock.
tokenstringOnly pools holding this token, by symbol, such as HYPE.
limitintegerItems per page, 1 to 100. Default 50.
cursorstringThe nextCursor of the previous page.
Request
curl "https://api.notinal.xyz/v1/pools?sort=tvl&limit=2"
Response
{
  "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

FieldTypeDescription
addressstringThe pool's contract address.
kindstringvolatile, stable or stock.
base, quoteobjectThe two tokens: symbol, name, priceUsd, and reserve, how much of it the pool holds.
feeBpsnumberThe fee on every swap, in basis points: 30 is 0.30%.
pricestringOne base token, priced in the quote token.
tvlUsdstringThe value of everything in the pool, in USD.
volume24hUsdstringUSD swapped over the last 24 hours.
fees24hUsdstringFees paid by swaps over the last 24 hours, in USD.
aprnumberThe last 24 hours of fees, all of which go to liquidity providers, times 365, over the TVL, in percent.
createdAtnumberWhen the pool was created, in Unix seconds.

Get a pool

GET/pools/{address}

One NLP pool, with a week of volume and fees. Returns 404 if there is no NLP pool at the address.

Path parameters

ParameterTypeDescription
addressstringThe pool's contract address.
Request
curl https://api.notinal.xyz/v1/pools/0x7197b1af3521b92ed8f1ce8dba175cdd55373388
Response
{
  "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:

FieldTypeDescription
tickSpacingnumberThe step between prices a range can start or end at. It is set by the fee tier.
volume7dUsdstringUSD swapped over the last 7 days.
fees7dUsdstringFees paid over the last 7 days, in USD.
swaps24hnumberSwaps over the last 24 hours.

List a pool's transactions

GET/pools/{address}/transactions

Swaps, deposits and withdrawals in a pool, newest first.

Parameters

ParameterTypeDescription
addressstringThe pool's contract address.
typestringswap, add or remove. All three if left out.
accountstringOnly transactions by this address.
limitintegerItems per page, 1 to 100. Default 50.
cursorstringThe nextCursor of the previous page.
Request
curl "https://api.notinal.xyz/v1/pools/0x7197b1af3521b92ed8f1ce8dba175cdd55373388/transactions?limit=3"
Response
{
  "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

FieldTypeDescription
typestringswap, add for a deposit, or remove for a withdrawal.
timenumberWhen it happened, in Unix seconds.
accountstringThe address that sent it.
baseAmount, quoteAmountstringHow much of each token moved, from the pool's side: positive into the pool, negative out of it.
valueUsdstringWhat it was worth, in USD.
txstringThe 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.

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

FieldTypeDescription
asOfnumberThe moment the numbers describe, in Unix seconds.
usersnumberAddresses that have traded, provided liquidity or staked.
transactionsnumberTransactions sent to notional's contracts.
coinsLaunched, coinsGraduatednumberCoins launched, and how many graduated.
tvlUsdstringEverything held in NLP pools, in USD.
volume24hUsd, fees24hUsdstringVolume over the last 24 hours, and every fee traders paid on it.
volumeUsdobjectAll-time volume: total, and its launchpad and nlp parts.
feesUsdobjectAll-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.
feeSplitobjectHow 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.

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

FieldTypeDescription
tokenstringThe NOTIONAL token's address.
rewardAssetstringWhat rewards are paid in: HYPE.
stakersnumberAddresses with NOTIONAL staked.
totalStakedstringNOTIONAL staked, in whole tokens.
totalWeightstringStaked NOTIONAL times each stake's lock multiplier.
locksarrayOne entry per lock: days (0 is flexible), multiplier, staked and apr in percent.
cooldownDaysnumberDays between asking to unstake and withdrawing.
lastPayoutobject or nullThe latest weekly payout: paidAt, amount in HYPE and amountUsd. null until the first payout.
thisWeekobjectThe running week's rewards so far: amount in HYPE and amountUsd.
nextPayoutAtnumberWhen the running week is paid out, in Unix seconds.

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.