API reference · testnet

WebSocket

Live updates without polling. Subscribe once; the node pushes after every block.

Connect

wss://api.functorfund.com/ws

Send JSON text messages. Each message from the node has a channel and data.

Every connection also receives a block message for each block, whatever it subscribed to:

{
  "channel": "block",
  "data": {
    "height": 40806,
    "timeMs": 1791409370830,
    "stateRoot": "0x7363592fb3f1a888a83e3f09d5bf15376c8586bf0706aa27724d8eb2fea18b03",
    "fills": 0
  }
}

Errors (bad JSON, too many subscriptions, rate limit) arrive on the error channel:

{
  "channel": "error",
  "data": "not JSON"
}

Subscriptions

l2Book

Book levels (20 per side), every block. Parameter: coin.

Message

{
  "channel": "l2Book",
  "data": {
    "coin": "BTC",
    "levels": [
      [
        {
          "px": 83248,
          "sz": 0.04
        },
        {
          "px": 83223,
          "sz": 0.04
        }
      ],
      [
        {
          "px": 83282,
          "sz": 0.04
        },
        {
          "px": 83307,
          "sz": 0.04
        }
      ]
    ],
    "time": 1791409367579
  }
}

trades

Recent trades of the market, every block. Parameter: coin.

Message

{
  "channel": "trades",
  "data": {
    "coin": "BTC",
    "trades": [
      {
        "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
      }
    ]
  }
}

user

Account state, open orders, last 50 fills and spot balances, every block. Parameter: user.

Message

{
  "channel": "user",
  "data": {
    "user": "0xf4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4",
    "state": {
      "accountValue": 5000072.899724,
      "agentOf": null,
      "cash": 5006732.899724,
      "initialMargin": 19948.24,
      "maintenanceMargin": 83.25,
      "positions": [
        {
          "coin": "BTC",
          "entryPx": 84022.73435,
          "leverage": 10,
          "liquidationPx": 61811517,
          "markPx": 83250,
          "positionValue": 6660,
          "size": -0.08,
          "unrealizedPnl": 61.818748
        }
      ],
      "user": "0xf4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4",
      "withdrawable": 4980124.659724
    },
    "openOrders": [
      {
        "coin": "BTC",
        "oid": 1958630,
        "px": 83248,
        "side": "B",
        "sz": 0.04
      },
      {
        "coin": "BTC",
        "oid": 1958631,
        "px": 83282,
        "side": "A",
        "sz": 0.04
      }
    ],
    "fills": [
      {
        "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
      }
    ],
    "spot": {
      "balances": [
        {
          "coin": "USDC",
          "free": 1000000,
          "hold": 0,
          "total": 1000000
        },
        {
          "coin": "FCTR",
          "hold": 0,
          "locked": 0,
          "spendable": 1000000,
          "total": 1000000
        }
      ],
      "user": "0xf4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4"
    }
  }
}

allMids

Per-market mark, oracle, open interest and 24-hour figures (the marketStats answer), every block. Parameter: none.

Message

{
  "channel": "allMids",
  "data": [
    {
      "coin": "BTC",
      "dayOpen": 85577,
      "dayVolumeCoins": 0.07,
      "mark": 83250,
      "openInterest": 0.08,
      "oracle": 83264
    },
    {
      "coin": "ETH",
      "dayOpen": 2696.7000000000003,
      "dayVolumeCoins": 0,
      "mark": 2568.4,
      "openInterest": 0,
      "oracle": 2568.4
    }
  ]
}

spotMarket

The FCTR/USDC market state (the spotMarket answer), every block. Parameter: none.

Message

{
  "channel": "spotMarket",
  "data": {
    "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
  }
}

Limits

Per IP: 10 connections, 30 new connections a minute, 1,000 subscriptions (20 per connection), 10 distinct users, 2,000 messages a minute. See Rules.

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.