HardBasis

Appearance

REST reference ​

Documents gateway spec version 1.4.0.

Generated from the public OpenAPI spec; the machine-readable source is served at /openapi.json (SDK generators and try-it tools read that). Every money, price, rate, duration and count field crosses the wire as a decimal string, and its unit (x-hardbasis-unit) is shown beside it — see Wire encoding. Base URL and auth are on the Overview and Authentication pages.

System ​

GET /healthz ​

Liveness + DB reachability probe.

Auth: none (public)

Responses

  • 200 — OK
    • ok · boolean · required
    • db · boolean · required
    • tsMs · string · unit ms · required
  • 503 — Service Unavailable
    • ok · boolean · required
    • db · boolean · required
    • tsMs · string · unit ms · required

Example 200 response:

json
{
  "ok": true,
  "db": true,
  "tsMs": "100000"
}

GET /deployment ​

Deployment posture (prod/testnet) — drives the testnet banner.

Auth: none (public)

Responses

  • 200 — OK
    • deployment · enum(prod, testnet) · required

Example 200 response:

json
{
  "deployment": "prod"
}

GET /v1/limits ​

The caller's rate-limit tier + per-budget config and remaining.

Auth: API key (x-api-key)

Responses

  • 200 — OK
    • tier · string · required
    • budgets · map(enum(read, order, withdraw) → object) · required
      • each enum(read, order, withdraw) key → object:
        • limitPerMin · integer · required
        • burst · integer · required
        • remaining · integer · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "tier": "string",
  "budgets": {
    "read": {
      "limitPerMin": 0,
      "burst": 0,
      "remaining": 0
    }
  }
}

Proof of Reserves ​

GET /por ​

Proof-of-Reserves snapshot (figures, staleness, liability root, vault exposure).

Auth: none (public)

Responses

  • 200 — OK
    • tsMs · string · unit ms · required
    • ageMs · string · unit ms · required
    • stale · boolean · required
    • staleAfterMs · string · unit ms · required
    • status · enum(clean, warn, page) · required
    • driftMsat · string · unit msat · required
    • consolidationVerified · boolean · required
    • snapshot · any · required
    • history · object[] · required
      • tsMs · string · unit ms · required
      • status · string · required
      • driftMsat · string · unit msat · required
    • liability · object · required
      • rootHash · string · required
      • totalMsat · string · unit msat · required
      • leafCount · integer · required
      • rootSaltHex · string · required
      • tsMs · string · unit ms · required
    • vaultExposure · object · required
      • netPctOfEquityQ9 · string | null · unit q9 · required
      • quantumQ9 · string · unit q9 · required
      • tsMs · string · unit ms · required
      • consolidationVerified · boolean · required
  • 404 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "tsMs": "100000",
  "ageMs": "100000",
  "stale": true,
  "staleAfterMs": "100000",
  "status": "clean",
  "driftMsat": "100000",
  "consolidationVerified": true,
  "snapshot": null,
  "history": [
    {
      "tsMs": "100000",
      "status": "string",
      "driftMsat": "100000"
    }
  ],
  "liability": {
    "rootHash": "string",
    "totalMsat": "100000",
    "leafCount": 0,
    "rootSaltHex": "string",
    "tsMs": "100000"
  },
  "vaultExposure": {
    "netPctOfEquityQ9": "100000",
    "quantumQ9": "100000",
    "tsMs": "100000",
    "consolidationVerified": true
  }
}

GET /por/dashboard ​

Proof-of-Reserves dashboard (HTML, engine-served).

Auth: none (public)

Responses

  • 200 — OK

GET /v1/por/proof ​

Merkle inclusion proof of the account's liability in the current PoR tree.

Auth: API key (x-api-key)

Responses

  • 200 — OK
    • rootHash · string · required
    • totalMsat · string · unit msat · required
    • rootSaltHex · string · required
    • treeTsMs · string · unit ms · required
    • leaf · object · required
      • accountTag · string · required
      • balanceMsat · string · unit msat · required
      • index · integer · required
    • path · object[] · required
      • siblingHash · string · required
      • siblingSumMsat · string · unit msat · required
      • siblingOnLeft · boolean · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 404 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "rootHash": "string",
  "totalMsat": "100000",
  "rootSaltHex": "string",
  "treeTsMs": "100000",
  "leaf": {
    "accountTag": "string",
    "balanceMsat": "100000",
    "index": 0
  },
  "path": [
    {
      "siblingHash": "string",
      "siblingSumMsat": "100000",
      "siblingOnLeft": true
    }
  ]
}

Markets ​

GET /v1/markets ​

All markets (skew quantized §13).

Auth: none (public)

Responses

  • 200 — OK

Example 200 response:

json
[
  {
    "marketId": "string",
    "underlying": "string",
    "contractType": "inverse",
    "oracleFeedId": "string",
    "quantoMultiplierMsat": "100000",
    "status": "live",
    "tickSizeQ8": "100000",
    "priceDp": "100000",
    "minOrderContracts": "100000",
    "maxOrderContracts": "100000",
    "takerFeeQ9": "100000",
    "maxLeverage": "100000",
    "imRateQ9": "100000",
    "mmRateQ9": "100000",
    "baseSpreadQ9": "100000",
    "fundingRateHourlyQ9": "100000",
    "nextFundingTsMs": "100000",
    "oracleStalenessMs": "100000",
    "openInterestContracts": "100000",
    "skewQ9": "100000",
    "lastPrice": {
      "midQ8": "100000",
      "tsMs": "100000"
    }
  }
]

GET /v1/markets/{id} ​

One market.

Auth: none (public)

Parameters

  • id (path), required — string

