FLOOR / API

For Developers

Getting started

Overview

Base URL
https://floor.supply/api/v1
Methods
GET only. Answers are JSON.
Data
Launches, trades, candles, holders and vesting locks on every chain FLOOR serves.
Spec
/api/v1/openapi.json
curl -s "https://floor.supply/api/v1/launches?sort=volume" \
  -H "Authorization: Bearer $FLOOR_API_KEY"

Authentication

Header
Authorization: Bearer <key>
Key in the URL
400 key_in_query
Browsers
Server-side only. Browser requests are blocked (no CORS).

Keys and scopes

ScopeReads
launches:readthe chains, the launch list and one launch
trades:reada launch's pool trades and candles
holders:reada launch's holders and vesting locks, and a wallet's vesting locks
Get a key
Ask FLOOR on X. A key is shown once.
IP allowlist
Optional, per key.
Rotation
The old key stops within 30 s.

Responses

Success
{ data, meta }
Error
{ error: { code, message }, meta }
meta.requestId
Quote it when you report a problem.
null
Not read, or no USD rate. 0 is a real zero.

Success

{
  "data": "…",
  "meta": {
    "requestId": "req_01J9EXAMPLE"
  }
}

Error

{
  "error": {
    "code": "invalid_key",
    "message": "The API key is not valid."
  },
  "meta": {
    "requestId": "req_01J9EXAMPLE"
  }
}

Endpoints

Chains

GET/api/v1/chains

The networks this API serves. Scope launches:read.

curl -s "https://floor.supply/api/v1/chains" \
  -H "Authorization: Bearer $FLOOR_API_KEY"

Response · 200

{
  "data": [
    {
      "id": "base",
      "name": "Base",
      "family": "evm",
      "chainId": 8453,
      "chainKey": "eip155:8453",
      "nativeAsset": "ETH",
      "testnet": false
    }
  ],
  "meta": {
    "requestId": "req_01J9EXAMPLE"
  }
}

Launches

GET/api/v1/launches

Launches, ranked, paged by cursor. Scope launches:read.

Query parameters

sortvolume · mcap · age · backed · default volume
volume: 24h volume in USD. mcap: market cap in USD. age: newest first. backed: floor ÷ price.
statusall · bonding · graduated · default all
chainstring
Comma-separated network ids.
cursorstring
meta.nextCursor of the previous page, exactly as served. Carries its query: no other parameter with it. A long cursor may be a short handle valid for the key that received it for 15 minutes; past that, 400 cursor_expired: start again from the first page.
curl -s "https://floor.supply/api/v1/launches?sort=volume" \
  -H "Authorization: Bearer $FLOOR_API_KEY"

Response · 200

