API reference · testnet

Info endpoint

Read-only queries. No signature, no account. Each answer is the node's state at the latest block.

All queries are POST /info with a JSON body whose type selects the query. Errors answer 400 with {"error": "…"}. Arrays in the examples are cut to two items.

Market data

`meta`

Perpetual markets: id, name, price tick, size lot, decimals and maximum leverage. Cache it: it changes only with a new market.

Request

{
  "type": "meta"
}

Response

{
  "agentChainId": 1337,
  "network": "functor-testnet (single validator, mock USDC)",
  "universe": [
    {
      "id": 0,
      "lot": 0.001,
      "maxLeverage": 40,
      "name": "BTC",
      "pxDecimals": 0,
      "szDecimals": 3,
      "tick": 1
    },
    {
      "id": 1,
      "lot": 0.01,
      "maxLeverage": 25,
      "name": "ETH",
      "pxDecimals": 1,
      "szDecimals": 2,
      "tick": 0.1
    }
  ]
}

`allMids`

Mark price of every perpetual market, in dollars, keyed by coin.

Request

{
  "type": "allMids"
}

Response

{
  "BTC": 83251,
  "ETH": 2567.2000000000003,
  "SOL": 115.58
}

`marketStats`

Per perpetual market: mark, oracle, open interest (coins), 24-hour volume (coins) and the price 24 hours ago.

Request

{
  "type": "marketStats"
}

Response

[
  {
    "coin": "BTC",
    "dayOpen": 85577,
    "dayVolumeCoins": 0.07,
    "mark": 83251,
    "openInterest": 0.08,
    "oracle": 83219
  },
  {
    "coin": "ETH",
    "dayOpen": 2696.7000000000003,
    "dayVolumeCoins": 0,
    "mark": 2567.2000000000003,
    "openInterest": 0,
    "oracle": 2567.2000000000003
  }
]

`l2Book`

Order book levels, best first: levels[0] bids, levels[1] asks. For FCTR/USDC during an auction, the waiting orders aggregated by price, with auction: true.

Field	Type	Required	Description
`coin`	string \| number	yes	Market name (`BTC`, `ETH`, `SOL`, `FCTR/USDC`; also `FCTR` or `@0`) or id
`nLevels`	number	no	Levels per side, default 20, at most 100

Request

{
  "type": "l2Book",
  "coin": "BTC",
  "nLevels": 2
}

Response

{
  "coin": "BTC",
  "levels": [
    [
      {
        "px": 83203,
        "sz": 0.04
      },
      {
        "px": 83178,
        "sz": 0.04
      }
    ],
    [
      {
        "px": 83237,
        "sz": 0.04
      },
      {
        "px": 83262,
        "sz": 0.04
      }
    ]
  ],
  "time": 1791409364101
}

`recentTrades`

The last 50 trades of a market, newest first. side is the taker's side (B buy, A sell; X for an auction print). mm marks trades with the protocol market maker.

Field	Type	Required	Description
`coin`	string \| number	yes	Market name or id

Request

{
  "type": "recentTrades",
  "coin": "BTC"
}

Response

[
  {
    "liquidation": false,
    "mm": true,
    "px": 83268,
    "side": "B",
    "sz": 0.01,
    "time": 1791408999969
  },
  {
    "liquidation": false,
    "mm": true,
    "px": 83313,
    "side": "B",
    "sz": 0.01,
    "time": 1791408994782
  }
]

`candles`

One-minute candles of the mark price for the last 24 hours (up to 1,440), oldest first. t is the minute's start in ms; v is the volume in coins.

Field	Type	Required	Description
`coin`	string \| number	yes	Market name or id

Request

{
  "type": "candles",
  "coin": "SOL"
}

Response

[
  {
    "c": 121.10000000000001,
    "h": 121.13,
    "l": 121.05,
    "o": 121.08,
    "t": 1791322980000,
    "v": 0
  },
  {
    "c": 121.16,
    "h": 121.16,
    "l": 121.11,
    "o": 121.11,
    "t": 1791323040000,
    "v": 0
  }
]