Responses

  • 200 — OK
    • marketId · string · required
    • underlying · string · required
    • contractType · enum(inverse, quanto) · required
    • oracleFeedId · string · required
    • quantoMultiplierMsat · string | null · unit msat · required
    • status · enum(live, reduce_only, halted) · required
    • tickSizeQ8 · string · unit q8 · required
    • priceDp · string · unit int · required
    • minOrderContracts · string · unit contracts · required
    • maxOrderContracts · string · unit contracts · required
    • takerFeeQ9 · string · unit q9 · required
    • maxLeverage · string · unit int · required
    • imRateQ9 · string · unit q9 · required
    • mmRateQ9 · string · unit q9 · required
    • baseSpreadQ9 · string · unit q9 · required
    • fundingRateHourlyQ9 · string · unit q9 · required
    • nextFundingTsMs · string · unit ms · required
    • oracleStalenessMs · string · unit ms · required
    • openInterestContracts · string · unit contracts · required
    • skewQ9 · string · unit q9 · required
    • lastPrice · object | null · required
  • 404 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "marketId": "string",
  "underlying": "string",
  "contractType": "inverse",
  "oracleFeedId": "string",
  "quantoMultiplierMsat": "100000",
  "status": "live",
  "tickSizeQ8": "100000",
  "priceDp": "100000",
  "minOrderContracts": "100000",
  "maxOrderContracts": "100000",
  "takerFeeQ9": "100000",
  "maxLeverage": "100000",
  "imRateQ9": "100000",
  "mmRateQ9": "100000",
  "baseSpreadQ9": "100000",
  "fundingRateHourlyQ9": "100000",
  "nextFundingTsMs": "100000",
  "oracleStalenessMs": "100000",
  "openInterestContracts": "100000",
  "skewQ9": "100000",
  "lastPrice": {
    "midQ8": "100000",
    "tsMs": "100000"
  }
}

GET /v1/markets/{id}/funding ​

Last 100 funding boundaries (skew quantized §E).

Auth: none (public)

Parameters

  • id (path), required — string

Responses

  • 200 — OK

Example 200 response:

json
[
  {
    "tsMs": "100000",
    "rateQ9": "100000",
    "skewQ9": "100000"
  }
]

GET /v1/markets/{id}/stats24h ​

24h volume + traded hi/lo, derived from fills.

Auth: none (public)

Parameters

  • id (path), required — string

Responses

  • 200 — OK
    • marketId · string · required
    • windowMs · string · unit ms · required
    • basis · string · required
    • fills · integer · required
    • volumeContracts · string · unit contracts · required
    • hiQ8 · string | null · unit q8 · required
    • loQ8 · string | null · unit q8 · required
    • truncated · boolean · required
  • 404 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "marketId": "string",
  "windowMs": "100000",
  "basis": "string",
  "fills": 0,
  "volumeContracts": "100000",
  "hiQ8": "100000",
  "loQ8": "100000",
  "truncated": true
}

GET /v1/markets/{id}/candles ​

OHLC candles (interval 60, 3600 or 86400).

Auth: none (public)

Parameters

  • id (path), required — string
  • interval (query) — enum(60, 3600, 86400)
  • limit (query) — string

Responses

  • 200 — OK
    • interval · number · required
    • candles · object[] · required
      • tsMs · string · unit ms · required
      • oQ8 · string · unit q8 · required
      • hQ8 · string · unit q8 · required
      • lQ8 · string · unit q8 · required
      • cQ8 · string · unit q8 · required
      • prints · integer · required
      • seeded · boolean · optional
      • volumeContracts · string · unit contracts · optional
  • 404 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "interval": 0,
  "candles": [
    {
      "tsMs": "100000",
      "oQ8": "100000",
      "hQ8": "100000",
      "lQ8": "100000",
      "cQ8": "100000",
      "prints": 0,
      "seeded": true,
      "volumeContracts": "100000"
    }
  ]
}

GET /v1/public/ticker ​

Landing-page ticker (microcached).

Auth: none (public)

Responses

  • 200 — OK
    • asOfMs · string · unit ms · required
    • tickers · object[] · required
      • marketId · string · required
      • last · object | null · required
      • stalenessMs · string · unit ms · required

Example 200 response:

json
{
  "asOfMs": "100000",
  "tickers": [
    {
      "marketId": "string",
      "last": {
        "midQ8": "100000",
        "tsMs": "100000"
      },
      "stalenessMs": "100000"
    }
  ]
}

Account ​

GET /v1/account ​

Account balances, rail address, per-path deposit fees.

Auth: API key (x-api-key)

Responses

  • 200 — OK
    • accountId · string · required
    • userId · string · required
    • railAddress · string · required
    • autoSweepThresholdMsat · string | null · unit msat · required
    • freeMsat · string · unit msat · required
    • reservedMsat · string · unit msat · required
    • depositFees · object[] · required
      • path · enum(spark, l1, lightning) · required
      • description · string · required
      • recommendedMinimumSats · string · unit sats · optional
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "accountId": "string",
  "userId": "string",
  "railAddress": "string",
  "autoSweepThresholdMsat": "100000",
  "freeMsat": "100000",
  "reservedMsat": "100000",
  "depositFees": [
    {
      "path": "spark",
      "description": "string",
      "recommendedMinimumSats": "100000"
    }
  ]
}

GET /v1/positions ​

Open positions for the account.

Auth: API key (x-api-key)

Responses

  • 200 — OK
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
[
  {
    "marketId": "string",
    "side": "long",
    "contracts": "100000",
    "entryPriceQ8": "100000",
    "marginMsat": "100000",
    "fundingClockTsMs": "100000"
  }
]

GET /v1/fills ​

Fills history (cursor-paginated).

Auth: API key (x-api-key)

Parameters

  • limit (query) — string
  • beforeSeq (query) — string