{
  "data": [
    {
      "chain": "base",
      "address": "0x5eA1000000000000000000000000000000000B1d",
      "launchId": "42",
      "name": "Seal",
      "symbol": "SEAL",
      "tokenDecimals": 18,
      "phase": "graduated",
      "mode": "floor-amm:1",
      "preset": {
        "id": 1,
        "name": "WAGMI"
      },
      "platformToken": false,
      "createdAt": 1790000000,
      "deployer": "0x1111111111111111111111111111111111111111",
      "quote": {
        "symbol": "ETH",
        "address": null,
        "decimals": 18,
        "listed": true
      },
      "quoteChain": [],
      "priceCheck": {
        "offPrice": false,
        "statedUsd": 3000,
        "marketUsd": 3004.12
      },
      "supply": {
        "total": "999000000000000000000000000",
        "circulating": "268000000000000000000000000",
        "locked": "50000000000000000000000000",
        "burned": "1000000000000000000000000"
      },
      "info": {
        "imageUrl": "https://floor.supply/media/launch/base/seal-avatar.webp?v=3",
        "bannerUrl": "https://floor.supply/media/launch/base/seal-banner.webp?v=3",
        "description": "A seal on the floor.",
        "website": "https://seal.example",
        "x": "https://x.com/sealonfloor",
        "telegram": "https://t.me/sealonfloor"
      },
      "liquidity": {
        "floor": {
          "quote": "780000000000000000000",
          "usd": 1872000
        },
        "cushion": {
          "quote": "120000000000000000000",
          "usd": 288000
        },
        "pol": {
          "quote": "185000000000000000000",
          "usd": 444000
        },
        "totalQuote": "1085000000000000000000",
        "totalUsd": 2604000
      },
      "market": {
        "priceUsd": 0.0142,
        "priceQuote": 0.00000592,
        "floorPriceUsd": 0.0089,
        "floorPriceQuote": 0.00000371,
        "backedPct": 62.7,
        "marketCapUsd": 14185800,
        "volume24hUsd": 1737000,
        "volume1hUsd": 86000,
        "volumeLifetimeUsd": 9420000,
        "priceChange1h": 0.031,
        "priceChange24h": -0.042,
        "high24hQuote": 0.00000631,
        "low24hQuote": 0.00000548,
        "buys24h": 412,
        "sells24h": 167,
        "liquidityUsd": 2604000,
        "priceUsdDeclared": 0.0142,
        "holders": 2841
      },
      "bonding": null,
      "stack": {
        "inventory": "310000000000000000000000000",
        "ended": null
      },
      "fees": {
        "backingFeeBuyPct": 1,
        "backingFeeSellPct": 1,
        "backingFeeBuyAtFloorPct": 1,
        "backingFeeSellAtFloorPct": 1,
        "teamShareBuyPct": 0.5,
        "teamShareSellPct": 0.5,
        "platformFeePct": 0.25,
        "floorTokenFeePct": 0.25
      },
      "milestones": {
        "teamPct": 0.5,
        "platformPct": 0.25,
        "floorTokenPct": 0.25
      },
      "teamSlot": {
        "ratePct": 0.5
      },
      "floorTokenOwed": {
        "accruedQuote": "4200000000000000000",
        "deliveredQuote": "4000000000000000000",
        "pendingQuote": "200000000000000000",
        "pendingUsd": 480
      },
      "referrals": {
        "traderPctOfPlatformFee": [
          30,
          20,
          10
        ],
        "creatorPctOfTeamShare": [
          9,
          0.9,
          0.1
        ]
      },
      "path": "/launch/base:0x5eA1000000000000000000000000000000000B1d"
    }
  ],
  "meta": {
    "requestId": "req_01J9EXAMPLE",
    "asOf": 1790003600,
    "nextCursor": "fp_eyJzb3J0Ijoidm9sdW1lIiwic3RhdHVzIjoiYWxsIiwib2Zmc2V0cyI6eyJiYXNlIjo0OH19",
    "partial": []
  }
}

Batch

GET/api/v1/launches/batch

Many launches in one call, in the order asked. Scope launches:read.

Query parameters

idsstring
Up to 50 comma-separated `network:token` ids (base:0x…,sol:…). A launch not shown is named in meta.missing; a network not read, in meta.unavailable. supply carries the total only: one launch answers the circulating figure.
curl -s "https://floor.supply/api/v1/launches/batch?ids=$CHAIN:$TOKEN" \
  -H "Authorization: Bearer $FLOOR_API_KEY"

Response · 200