Account

`clearinghouseState`

Perpetuals account: account value, cash, margins, withdrawable amount and open positions with entry, mark, unrealised PnL, leverage and liquidation price (null when no positive price can liquidate it).

Field	Type	Required	Description
`user`	address	yes	Account address

Request

{
  "type": "clearinghouseState",
  "user": "0xf4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4"
}

Response

{
  "accountValue": 5000072.819724,
  "agentOf": null,
  "cash": 5006732.899724,
  "initialMargin": 19938.008,
  "maintenanceMargin": 83.251,
  "positions": [
    {
      "coin": "BTC",
      "entryPx": 84022.73435,
      "leverage": 10,
      "liquidationPx": 61811517,
      "markPx": 83251,
      "positionValue": 6660.08,
      "size": -0.08,
      "unrealizedPnl": 61.738748
    }
  ],
  "user": "0xf4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4",
  "withdrawable": 4980134.811724
}

`openOrders`

Resting orders on every market, perpetuals and spot. Spot orders carry auction: true while the market is in an auction phase.

Field	Type	Required	Description
`user`	address	yes	Account address

Request

{
  "type": "openOrders",
  "user": "0xf4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4"
}

Response

[
  {
    "coin": "BTC",
    "oid": 1958582,
    "px": 83203,
    "side": "B",
    "sz": 0.04
  },
  {
    "coin": "BTC",
    "oid": 1958583,
    "px": 83237,
    "side": "A",
    "sz": 0.04
  }
]

`userFills`

The account's last 200 fills, perpetuals and spot, newest first. taker is false for maker and auction fills.

Field	Type	Required	Description
`user`	address	yes	Account address

Request

{
  "type": "userFills",
  "user": "0xf4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4"
}

Response

[
  {
    "coin": "BTC",
    "liquidation": false,
    "oid": 1953061,
    "px": 83268,
    "side": "A",
    "sz": 0.01,
    "taker": false,
    "time": 1791408999969
  },
  {
    "coin": "BTC",
    "liquidation": false,
    "oid": 1952531,
    "px": 83313,
    "side": "A",
    "sz": 0.01,
    "taker": false,
    "time": 1791408994782
  }
]

`userRateLimit`

The account's request budget and open-order limit (see Rules). Same first three fields as Hyperliquid's userRateLimit.

Field	Type	Required	Description
`user`	address	yes	Account address

Request

{
  "type": "userRateLimit",
  "user": "0xf4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4"
}

Response

{
  "cumVlm": 3332.75,
  "nCancelsCap": 26664,
  "nRequestsCap": 13332,
  "nRequestsUsed": 0,
  "openOrders": 48,
  "openOrdersCap": 1000
}

`agentOwner`

The account a session key (agent) trades for, or null.

Field	Type	Required	Description
`agent`	address	yes	Session key address

Request

{
  "type": "agentOwner",
  "agent": "0xf4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4"
}

Response

null

Spot and FCTR

`spotMeta`

Spot tokens (USDC, FCTR) and the FCTR/USDC pair: tick, lot, decimals, minimum order.

Request

{
  "type": "spotMeta"
}

Response

{
  "tokens": [
    {
      "index": 0,
      "name": "USDC",
      "note": "mock USDC (testnet)",
      "szDecimals": 2,
      "weiDecimals": 6
    },
    {
      "index": 1,
      "maxSupply": 50000000,
      "name": "FCTR",
      "native": true,
      "szDecimals": 2,
      "weiDecimals": 9
    }
  ],
  "universe": [
    {
      "id": 10000,
      "index": 0,
      "lot": 0.01,
      "minOrder": 1,
      "name": "FCTR/USDC",
      "pxDecimals": 4,
      "szDecimals": 2,
      "tick": 0.0001,
      "tokens": [
        1,
        0
      ]
    }
  ]
}

`spotMarket`

The FCTR/USDC market's phase (collecting, closing, batch, continuous, halted), auction schedule in blocks, indicative opening price, price bands and rules.