Responses

  • 200 — OK
    • fills · object[] · required
      • orderId · string · required
      • accountId · string · required
      • marketId · string · required
      • side · enum(buy, sell) · required
      • closedContracts · string · unit contracts · required
      • openedContracts · string · unit contracts · required
      • execPriceQ8 · string · unit q8 · required
      • oracle · object · required
      • spreadQ9 · string · unit q9 · required
      • tradeNotionalMsat · string · unit msat · required
      • feeMsat · string · unit msat · required
      • impactMsat · string · unit msat · required
      • rebateDivertedMsat · string · unit msat · required
      • realizedPnlMsat · string · unit msat · required
      • fundingSettledMsat · string · unit msat · required
      • releasedMarginMsat · string · unit msat · required
      • reservedMarginMsat · string · unit msat · required
      • deficitMsat · string · unit msat · required
      • referral · object | null · optional
      • positionAfter · object | null · required
      • seq · string · unit seq · required
      • tsMs · string · unit ms · required
    • nextBeforeSeq · string | null · unit seq · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "fills": [
    {
      "orderId": "string",
      "accountId": "string",
      "marketId": "string",
      "side": "buy",
      "closedContracts": "100000",
      "openedContracts": "100000",
      "execPriceQ8": "100000",
      "oracle": {
        "midQ8": "100000",
        "confQ9": "100000",
        "tsMs": "100000"
      },
      "spreadQ9": "100000",
      "tradeNotionalMsat": "100000",
      "feeMsat": "100000",
      "impactMsat": "100000",
      "rebateDivertedMsat": "100000",
      "realizedPnlMsat": "100000",
      "fundingSettledMsat": "100000",
      "releasedMarginMsat": "100000",
      "reservedMarginMsat": "100000",
      "deficitMsat": "100000",
      "referral": {
        "code": "string",
        "grossFeeMsat": "100000",
        "discountMsat": "100000",
        "rewardMsat": "100000",
        "policyVersion": "100000"
      },
      "positionAfter": {
        "side": "long",
        "contracts": "100000",
        "entryPriceQ8": "100000",
        "marginMsat": "100000"
      },
      "seq": "100000",
      "tsMs": "100000"
    }
  ],
  "nextBeforeSeq": "100000"
}

Deposits ​

POST /v1/deposit-invoices ​

Create a Lightning deposit invoice.

Auth: API key (x-api-key)

Parameters

  • idempotency-key (header), required — string

Request body

  • amountMsat · string · unit msat · optional
  • expirySeconds · integer · optional
  • memo · string · optional
json
{
  "amountMsat": "100000",
  "expirySeconds": 0,
  "memo": "string"
}

Responses

  • 201 — Created
    • invoice · string · required
    • paymentRef · string · required
    • expiresAtMs · string · unit ms · required
    • depositFees · object[] · required
      • path · enum(spark, l1, lightning) · required
      • description · string · required
      • recommendedMinimumSats · string · unit sats · optional
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 201 response:

json
{
  "invoice": "string",
  "paymentRef": "string",
  "expiresAtMs": "100000",
  "depositFees": [
    {
      "path": "spark",
      "description": "string",
      "recommendedMinimumSats": "100000"
    }
  ]
}

GET /v1/deposits ​

Deposit history (cursor-paginated).

Auth: API key (x-api-key)

Parameters

  • limit (query) — string
  • beforeSeq (query) — string

Responses

  • 200 — OK
    • deposits · object[] · required
      • accountId · string · required
      • amountMsat · string · unit msat · required
      • feeMsat · string · unit msat · required
      • railRef · string · required
      • seq · string · unit seq · required
      • tsMs · string · unit ms · required
    • nextBeforeSeq · string | null · unit seq · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "deposits": [
    {
      "accountId": "string",
      "amountMsat": "100000",
      "feeMsat": "100000",
      "railRef": "string",
      "seq": "100000",
      "tsMs": "100000"
    }
  ],
  "nextBeforeSeq": "100000"
}

Sessions & keys ​

GET /v1/sessions ​

The account's live/revoked sessions (never the key value).

Auth: API key (x-api-key)

Responses

  • 200 — OK
    • tsMs · string · unit ms · required
    • sessions · object[] · required
      • keyId · string · required
      • accountId · string · required
      • label · string · required
      • scopes · enum(read, trade, withdraw, admin-sessions)[] · required
      • uaClass · string | null · required
      • ipCountryFirst · string | null · required
      • createdTsMs · string · unit ms · required
      • lastSeenTsMs · string | null · unit ms · required
      • revokedTsMs · string | null · unit ms · required
      • revokedBy · string | null · required
      • revokeReason · string | null · required
      • current · string · unit int · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "tsMs": "100000",
  "sessions": [
    {
      "keyId": "string",
      "accountId": "string",
      "label": "string",
      "scopes": [
        "read"
      ],
      "uaClass": "string",
      "ipCountryFirst": "string",
      "createdTsMs": "100000",
      "lastSeenTsMs": "100000",
      "revokedTsMs": "100000",
      "revokedBy": "string",
      "revokeReason": "string",
      "current": "100000"
    }
  ]
}

POST /v1/sessions ​

Mint a new session key (delegate key primitive).

Auth: API key (x-api-key)

Parameters

  • idempotency-key (header), required — string

Request body

  • label · string · optional
  • scopes · enum(read, trade, withdraw, admin-sessions)[] · optional
json
{
  "label": "string",
  "scopes": [
    "read"
  ]
}

Responses

  • 201 — Created
    • apiKey · string · optional
    • keyId · string · required
    • scopes · enum(read, trade, withdraw, admin-sessions)[] · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 201 response:

json
{
  "apiKey": "string",
  "keyId": "string",
  "scopes": [
    "read"
  ]
}

POST /v1/sessions/revoke ​

Revoke one session or all-but-current.

Auth: API key (x-api-key)

Parameters

  • idempotency-key (header), required — string

Request body

  • keyId · string · optional
  • allButCurrent · boolean · optional
json
{
  "keyId": "string",
  "allButCurrent": true
}

Responses

  • 200 — OK
    • revoked · string[] · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 404 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "revoked": [
    "string"
  ]
}

Liquidations ​

GET /v1/liquidations ​

Liquidation history (cursor-paginated).

Auth: API key (x-api-key)

Parameters

  • limit (query) — string
  • beforeSeq (query) — string