{
  "data": [
    {
      "chain": "base",
      "address": "0x5eA1000000000000000000000000000000000B1d",
      "launchId": "42",
      "name": "Seal",
      "symbol": "SEAL",
      "tokenDecimals": 18,
      "phase": "graduated",
      "mode": "floor-amm:1",
      "preset": {
        "id": 1,
        "name": "WAGMI"
      },
      "platformToken": false,
      "createdAt": 1790000000,
      "deployer": "0x1111111111111111111111111111111111111111",
      "quote": {
        "symbol": "ETH",
        "address": null,
        "decimals": 18,
        "listed": true
      },
      "quoteChain": [],
      "priceCheck": {
        "offPrice": false,
        "statedUsd": 3000,
        "marketUsd": 3004.12
      },
      "supply": {
        "total": "999000000000000000000000000",
        "circulating": "268000000000000000000000000",
        "locked": "50000000000000000000000000",
        "burned": "1000000000000000000000000"
      },
      "info": {
        "imageUrl": "https://floor.supply/media/launch/base/seal-avatar.webp?v=3",
        "bannerUrl": "https://floor.supply/media/launch/base/seal-banner.webp?v=3",
        "description": "A seal on the floor.",
        "website": "https://seal.example",
        "x": "https://x.com/sealonfloor",
        "telegram": "https://t.me/sealonfloor"
      },
      "liquidity": {
        "floor": {
          "quote": "780000000000000000000",
          "usd": 1872000
        },
        "cushion": {
          "quote": "120000000000000000000",
          "usd": 288000
        },
        "pol": {
          "quote": "185000000000000000000",
          "usd": 444000
        },
        "totalQuote": "1085000000000000000000",
        "totalUsd": 2604000
      },
      "market": {
        "priceUsd": 0.0142,
        "priceQuote": 0.00000592,
        "floorPriceUsd": 0.0089,
        "floorPriceQuote": 0.00000371,
        "backedPct": 62.7,
        "marketCapUsd": 14185800,
        "volume24hUsd": 1737000,
        "volume1hUsd": 86000,
        "volumeLifetimeUsd": 9420000,
        "priceChange1h": 0.031,
        "priceChange24h": -0.042,
        "high24hQuote": 0.00000631,
        "low24hQuote": 0.00000548,
        "buys24h": 412,
        "sells24h": 167,
        "liquidityUsd": 2604000,
        "priceUsdDeclared": 0.0142,
        "holders": 2841
      },
      "bonding": null,
      "stack": {
        "inventory": "310000000000000000000000000",
        "ended": null
      },
      "fees": {
        "backingFeeBuyPct": 1,
        "backingFeeSellPct": 1,
        "backingFeeBuyAtFloorPct": 1,
        "backingFeeSellAtFloorPct": 1,
        "teamShareBuyPct": 0.5,
        "teamShareSellPct": 0.5,
        "platformFeePct": 0.25,
        "floorTokenFeePct": 0.25
      },
      "milestones": {
        "teamPct": 0.5,
        "platformPct": 0.25,
        "floorTokenPct": 0.25
      },
      "teamSlot": {
        "ratePct": 0.5
      },
      "floorTokenOwed": {
        "accruedQuote": "4200000000000000000",
        "deliveredQuote": "4000000000000000000",
        "pendingQuote": "200000000000000000",
        "pendingUsd": 480
      },
      "referrals": {
        "traderPctOfPlatformFee": [
          30,
          20,
          10
        ],
        "creatorPctOfTeamShare": [
          9,
          0.9,
          0.1
        ]
      },
      "path": "/launch/base:0x5eA1000000000000000000000000000000000B1d"
    }
  ],
  "meta": {
    "requestId": "req_01J9EXAMPLE",
    "asOf": 1790003600,
    "missing": [],
    "unavailable": []
  }
}

One launch

GET/api/v1/launches/{chain}/{token}

One launch. Scope launches:read.

Path parameters

chainstring
Network id.
tokenstring
Token address.
curl -s "https://floor.supply/api/v1/launches/$CHAIN/$TOKEN" \
  -H "Authorization: Bearer $FLOOR_API_KEY"

Response · 200