Request

{
  "type": "spotMarket"
}

Response

{
  "auctionEndBlock": null,
  "bandNow": 0.05,
  "batchUntil": null,
  "blocksToFreeze": 16795,
  "coin": "FCTR/USDC",
  "dayOpen": null,
  "dayVolume": 0,
  "endWindow": 1200,
  "freezeAt": 57600,
  "height": 40805,
  "indicative": null,
  "lastPx": null,
  "luld": null,
  "openingReference": 1,
  "phase": "collecting",
  "referenceNote": "testnet placeholder used only to break exact ties in the opening auction; not a valuation",
  "reopenAt": null,
  "rules": {
    "bandMaxPct": 20,
    "bandPct": 5,
    "batchBlocks": 1200,
    "breakerPct": 10,
    "breakerWindow": 100,
    "haltBlocks": 20,
    "minOrder": 1,
    "orderBandPct": 20
  },
  "tradeCount": 0
}

`spotClearinghouseState`

Spot balances: USDC (free and held by open bids) and FCTR (held, locked by vesting, spendable).

Field	Type	Required	Description
`user`	address	yes	Account address

Request

{
  "type": "spotClearinghouseState",
  "user": "0xf4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4"
}

Response

{
  "balances": [
    {
      "coin": "USDC",
      "free": 1000000,
      "hold": 0,
      "total": 1000000
    },
    {
      "coin": "FCTR",
      "hold": 0,
      "locked": 0,
      "spendable": 1000000,
      "total": 1000000
    }
  ],
  "user": "0xf4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4"
}

`tokenDetails`

The FCTR ledger: maximum and total supply, burned, circulating (with its formula), every protocol bucket and the founder's vesting schedule.

Request

{
  "type": "tokenDetails"
}

Response

{
  "burned": 0,
  "circulating": 15000,
  "circulatingFormula": "totalSupply − protocol accounts − market maker − faucet pool − founder locked",
  "decimals": 9,
  "founder": {
    "address": "0xf6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6",
    "cliffEndsMs": 1822807287680,
    "locked": 12500000,
    "spendable": 0,
    "total": 12500000,
    "vestEndsMs": 1917415287680,
    "vested": 0
  },
  "genesisTimeMs": 1791271287680,
  "holders": [
    {
      "address": "0xf6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6",
      "balance": 12500000,
      "label": "Founder (25%)",
      "note": "locked by the chain: 12-month cliff, then 36 months linear"
    },
    {
      "address": "0xf5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5",
      "balance": 9985000,
      "label": "Genesis bucket (20%), testnet faucet",
      "note": "mainnet: points holders. Testnet: 1,000 FCTR per address per day"
    }
  ],
  "maxSupply": 50000000,
  "name": "FCTR",
  "network": "functor-testnet: test FCTR, no value",
  "nowMs": 1791409367579,
  "totalSupply": 50000000
}

Vaults

`vaults`

The FLP vaults: equity, share price, return since genesis, depositors, lock-up. With user, adds that account's shares and value.

Field	Type	Required	Description
`user`	address	no	Adds a `user` object

Request

{
  "type": "vaults"
}

Response

[
  {
    "communityOwnedPct": 0.14977504746375112,
    "depositors": 15,
    "equity": 1001503.359884,
    "lockupDays": 4,
    "name": "FLP · Backstop",
    "note": "testnet, mock USDC: returns are from real test-node trading, not a forecast",
    "returnSinceGenesis": 0.000003350000000068576,
    "risk": "Tail risk: a crash that bankrupts large accounts lands here first.",
    "sharePrice": 1.00000335,
    "strategy": "Earns 30% of every trading fee. Takes over accounts in backstop liquidations and unwinds those positions through the book (at most 10% per block, within 1% of the mark). Covers bankrupt accounts' deficits before anyone is auto-deleveraged.",
    "totalShares": "1001499997096",
    "vaultAddress": "0xf1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1",
    "withdrawable": 1001503.359884
  },
  {
    "communityOwnedPct": 0,
    "depositors": 0,
    "equity": 5000072.899724,
    "lockupDays": 4,
    "name": "FLP · Market-making",
    "note": "testnet, mock USDC: returns are from real test-node trading, not a forecast",
    "returnSinceGenesis": 0.000014570000000047045,
    "risk": "Inventory risk: it holds whatever traders sell it while the price moves.",
    "sharePrice": 1.00001457,
    "strategy": "Quotes 8 levels each side on BTC, ETH and SOL around the oracle price, leaning against its inventory. Earns the spread; pays maker fees.",
    "totalShares": "5000000000000",
    "vaultAddress": "0xf4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4",
    "withdrawable": 4980124.659724
  }
]