Responses

  • 200 — OK
    • liquidations · object[] · required
      • accountId · string · required
      • positionId · string · required
      • marketId · string · required
      • side · enum(long, short) · required
      • closedContracts · string · unit contracts · required
      • partial · boolean · required
      • execPriceQ8 · string · unit q8 · required
      • oracle · object · required
      • spreadQ9 · string · unit q9 · required
      • realizedPnlMsat · string · unit msat · required
      • fundingSettledMsat · string · unit msat · required
      • penaltyMsat · string · unit msat · required
      • remainderMsat · string · unit msat · optional
      • deficitMsat · string · unit msat · required
      • insuranceCoveredMsat · string · unit msat · required
      • adlTriggered · boolean · required
      • remainingContracts · string · unit contracts · required
      • remainingMarginMsat · string · unit msat · required
      • seq · string · unit seq · required
      • tsMs · string · unit ms · required
    • nextBeforeSeq · string | null · unit seq · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "liquidations": [
    {
      "accountId": "string",
      "positionId": "string",
      "marketId": "string",
      "side": "long",
      "closedContracts": "100000",
      "partial": true,
      "execPriceQ8": "100000",
      "oracle": {
        "midQ8": "100000",
        "confQ9": "100000",
        "tsMs": "100000"
      },
      "spreadQ9": "100000",
      "realizedPnlMsat": "100000",
      "fundingSettledMsat": "100000",
      "penaltyMsat": "100000",
      "remainderMsat": "100000",
      "deficitMsat": "100000",
      "insuranceCoveredMsat": "100000",
      "adlTriggered": true,
      "remainingContracts": "100000",
      "remainingMarginMsat": "100000",
      "seq": "100000",
      "tsMs": "100000"
    }
  ],
  "nextBeforeSeq": "100000"
}

Funding ​

GET /v1/funding ​

Funding-flow history (cursor-paginated).

Auth: API key (x-api-key)

Parameters

  • limit (query) — string
  • beforeSeq (query) — string

Responses

  • 200 — OK
    • funding · object[] · required
      • seq · string · unit seq · required
      • boundaryTsMs · string · unit ms · required
      • marketId · string · required
      • rateQ9 · string · unit q9 · required
      • flowMsat · string · unit msat · required
      • paidMsat · string · unit msat · required
      • positionId · string · required
    • nextBeforeSeq · string | null · unit seq · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "funding": [
    {
      "seq": "100000",
      "boundaryTsMs": "100000",
      "marketId": "string",
      "rateQ9": "100000",
      "flowMsat": "100000",
      "paidMsat": "100000",
      "positionId": "string"
    }
  ],
  "nextBeforeSeq": "100000"
}

Orders ​

GET /v1/orders ​

Orders (optionally ?status= filtered), or ?state=resting|armed triggers (cursor-paginated).

Auth: API key (x-api-key)

Parameters

  • state (query) — enum(resting, armed)
  • status (query) — enum(accepted, filled, canceled, rejected)[]
  • limit (query) — string
  • beforeSeq (query) — string

Responses

  • 200 — OK
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 402 — 402 — reserved for L402/Lightning-metered access (PAPI-8). Not returned today; documented so it lands additively.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

POST /v1/orders ​

Submit an order, bracket, or trigger (idempotency key = order id).

Auth: API key (x-api-key)

Parameters

  • idempotency-key (header), required — string

Request body

  • marketId · string · required
  • side · enum(buy, sell) · required
  • type · enum(market, limit, stop_market, take_profit_market) · required
  • contracts · string · unit contracts · required
  • limitPriceQ8 · string · unit q8 · optional
  • triggerPriceQ8 · string · unit q8 · optional
  • maxSlippageQ9 · string · unit q9 · optional
  • reduceOnly · boolean · required
  • trigger · object · optional
    • kind · enum(entry, stop, take_profit) · required
    • level · string · unit q8 · required
  • bracket · object · optional
    • entryKind · enum(market, trigger) · required
    • entryLevel · string · unit q8 · optional
    • stopLevel · string · unit q8 · optional
    • takeProfitLevel · string · unit q8 · optional
    • stopContracts · string · unit contracts · optional
    • takeProfitContracts · string · unit contracts · optional
json
{
  "marketId": "string",
  "side": "buy",
  "type": "market",
  "contracts": "100000",
  "limitPriceQ8": "100000",
  "triggerPriceQ8": "100000",
  "maxSlippageQ9": "100000",
  "reduceOnly": true,
  "trigger": {
    "kind": "entry",
    "level": "100000"
  },
  "bracket": {
    "entryKind": "market",
    "entryLevel": "100000",
    "stopLevel": "100000",
    "takeProfitLevel": "100000",
    "stopContracts": "100000",
    "takeProfitContracts": "100000"
  }
}

Responses

  • 201 — Created
    • orderId · string · required
    • status · enum(accepted, filled, canceled, rejected, resting, working) · required
  • 400 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 402 — 402 — reserved for L402/Lightning-metered access (PAPI-8). Not returned today; documented so it lands additively.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 201 response:

json
{
  "orderId": "string",
  "status": "accepted"
}

GET /v1/orders/{id} ​

One order's status.

Auth: API key (x-api-key)

Parameters

  • id (path), required — string

Responses

  • 200 — OK
    • orderId · string · required
    • marketId · string · required
    • side · enum(buy, sell) · required
    • type · enum(market, limit, stop_market, take_profit_market) · required
    • contracts · string · unit contracts · required
    • status · enum(accepted, filled, canceled, rejected) · required
    • reason · string | null · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 404 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "orderId": "string",
  "marketId": "string",
  "side": "buy",
  "type": "market",
  "contracts": "100000",
  "status": "accepted",
  "reason": "string"
}

DELETE /v1/orders/{id} ​

Cancel an order / trigger / bracket by id.

Auth: API key (x-api-key)

Parameters

  • id (path), required — string
  • idempotency-key (header), required — string