{
  "data": {
    "chain": "base",
    "address": "0x5eA1000000000000000000000000000000000B1d",
    "launchId": "42",
    "name": "Seal",
    "symbol": "SEAL",
    "tokenDecimals": 18,
    "phase": "graduated",
    "mode": "floor-amm:1",
    "preset": {
      "id": 1,
      "name": "WAGMI"
    },
    "platformToken": false,
    "createdAt": 1790000000,
    "deployer": "0x1111111111111111111111111111111111111111",
    "quote": {
      "symbol": "ETH",
      "address": null,
      "decimals": 18,
      "listed": true
    },
    "quoteChain": [],
    "priceCheck": {
      "offPrice": false,
      "statedUsd": 3000,
      "marketUsd": 3004.12
    },
    "supply": {
      "total": "999000000000000000000000000",
      "circulating": "268000000000000000000000000",
      "locked": "50000000000000000000000000",
      "burned": "1000000000000000000000000"
    },
    "info": {
      "imageUrl": "https://floor.supply/media/launch/base/seal-avatar.webp?v=3",
      "bannerUrl": "https://floor.supply/media/launch/base/seal-banner.webp?v=3",
      "description": "A seal on the floor.",
      "website": "https://seal.example",
      "x": "https://x.com/sealonfloor",
      "telegram": "https://t.me/sealonfloor"
    },
    "liquidity": {
      "floor": {
        "quote": "780000000000000000000",
        "usd": 1872000
      },
      "cushion": {
        "quote": "120000000000000000000",
        "usd": 288000
      },
      "pol": {
        "quote": "185000000000000000000",
        "usd": 444000
      },
      "totalQuote": "1085000000000000000000",
      "totalUsd": 2604000
    },
    "market": {
      "priceUsd": 0.0142,
      "priceQuote": 0.00000592,
      "floorPriceUsd": 0.0089,
      "floorPriceQuote": 0.00000371,
      "backedPct": 62.7,
      "marketCapUsd": 14185800,
      "volume24hUsd": 1737000,
      "volume1hUsd": 86000,
      "volumeLifetimeUsd": 9420000,
      "priceChange1h": 0.031,
      "priceChange24h": -0.042,
      "high24hQuote": 0.00000631,
      "low24hQuote": 0.00000548,
      "buys24h": 412,
      "sells24h": 167,
      "liquidityUsd": 2604000,
      "priceUsdDeclared": 0.0142,
      "holders": 2841
    },
    "bonding": null,
    "stack": {
      "inventory": "310000000000000000000000000",
      "ended": null
    },
    "fees": {
      "backingFeeBuyPct": 1,
      "backingFeeSellPct": 1,
      "backingFeeBuyAtFloorPct": 1,
      "backingFeeSellAtFloorPct": 1,
      "teamShareBuyPct": 0.5,
      "teamShareSellPct": 0.5,
      "platformFeePct": 0.25,
      "floorTokenFeePct": 0.25
    },
    "milestones": {
      "teamPct": 0.5,
      "platformPct": 0.25,
      "floorTokenPct": 0.25
    },
    "teamSlot": {
      "ratePct": 0.5
    },
    "floorTokenOwed": {
      "accruedQuote": "4200000000000000000",
      "deliveredQuote": "4000000000000000000",
      "pendingQuote": "200000000000000000",
      "pendingUsd": 480
    },
    "referrals": {
      "traderPctOfPlatformFee": [
        30,
        20,
        10
      ],
      "creatorPctOfTeamShare": [
        9,
        0.9,
        0.1
      ]
    },
    "path": "/launch/base:0x5eA1000000000000000000000000000000000B1d"
  },
  "meta": {
    "requestId": "req_01J9EXAMPLE",
    "asOf": 1790003600,
    "indexedAt": 1790003598
  }
}

Trades

GET/api/v1/launches/{chain}/{token}/trades

Trades, newest first. Scope trades:read. A launch still in its sale has no pool: 409 no_pool.

Path parameters

chainstring
Network id.
tokenstring
Token address.

Query parameters