`vaultDetails`

One vault with its positions and one-minute share-price candles.

Field	Type	Required	Description
`vaultAddress`	address	yes	Vault address
`user`	address	no	Adds a `user` object

Request

{
  "type": "vaultDetails",
  "vaultAddress": "0xf1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1"
}

Response

{
  "candles": [
    {
      "c": 1.0000023,
      "h": 1.0000023,
      "l": 1.0000023,
      "o": 1.0000023,
      "t": 1791322980000
    },
    {
      "c": 1.0000023,
      "h": 1.0000023,
      "l": 1.0000023,
      "o": 1.0000023,
      "t": 1791323040000
    }
  ],
  "communityOwnedPct": 0.14977504746375112,
  "depositors": 15,
  "equity": 1001503.359884,
  "lockupDays": 4,
  "name": "FLP · Backstop",
  "note": "testnet, mock USDC: returns are from real test-node trading, not a forecast",
  "openOrders": 0,
  "positions": [],
  "returnSinceGenesis": 0.000003350000000068576,
  "risk": "Tail risk: a crash that bankrupts large accounts lands here first.",
  "sharePrice": 1.00000335,
  "strategy": "Earns 30% of every trading fee. Takes over accounts in backstop liquidations and unwinds those positions through the book (at most 10% per block, within 1% of the mark). Covers bankrupt accounts' deficits before anyone is auto-deleveraged.",
  "totalShares": "1001499997096",
  "vaultAddress": "0xf1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1",
  "withdrawable": 1001503.359884
}

`userVaultEquities`

The vaults an account holds shares in, with value and lock-up end.

Field	Type	Required	Description
`user`	address	yes	Account address

Request

{
  "type": "userVaultEquities",
  "user": "0xf4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4"
}

Response

[]

Node

`nodeStatus`

Height, block time, state root, last block hash, mempool size, validators and the spot phase. GET /status returns the same plus oracle sources, price age and the deployed version.

Request

{
  "type": "nodeStatus"
}

Response

{
  "height": 40804,
  "lastBlockHash": "0x2d3f75ac3334118ac4ffec8f6501f5349ddfc0135e20d9df97cb6fec1918715e",
  "mempool": 0,
  "spotPhase": "collecting",
  "stateRoot": "0x1febf98118f13a6433fdcc52b6f641db3ba8e9d34df4f7918c1ec7685b31942f",
  "timeMs": 1791409364101,
  "validators": [
    "0xf3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3"
  ]
}

Generated from the node's source code by tools/api-docs.mjs; examples are real responses from https://api.functorfund.com. Questions: Telegram. Changes: News.

Info endpoint

Market data

meta

allMids

marketStats

l2Book

recentTrades

candles

Account

clearinghouseState

openOrders

userFills

userRateLimit

agentOwner

Spot and FCTR

spotMeta

spotMarket

spotClearinghouseState

tokenDetails

Vaults

vaults

vaultDetails

userVaultEquities

Node

nodeStatus

On this page

`meta`

`allMids`

`marketStats`

`l2Book`

`recentTrades`

`candles`

`clearinghouseState`

`openOrders`

`userFills`

`userRateLimit`

`agentOwner`

`spotMeta`

`spotMarket`

`spotClearinghouseState`

`tokenDetails`

`vaults`

`vaultDetails`

`userVaultEquities`

`nodeStatus`