Responses

  • 200 — OK
    • orderId · string · required
    • canceled · boolean · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "orderId": "string",
  "canceled": true
}

POST /v1/cancel-all-after ​

Dead-man's-switch: arm/refresh/disarm cancel-all-after.

Auth: API key (x-api-key)

Parameters

  • idempotency-key (header), required — string

Request body

  • timeoutMs · string · unit ms · required
json
{
  "timeoutMs": "100000"
}

Responses

  • 200 — OK
    • armed · boolean · required
    • deadlineTsMs · string | null · unit ms · required
  • 400 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "armed": true,
  "deadlineTsMs": "100000"
}

Withdrawals ​

POST /v1/withdrawals/quote ​

Fee quote + wrong-address first-seen check.

Auth: API key (x-api-key)

Request body

  • invoice · string · optional
  • toAddress · string · optional
  • amountMsat · string · unit msat · optional
json
{
  "invoice": "string",
  "toAddress": "string",
  "amountMsat": "100000"
}

Responses

  • 200 — OK
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

GET /v1/withdrawals ​

Withdrawal history (cursor-paginated).

Auth: API key (x-api-key)

Parameters

  • limit (query) — string
  • beforeSeq (query) — string

Responses

  • 200 — OK
    • withdrawals · object[] · required
      • idempotencyKey · string · required
      • amountMsat · string · unit msat · required
      • feeMsat · string | null · unit msat · required
      • state · enum(requested, queued, paid, returned) · required
      • path · enum(spark, lightning) · required
      • queuedReason · string | null · required
      • railRef · string | null · required
      • requestedTsMs · string · unit ms · required
      • paidTsMs · string | null · unit ms · required
    • nextBeforeSeq · string | null · unit seq · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 402 — 402 — reserved for L402/Lightning-metered access (PAPI-8). Not returned today; documented so it lands additively.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "withdrawals": [
    {
      "idempotencyKey": "string",
      "amountMsat": "100000",
      "feeMsat": "100000",
      "state": "requested",
      "path": "spark",
      "queuedReason": "string",
      "railRef": "string",
      "requestedTsMs": "100000",
      "paidTsMs": "100000"
    }
  ],
  "nextBeforeSeq": "100000"
}

POST /v1/withdrawals ​

Withdraw free balance (spark or lightning).

Auth: API key (x-api-key)

Parameters

  • idempotency-key (header), required — string

Request body

  • amountMsat · string · unit msat · required
  • toAddress · string · optional
  • confirmToken · string · optional
json
{
  "amountMsat": "100000",
  "toAddress": "string",
  "confirmToken": "string"
}

Responses

  • 201 — Created
    • railRef · string · required
    • queued · boolean · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 402 — 402 — reserved for L402/Lightning-metered access (PAPI-8). Not returned today; documented so it lands additively.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 428 — Confirmation Required
    • error · string · required
    • code · string · optional
    • reason · string · required
    • firstSeen · boolean · required
    • confirmThresholdMsat · string · unit msat · required
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 201 response:

json
{
  "railRef": "string",
  "queued": true
}

Referral ​

GET /v1/referral ​

The account's referral status.

Auth: API key (x-api-key)

Responses

  • 200 — OK
    • tsMs · string · unit ms · required
    • program · object · required
      • enabled · boolean · required
      • paused · boolean · required
      • policyVersion · string · unit int · required
    • policy · object · required
      • shareQ9 · string · unit q9 · required
      • shareTiers · object[] · required
      • refereeDiscountQ9 · string · unit q9 · required
      • refereeDiscountWindowMs · string · unit ms · required
      • refereeDiscountVolumeCapMsat · string | null · unit msat · required
      • rewardWindowMs · string · unit ms · required
      • holdbackMs · string · unit ms · required
      • minClaimMsat · string · unit msat · required
    • eligibility · object · required
      • eligible · boolean · required
      • gates · object[] · required
    • code · object | null · required
    • referredBy · object | null · required
    • stats · object | null · required
    • bindWindow · object | null · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "tsMs": "100000",
  "program": {
    "enabled": true,
    "paused": true,
    "policyVersion": "100000"
  },
  "policy": {
    "shareQ9": "100000",
    "shareTiers": [
      {
        "minActiveReferees": "100000",
        "shareQ9": "100000"
      }
    ],
    "refereeDiscountQ9": "100000",
    "refereeDiscountWindowMs": "100000",
    "refereeDiscountVolumeCapMsat": "100000",
    "rewardWindowMs": "100000",
    "holdbackMs": "100000",
    "minClaimMsat": "100000"
  },
  "eligibility": {
    "eligible": true,
    "gates": [
      {
        "gate": "string",
        "met": true,
        "requiredMs": "100000",
        "currentMs": "100000",
        "requiredMsat": "100000",
        "currentMsat": "100000",
        "required": "100000",
        "current": "100000"
      }
    ]
  },
  "code": {
    "code": "string",
    "createdTsMs": "100000",
    "disabled": true
  },
  "referredBy": {
    "code": "string",
    "boundTsMs": "100000",
    "discountQ9": "100000",
    "discountExpiresTsMs": "100000",
    "discountVolumeCapMsat": "100000",
    "discountVolumeUsedMsat": "100000",
    "discountActive": true
  },
  "stats": {
    "referees": "100000",
    "activeReferees": "100000",
    "tier": {
      "shareQ9": "100000"
    },
    "lifetimeEarnedMsat": "100000",
    "earned30dMsat": "100000",
    "claimableMsat": "100000",
    "pendingHoldbackMsat": "100000",
    "claimedMsat": "100000",
    "forfeitedMsat": "100000"
  },
  "bindWindow": {
    "openUntilTsMs": "100000"
  }
}

POST /v1/referral/code ​

Create the account's referral code.

Auth: API key (x-api-key)

Parameters

  • idempotency-key (header), required — string

Request body

  • code · string · optional
json
{
  "code": "string"
}

Responses

  • 201 — Created
    • code · string · required
    • createdTsMs · string · unit ms · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 201 response:

json
{
  "code": "string",
  "createdTsMs": "100000"
}

POST /v1/referral/bind ​

Bind to a referrer's code (grace window).

Auth: API key (x-api-key)

Parameters

  • idempotency-key (header), required — string

Request body

  • code · string · required
json
{
  "code": "string"
}

Responses

  • 200 — OK
    • bound · boolean · required
    • referredBy · object · required
      • code · string · required
      • boundTsMs · string · unit ms · required
      • discountQ9 · string · unit q9 · required
      • discountExpiresTsMs · string · unit ms · required
      • discountVolumeCapMsat · string | null · unit msat · required
      • discountVolumeUsedMsat · string · unit msat · required
      • discountActive · boolean · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "bound": true,
  "referredBy": {
    "code": "string",
    "boundTsMs": "100000",
    "discountQ9": "100000",
    "discountExpiresTsMs": "100000",
    "discountVolumeCapMsat": "100000",
    "discountVolumeUsedMsat": "100000",
    "discountActive": true
  }
}

GET /v1/referral/earnings ​

Referral earnings (cursor-paginated).

Auth: API key (x-api-key)

Parameters

  • limit (query) — string
  • beforeSeq (query) — string

Responses

  • 200 — OK
    • earnings · object[] · required
      • seq · string · unit seq · required
      • fillSeq · string | null · unit seq · required
      • tsMs · string · unit ms · required
      • ref · string | null · required
      • grossFeeMsat · string · unit msat · required
      • netFeeMsat · string · unit msat · required
      • shareQ9 · string · unit q9 · required
      • rewardMsat · string · unit msat · required
      • status · enum(accrued, claimed, forfeited) · required
      • epochDay · string · unit ms · required
      • code · string | null · required
    • nextBeforeSeq · string | null · unit seq · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "earnings": [
    {
      "seq": "100000",
      "fillSeq": "100000",
      "tsMs": "100000",
      "ref": "string",
      "grossFeeMsat": "100000",
      "netFeeMsat": "100000",
      "shareQ9": "100000",
      "rewardMsat": "100000",
      "status": "accrued",
      "epochDay": "100000",
      "code": "string"
    }
  ],
  "nextBeforeSeq": "100000"
}

GET /v1/referral/referees ​

The account's referees.

Auth: API key (x-api-key)

Parameters

  • limit (query) — string
  • beforeSeq (query) — string

Responses

  • 200 — OK
    • referees · string · unit int · required
    • nextBeforeSeq · string | null · unit seq · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "referees": "100000",
  "nextBeforeSeq": "100000"
}

POST /v1/referral/claim ​

Claim vested referral rewards.

Auth: API key (x-api-key)

Parameters

  • idempotency-key (header), required — string

Responses

  • 201 — Created
    • claimedMsat · string · unit msat · required
    • accruals · string · unit int · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 201 response:

json
{
  "claimedMsat": "100000",
  "accruals": "100000"
}

Promoter ​

POST /v1/promoter/apply ​

Apply for a promoter profile.

Auth: API key (x-api-key)

Parameters

  • idempotency-key (header), required — string

Request body

  • displayName · string · required
  • channels · object[] · required
    • kind · string · required
    • url · string · required
    • audience · string · required
  • plan · string · required
  • jurisdictions · string[] · required
  • acceptedTermsVersion · string · required
json
{
  "displayName": "string",
  "channels": [
    {
      "kind": "string",
      "url": "string",
      "audience": "string"
    }
  ],
  "plan": "string",
  "jurisdictions": [
    "string"
  ],
  "acceptedTermsVersion": "string"
}

Responses

  • 201 — Created
    • promoterId · string · required
    • status · string · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 201 response:

json
{
  "promoterId": "string",
  "status": "string"
}

GET /v1/promoter ​

Promoter profile + status.

Auth: API key (x-api-key)

Responses

  • 200 — OK
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 404 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

GET /v1/promoter/codes ​

The promoter's codes.

Auth: API key (x-api-key)

Responses

  • 200 — OK
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

POST /v1/promoter/codes ​

Create a promoter code.

Auth: API key (x-api-key)

Parameters

  • idempotency-key (header), required — string

Request body

  • code · string · required
  • label · string · required
  • kickbackQ9 · string · unit q9 · required
json
{
  "code": "string",
  "label": "string",
  "kickbackQ9": "100000"
}

Responses

  • 201 — Created
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

GET /v1/promoter/stats ​

Promoter stats (days window).

Auth: API key (x-api-key)

Parameters

  • days (query) — string

Responses

  • 200 — OK
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

GET /v1/promoter/earnings ​

Promoter earnings (cursor-paginated).

Auth: API key (x-api-key)

Parameters

  • limit (query) — string
  • beforeSeq (query) — string

Responses

  • 200 — OK
    • earnings · object[] · required
      • seq · string · unit seq · required
      • fillSeq · string | null · unit seq · required
      • tsMs · string · unit ms · required
      • ref · string | null · required
      • grossFeeMsat · string · unit msat · required
      • netFeeMsat · string · unit msat · required
      • shareQ9 · string · unit q9 · required
      • rewardMsat · string · unit msat · required
      • status · enum(accrued, claimed, forfeited) · required
      • epochDay · string · unit ms · required
      • code · string | null · required
    • nextBeforeSeq · string | null · unit seq · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "earnings": [
    {
      "seq": "100000",
      "fillSeq": "100000",
      "tsMs": "100000",
      "ref": "string",
      "grossFeeMsat": "100000",
      "netFeeMsat": "100000",
      "shareQ9": "100000",
      "rewardMsat": "100000",
      "status": "accrued",
      "epochDay": "100000",
      "code": "string"
    }
  ],
  "nextBeforeSeq": "100000"
}

POST /v1/promoter/claim ​

Claim vested promoter rewards.

Auth: API key (x-api-key)

Parameters

  • idempotency-key (header), required — string