limit1–100 · default 50
beforestring
meta.nextBefore of the previous page (a trade's position).
curl -s "https://floor.supply/api/v1/launches/$CHAIN/$TOKEN/trades?limit=50" \
  -H "Authorization: Bearer $FLOOR_API_KEY"

Response · 200

{
  "data": [
    {
      "time": 1790003600,
      "side": "buy",
      "tokenAmount": 35210.4,
      "quoteAmount": 0.21,
      "priceQuote": 0.00000597,
      "floorPriceQuote": 0.00000371,
      "trader": "0x4444444444444444444444444444444444444444",
      "txHash": "0x5555555555555555555555555555555555555555555555555555555555555555",
      "block": 21004211,
      "position": "21004211:3:7"
    }
  ],
  "meta": {
    "requestId": "req_01J9EXAMPLE",
    "indexedAt": 1790003598,
    "quote": "ETH",
    "nextBefore": "21004211:3:7"
  }
}

Candles

GET/api/v1/launches/{chain}/{token}/candles

OHLCV in the quote asset, oldest first. Scope trades:read. A launch still in its sale has no pool: 409 no_pool.

Path parameters

chainstring
Network id.
tokenstring
Token address.

Query parameters

bucket60 · 300 · 900 · 3600 · 14400 · 86400 · default 3600
limit1–300 · default 100
beforeinteger
Unix seconds.
curl -s "https://floor.supply/api/v1/launches/$CHAIN/$TOKEN/candles?bucket=3600" \
  -H "Authorization: Bearer $FLOOR_API_KEY"

Response · 200

{
  "data": [
    {
      "time": 1790000000,
      "open": 0.00000581,
      "high": 0.00000612,
      "low": 0.00000577,
      "close": 0.00000597,
      "volumeQuote": 4.82
    }
  ],
  "meta": {
    "requestId": "req_01J9EXAMPLE",
    "indexedAt": 1790003598,
    "quote": "ETH",
    "bucket": 3600,
    "nextBefore": 1790000000
  }
}

Holders

GET/api/v1/launches/{chain}/{token}/holders

Holders, largest first, protocol addresses labelled. Scope holders:read.

Path parameters

chainstring
Network id.
tokenstring
Token address.

Query parameters

limit1–100 · default 50
offset0–10000 · default 0
curl -s "https://floor.supply/api/v1/launches/$CHAIN/$TOKEN/holders?limit=50" \
  -H "Authorization: Bearer $FLOOR_API_KEY"

Response · 200

{
  "data": [
    {
      "address": "0x6666666666666666666666666666666666666666",
      "balance": "12000000000000000000000000",
      "sharePct": 1.2,
      "isProtocol": false,
      "role": null,
      "firstSeenAt": 1790000000
    }
  ],
  "meta": {
    "requestId": "req_01J9EXAMPLE",
    "indexedAt": 1790003598,
    "totalSupply": "1000000000000000000000000000",
    "holderCount": 2841,
    "tokenDecimals": 18
  }
}

Locks

GET/api/v1/launches/{chain}/{token}/locks

A launch's vesting locks, newest first, with totals. DEGRADED until v2: answers 503 `degraded`. Scope holders:read.

Path parameters

chainstring
Network id.
tokenstring
Token address.

Query parameters

limit1–100 · default 50
beforestring
meta.nextBefore of the previous page. meta.totals covers every lock of the token (count, amount, claimed, base units), not only the page.
curl -s "https://floor.supply/api/v1/launches/$CHAIN/$TOKEN/locks?limit=50" \
  -H "Authorization: Bearer $FLOOR_API_KEY"

Response · 200

{
  "data": [
    {
      "id": "42",
      "token": "0x5eA1000000000000000000000000000000000B1d",
      "beneficiary": "0x6666666666666666666666666666666666666666",
      "locker": "0x1111111111111111111111111111111111111111",
      "floorLaunch": true,
      "amount": "50000000000000000000000000",
      "claimed": "10000000000000000000000000",
      "vested": "25000000000000000000000000",
      "claimable": "15000000000000000000000000",
      "unvested": "25000000000000000000000000",
      "start": 1790000000,
      "cliff": 1792592000,
      "end": 1805552000,
      "shape": "cliffGate",
      "txHash": "0x7777777777777777777777777777777777777777777777777777777777777777",
      "block": 21000042
    }
  ],
  "meta": {
    "requestId": "req_01J9EXAMPLE",
    "indexedAt": 1790003598,
    "asOf": 1790003600,
    "totals": {
      "locks": 3,
      "amount": "120000000000000000000000000",
      "claimed": "10000000000000000000000000"
    },
    "tokenDecimals": 18,
    "nextBefore": null
  }
}

Locks

GET/api/v1/wallets/{chain}/{wallet}/locks

A wallet's vesting locks, newest first. DEGRADED until v2: answers 503 `degraded`. Scope holders:read.

Path parameters

chainstring
Network id.
walletstring
Wallet address.

Query parameters

rolebeneficiary · locker · default beneficiary
beneficiary: locks that vest to the wallet. locker: locks the wallet made.
limit1–100 · default 50
beforestring
meta.nextBefore of the previous page.
curl -s "https://floor.supply/api/v1/wallets/$CHAIN/$WALLET/locks?role=beneficiary" \
  -H "Authorization: Bearer $FLOOR_API_KEY"

Response · 200

{
  "data": [
    {
      "id": "42",
      "token": "0x5eA1000000000000000000000000000000000B1d",
      "beneficiary": "0x6666666666666666666666666666666666666666",
      "locker": "0x1111111111111111111111111111111111111111",
      "floorLaunch": true,
      "amount": "50000000000000000000000000",
      "claimed": "10000000000000000000000000",
      "vested": "25000000000000000000000000",
      "claimable": "15000000000000000000000000",
      "unvested": "25000000000000000000000000",
      "start": 1790000000,
      "cliff": 1792592000,
      "end": 1805552000,
      "shape": "cliffGate",
      "txHash": "0x7777777777777777777777777777777777777777777777777777777777777777",
      "block": 21000042
    }
  ],
  "meta": {
    "requestId": "req_01J9EXAMPLE",
    "indexedAt": 1790003598,
    "asOf": 1790003600,
    "nextBefore": null
  }
}

Reference

Rate limits

TierBurstPer second
standard1205
partner60030
Over the limit
429 rate_limited with Retry-After.
Failed auth
10 attempts per IP, then one every 10 s: 429 too_many_failures.

Errors

Branch on error.code.

Paging

Launches
Pass meta.nextCursor as cursor. null is the last page.
Trades, candles
Pass meta.nextBefore as before.
Holders
offset and limit.
Expiry
A cursor can expire after 15 min: 400 cursor_expired. Start again from the first page.

Reading the numbers

floorPriceUsd
The floor: the launch's backing ÷ its circulating supply, where the program buys back. In the quote asset it never moves down.
backedPct
Floor ÷ price, as a percentage.
fees
The launch's own rates, fixed at its creation.
indexedAt
The indexer time a launch read was taken at. An indexer that is behind answers 503 upstream_unavailable.
Times
Unix seconds.
balance
Base units, as a decimal string.

SDKs

SDKs

FLOOR
One program per chain, on Solana and on every EVM chain: a launch trades against the program itself.
Package
@floor/sdk
Status
Not released yet. This page describes the first release.
Scope
Read a launch, quote, buy and sell, create and claim. No dependencies: bring your own RPC client and wallet.
Amounts
Bigints in base units.

Modules

Read a launch

EVM
readLaunch reads every view at one block, in one eth_call.
Solana
launchFromAccount turns a Launch account into the quoter's state.
Quote
quoteBuy and quoteSell run the program's own math on that state.
import { readLaunch } from '@floor/sdk/evm/floor/market';
import { displayFloor } from '@floor/sdk/quote';

// publicClient: a viem PublicClient. floorAmm: the chain's FloorAmm address.
// launchId: the launch's id (a bigint).
const ethCall = async (c) => (await publicClient.call({ to: c.to, data: c.data })).data ?? '0x';

// Every view at one block, in one eth_call (Multicall3).
const { launch, liveSupply } = await readLaunch(ethCall, floorAmm, launchId);
const { floorX64, priceX64, sOut } = displayFloor(launch);