Responses

  • 201 — Created
    • claimedMsat · string · unit msat · required
    • accruals · string · unit int · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 201 response:

json
{
  "claimedMsat": "100000",
  "accruals": "100000"
}

Onboarding ​

POST /v1/signup ​

Self-serve session (testnet profile only).

Auth: none (public)

Parameters

  • idempotency-key (header), required — string

Responses

  • 201 — Created
    • apiKey · string · required
    • accountId · string · required
    • railAddress · string · required
    • referredBy · object · optional
      • code · string · required
      • boundTsMs · string · unit ms · required
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 409 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional

Example 201 response:

json
{
  "apiKey": "string",
  "accountId": "string",
  "railAddress": "string",
  "referredBy": {
    "code": "string",
    "boundTsMs": "100000"
  }
}

POST /v1/faucet ​

Testnet faucet grant (rate-limited).

Auth: API key (x-api-key)

Parameters

  • idempotency-key (header), required — string

Responses

  • 201 — Created
    • creditedMsat · string · unit msat · required
    • grantsRemainingThisHour · integer · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 201 response:

json
{
  "creditedMsat": "100000",
  "grantsRemainingThisHour": 0
}

Leaderboard ​

GET /v1/leaderboard ​

A leaderboard board (?board=pnl|roi&window=7d|30d|all&limit=). Bounded.

Auth: none (public)

Parameters

  • board (query) — enum(pnl, roi)
  • window (query) — enum(7d, 30d, all)
  • limit (query) — string

Responses

  • 200 — OK
    • board · enum(pnl, roi) · required
    • window · enum(7d, 30d, all) · required
    • rows · object[] · required
      • rank · string · unit int · required
      • handle · string · required
      • displayName · string | null · required
      • pnlMsat · string · unit msat · required
      • roiQ9 · string · unit q9 · required
      • volumeContracts · string · unit contracts · required
      • trades · string · unit int · required
      • winRateQ9 · string | null · unit q9 · required
      • maxDrawdownQ9 · string · unit q9 · required
    • computedTsMs · string | null · unit ms · required
    • cadenceMinutes · string · unit int · required
    • gates · object · required
      • minEquityMsat · string · unit msat · required
      • minTrades · string · unit int · required
      • minVolumeContracts · string · unit contracts · required
    • windows · enum(7d, 30d, all)[] · optional
    • testnet · boolean · required

Example 200 response:

json
{
  "board": "pnl",
  "window": "7d",
  "rows": [
    {
      "rank": "100000",
      "handle": "string",
      "displayName": "string",
      "pnlMsat": "100000",
      "roiQ9": "100000",
      "volumeContracts": "100000",
      "trades": "100000",
      "winRateQ9": "100000",
      "maxDrawdownQ9": "100000"
    }
  ],
  "computedTsMs": "100000",
  "cadenceMinutes": "100000",
  "gates": {
    "minEquityMsat": "100000",
    "minTrades": "100000",
    "minVolumeContracts": "100000"
  },
  "windows": [
    "7d"
  ],
  "testnet": true
}

GET /v1/leaderboard/me ​

The caller's own placements + per-window eligibility checklist.

Auth: API key (x-api-key)

Responses

  • 200 — OK
    • optedOut · boolean · required
    • handle · string | null · required
    • displayName · string | null · required
    • placements · object[] · required
      • board · enum(pnl, roi) · required
      • window · enum(7d, 30d, all) · required
      • rank · string · unit int · required
      • pnlMsat · string · unit msat · required
      • roiQ9 · string · unit q9 · required
      • volumeContracts · string · unit contracts · required
      • trades · string · unit int · required
      • winRateQ9 · string | null · unit q9 · required
      • maxDrawdownQ9 · string · unit q9 · required
    • eligibility · object[] · required
      • window · enum(7d, 30d, all) · required
      • eligible · boolean · required
      • reason · enum(gates_failed, insufficient_history, coverage_gap, window_unserved) | null · optional
      • eligibleAtMs · string | null · unit ms · optional
      • checks · object[] · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "optedOut": true,
  "handle": "string",
  "displayName": "string",
  "placements": [
    {
      "board": "pnl",
      "window": "7d",
      "rank": "100000",
      "pnlMsat": "100000",
      "roiQ9": "100000",
      "volumeContracts": "100000",
      "trades": "100000",
      "winRateQ9": "100000",
      "maxDrawdownQ9": "100000"
    }
  ],
  "eligibility": [
    {
      "window": "7d",
      "eligible": true,
      "reason": "gates_failed",
      "eligibleAtMs": "100000",
      "checks": [
        {
          "gate": "string",
          "ok": true,
          "thresholdMsat": "100000",
          "threshold": "100000",
          "valueMsat": "100000",
          "value": "100000"
        }
      ]
    }
  ]
}

GET /v1/leaderboard/trader/{handle} ​

A public trader profile (404 for opted-out OR unknown, indistinguishably).

Auth: none (public)

Parameters

  • handle (path), required — string

Responses

  • 200 — OK
    • handle · string · required
    • displayName · string | null · required
    • tradingSince · string | null · required
    • placements · object[] · required
      • board · enum(pnl, roi) · required
      • window · enum(7d, 30d, all) · required
      • rank · string · unit int · required
      • pnlMsat · string · unit msat · required
      • roiQ9 · string · unit q9 · required
      • volumeContracts · string · unit contracts · required
      • trades · string · unit int · required
      • winRateQ9 · string | null · unit q9 · required
      • maxDrawdownQ9 · string · unit q9 · required
    • equityCurve · object[] · required
      • dayTsMs · string · unit ms · required
      • indexQ9 · string · unit q9 · required
    • testnet · boolean · required

Example 200 response:

json
{
  "handle": "string",
  "displayName": "string",
  "tradingSince": "string",
  "placements": [
    {
      "board": "pnl",
      "window": "7d",
      "rank": "100000",
      "pnlMsat": "100000",
      "roiQ9": "100000",
      "volumeContracts": "100000",
      "trades": "100000",
      "winRateQ9": "100000",
      "maxDrawdownQ9": "100000"
    }
  ],
  "equityCurve": [
    {
      "dayTsMs": "100000",
      "indexQ9": "100000"
    }
  ],
  "testnet": true
}

GET /v1/leaderboard/trader/{handle}/og.png ​

Server-rendered 1200×630 Open Graph share card (PNG) for a profile, from the same quantized cache (ETag on the recompute stamp; 404 for opted-out OR unknown, indistinguishably).

Auth: none (public)

Parameters

  • handle (path), required — string

Responses

  • 200 — OK

POST /v1/leaderboard/settings ​

Opt-out/in + display-name claim (own public identity).

Auth: API key (x-api-key)

Parameters

  • idempotency-key (header), required — string

Request body

  • optedOut · boolean · optional
  • displayName · string | null · optional
json
{
  "optedOut": true,
  "displayName": "string"
}

Responses

  • 200 — OK
    • optedOut · boolean · required
    • handle · string | null · required
    • displayName · string | null · required
    • placements · object[] · required
      • board · enum(pnl, roi) · required
      • window · enum(7d, 30d, all) · required
      • rank · string · unit int · required
      • pnlMsat · string · unit msat · required
      • roiQ9 · string · unit q9 · required
      • volumeContracts · string · unit contracts · required
      • trades · string · unit int · required
      • winRateQ9 · string | null · unit q9 · required
      • maxDrawdownQ9 · string · unit q9 · required
    • eligibility · object[] · required
      • window · enum(7d, 30d, all) · required
      • eligible · boolean · required
      • reason · enum(gates_failed, insufficient_history, coverage_gap, window_unserved) | null · optional
      • eligibleAtMs · string | null · unit ms · optional
      • checks · object[] · required
  • 401 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 403 — Refusal — a stable machine code (ErrorCode) beside human error prose.
    • error · string · required
    • code · ErrorCode · optional
  • 429 — 429 — a token bucket is exhausted.
    • error · string · required
    • code · ErrorCode · optional

Example 200 response:

json
{
  "optedOut": true,
  "handle": "string",
  "displayName": "string",
  "placements": [
    {
      "board": "pnl",
      "window": "7d",
      "rank": "100000",
      "pnlMsat": "100000",
      "roiQ9": "100000",
      "volumeContracts": "100000",
      "trades": "100000",
      "winRateQ9": "100000",
      "maxDrawdownQ9": "100000"
    }
  ],
  "eligibility": [
    {
      "window": "7d",
      "eligible": true,
      "reason": "gates_failed",
      "eligibleAtMs": "100000",
      "checks": [
        {
          "gate": "string",
          "ok": true,
          "thresholdMsat": "100000",
          "threshold": "100000",
          "valueMsat": "100000",
          "value": "100000"
        }
      ]
    }
  ]
}

Schemas ​

Types referenced by the fields above.

ErrorCode ​

Enum — one of: validation, unauthorized, insufficient_scope, compliance_refused, session_limit, referral_forbidden, not_found, idempotency_key_reused, conflict, confirmation_required, rate_limited, feature_unavailable, deposits_halted, unavailable, insufficient_balance, insufficient_margin, position_limit, oi_cap, reduce_only, market_halted, oracle_stale, body_too_large

FundingHistoryEntry ​

  • tsMs · string · unit ms · required
  • rateQ9 · string · unit q9 · required
  • skewQ9 · string · unit q9 · required

OrdersPage ​

  • orders · object[] · required
    • orderId · string · required
    • marketId · string · required
    • side · enum(buy, sell) · required
    • type · enum(market, limit, stop_market, take_profit_market) · required
    • contracts · string · unit contracts · required
    • status · enum(accepted, filled, canceled, rejected) · required
    • reason · string | null · required
  • nextBeforeSeq · string | null · unit seq · required

Position ​

  • marketId · string · required
  • side · enum(long, short) · required
  • contracts · string · unit contracts · required
  • entryPriceQ8 · string · unit q8 · required
  • marginMsat · string · unit msat · required
  • fundingClockTsMs · string · unit ms · required

PublicMarket ​

  • marketId · string · required
  • underlying · string · required
  • contractType · enum(inverse, quanto) · required
  • oracleFeedId · string · required
  • quantoMultiplierMsat · string | null · unit msat · required
  • status · enum(live, reduce_only, halted) · required
  • tickSizeQ8 · string · unit q8 · required
  • priceDp · string · unit int · required
  • minOrderContracts · string · unit contracts · required
  • maxOrderContracts · string · unit contracts · required
  • takerFeeQ9 · string · unit q9 · required
  • maxLeverage · string · unit int · required
  • imRateQ9 · string · unit q9 · required
  • mmRateQ9 · string · unit q9 · required
  • baseSpreadQ9 · string · unit q9 · required
  • fundingRateHourlyQ9 · string · unit q9 · required
  • nextFundingTsMs · string · unit ms · required
  • oracleStalenessMs · string · unit ms · required
  • openInterestContracts · string · unit contracts · required
  • skewQ9 · string · unit q9 · required
  • lastPrice · object | null · required

TriggersPage ​

  • triggers · object[] · required
    • orderId · string · required
    • marketId · string · required
    • kind · enum(entry, stop, take_profit) · required
    • side · enum(buy, sell) · required
    • contracts · string · unit contracts · required
    • triggerPriceQ8 · string · unit q8 · required
    • reduceOnly · boolean · required
    • status · enum(resting, armed, blocked, executed, cancelled) · required
    • reason · string | null · required
    • ocoGroup · string | null · required
  • nextBeforeSeq · string | null · unit seq · required

Program policy v1 · numbers current as of 2026-08-28

Testnet — test sats have no value. Nothing on this page is an offer, a solicitation, or advice.

Program policy v1 · numbers current as of 2026-08-28
Testnet — test sats have no value. Nothing here is an offer, a solicitation, or advice.

HardBasis