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:

{
  "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:

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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
  • liabilityUsdhb · object · required
    • rootHash · string · required
    • totalMicro · string · unit int · 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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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"
  },
  "liabilityUsdhb": {
    "rootHash": "string",
    "totalMicro": "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 (sats, or USDhb with ?asset=usdhb).

Auth: API key (x-api-key)

Parameters

• asset (query): enum(msat, usdhb)

Responses

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

Markets

GET /v1/markets

All markets (skew quantized §13).

Auth: none (public)

Responses

• 200: OK

Example 200 response:

[
  {
    "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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:

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

---

GET /v1/markets/{id}/stats24h

24h volume + traded hi/lo, derived from fills, including the venue's own USDhb hedge legs.

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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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); volumeContracts counts fills, including the venue's own USDhb hedge legs.

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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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:

{
  "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
  • usdhb · string · optional
  • usdhbPending · string · optional
  • susdhb · string · optional
  • susdhbCooling · string · optional
  • cooling · object[] · optional
    • unstakeId · string · required
    • susdhb · string · required
    • releaseAtMs · string · unit ms · required
• 401: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "accountId": "string",
  "userId": "string",
  "railAddress": "string",
  "autoSweepThresholdMsat": "100000",
  "freeMsat": "100000",
  "reservedMsat": "100000",
  "depositFees": [
    {
      "path": "spark",
      "description": "string",
      "recommendedMinimumSats": "100000"
    }
  ],
  "usdhb": "string",
  "usdhbPending": "string",
  "susdhb": "string",
  "susdhbCooling": "string",
  "cooling": [
    {
      "unstakeId": "string",
      "susdhb": "string",
      "releaseAtMs": "100000"
    }
  ]
}

---

GET /v1/positions

Open positions for the account.

Auth: API key (x-api-key)

Responses

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

Example 200 response:

[
  {
    "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 201 response:

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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

{
  "label": "string",
  "scopes": [
    "read"
  ]
}

Responses

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

Example 201 response:

{
  "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

{
  "keyId": "string",
  "allButCurrent": true
}

Responses

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

Example 200 response:

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 402: Reserved for L402/Lightning-metered access (PAPI-8). Not returned today; documented so it lands additively.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 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

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 401: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 402: Reserved for L402/Lightning-metered access (PAPI-8). Not returned today; documented so it lands additively.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 201 response:

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 404: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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

{
  "timeoutMs": "100000"
}

Responses

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

Example 200 response:

{
  "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

{
  "invoice": "string",
  "toAddress": "string",
  "amountMsat": "100000"
}

Responses

• 200: OK
• 401: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 402: Reserved for L402/Lightning-metered access (PAPI-8). Not returned today; documented so it lands additively.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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

{
  "amountMsat": "100000",
  "toAddress": "string",
  "confirmToken": "string"
}

Responses

• 201: Created
  • railRef · string · required
  • queued · boolean · required
• 401: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 402: Reserved for L402/Lightning-metered access (PAPI-8). Not returned today; documented so it lands additively.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying 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: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 201 response:

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

Usdhb

GET /v1/usdhb

USDhb public state: params, supply, hedge book, reserve vs target, capacity headroom, mints-halted flag (the proof-of-backing payload; no user data).

Auth: none (public)

Responses

• 200: OK
  • tsMs · string · unit ms · required
  • params · object · required
    • baseFeeQ9 · string · unit q9 · required
    • spreadQ9 · string · unit q9 · required
    • reserveTargetQ9 · string · unit q9 · required
    • reserveFloorQ9 · string · unit q9 · required
    • dynFeeCurve · object[] · required
    • hardCap · string · required
    • quoteTtlMs · string · unit ms · required
    • mintVelocityQ9PerH · string · unit q9 · required
    • mintVelocityFloor · string · required
    • requoteToleranceQ9 · string · unit q9 · required
  • supply · string · required
  • hedge · object · required
    • contracts · string · unit contracts · required
    • entryPriceQ8 · string | null · unit q8 · required
    • marginMsat · string · unit msat · required
  • backingIdentityHolds · boolean · required
  • reserveMsat · string · unit msat · required
  • reserveTargetMsat · string | null · unit msat · required
  • reserveFloorMsat · string | null · unit msat · required
  • markQ8 · string | null · unit q8 · required
  • oracleFresh · boolean · required
  • mintedLastHour · string · required
  • redeemedLastHour · string · required
  • capacity · object · required
    • headroom · string | null · required
    • limit · enum(organic_oi, hard_cap, oi_cap, skew, velocity) | null · required
    • perLimit · object | null · required
  • mintsHalted · boolean · required: Halts user mints AND stakes (a stake is a mint-class flow; stakeUsdhb refuses with usdhb_mints_halted). Redemptions, unstake releases and the waterfall's yield mints continue, so supply can move while this is true.
  • mintsHaltedReason · string | null · required
  • lastAttestation · object | null · required
  • features · object · required
    • mint · boolean · required
    • redeem · boolean · required
    • stake · boolean · required
    • withdraw · boolean · required
  • staking · object · required
    • sharePriceQ9 · string · unit q9 · required
    • staked · string · required
    • susdhbSupply · string · required
    • yieldEscrowMsat · string · unit msat · required
    • uncoveredShortfallMsat · string · unit msat · required
    • unstakeCooldownMs · string · unit ms · required
    • lastWaterfall · object | null · required
  • tokenIdentifier · string | null · required
  • freezeCount · integer · required
  • frozenCount · integer · required

Example 200 response:

{
  "tsMs": "100000",
  "params": {
    "baseFeeQ9": "100000",
    "spreadQ9": "100000",
    "reserveTargetQ9": "100000",
    "reserveFloorQ9": "100000",
    "dynFeeCurve": [
      {
        "xQ9": "100000",
        "yQ9": "100000"
      }
    ],
    "hardCap": "string",
    "quoteTtlMs": "100000",
    "mintVelocityQ9PerH": "100000",
    "mintVelocityFloor": "string",
    "requoteToleranceQ9": "100000"
  },
  "supply": "string",
  "hedge": {
    "contracts": "100000",
    "entryPriceQ8": "100000",
    "marginMsat": "100000"
  },
  "backingIdentityHolds": true,
  "reserveMsat": "100000",
  "reserveTargetMsat": "100000",
  "reserveFloorMsat": "100000",
  "markQ8": "100000",
  "oracleFresh": true,
  "mintedLastHour": "string",
  "redeemedLastHour": "string",
  "capacity": {
    "headroom": "string",
    "limit": "organic_oi",
    "perLimit": {
      "organic_oi": "string",
      "hard_cap": "string",
      "oi_cap": "string",
      "skew": "string",
      "velocity": "string"
    }
  },
  "mintsHalted": true,
  "mintsHaltedReason": "string",
  "lastAttestation": {
    "asOfTsMs": "100000",
    "issuerSupply": "string",
    "issuerIssued": "string",
    "issuerBurned": "string",
    "issuerCustody": "string",
    "ledgerSupply": "string",
    "ledgerCustody": "string",
    "ok": true
  },
  "features": {
    "mint": true,
    "redeem": true,
    "stake": true,
    "withdraw": true
  },
  "staking": {
    "sharePriceQ9": "100000",
    "staked": "string",
    "susdhbSupply": "string",
    "yieldEscrowMsat": "100000",
    "uncoveredShortfallMsat": "100000",
    "unstakeCooldownMs": "100000",
    "lastWaterfall": {
      "boundaryTsMs": "100000",
      "markQ8": "100000",
      "flowMsat": "100000",
      "toReserveMsat": "100000",
      "toStakersMsat": "100000",
      "overflowMsat": "100000",
      "shortfallMsat": "100000",
      "markdown": "string",
      "yieldMinted": "string",
      "sharePriceQ9Before": "100000",
      "sharePriceQ9After": "100000"
    }
  },
  "tokenIdentifier": "string",
  "freezeCount": 0,
  "frozenCount": 0
}

---

POST /v1/usdhb/quotes

Price a USDhb mint or redeem (whole units on testnet v1). 409 with the refusal's figures when capacity, the oracle, a halt or dust refuses.

Auth: API key (x-api-key)

Request body

• side · enum(mint, redeem) · required
• usdhb · string · required

{
  "side": "mint",
  "usdhb": "string"
}

Responses

• 201: Created
  • quoteId · string · required
  • side · enum(mint, redeem) · required
  • usdhb · string · required
  • contracts · string · unit contracts · required
  • priceQ8 · string · unit q8 · required
  • spreadQ9 · string · unit q9 · required
  • feeMsat · string · unit msat · required
  • dynFeeMsat · string · unit msat · required
  • impactMsat · string · unit msat · required
  • satsMsat · string · unit msat · required
  • expiresAtMs · string · unit ms · required
  • oracleTsMs · string · unit ms · required
• 401: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 409: Conflict
  • error · string · required
  • code · string · required
  • reason · string · optional
  • headroom · string · optional
  • limit · enum(organic_oi, hard_cap, oi_cap, skew, velocity) · optional
  • quote · object · optional
    • quoteId · string · required
    • side · enum(mint, redeem) · required
    • usdhb · string · required
    • contracts · string · unit contracts · required
    • priceQ8 · string · unit q8 · required
    • spreadQ9 · string · unit q9 · required
    • feeMsat · string · unit msat · required
    • dynFeeMsat · string · unit msat · required
    • impactMsat · string · unit msat · required
    • satsMsat · string · unit msat · required
    • expiresAtMs · string · unit ms · required
    • oracleTsMs · string · unit ms · required
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 201 response:

{
  "quoteId": "string",
  "side": "mint",
  "usdhb": "string",
  "contracts": "100000",
  "priceQ8": "100000",
  "spreadQ9": "100000",
  "feeMsat": "100000",
  "dynFeeMsat": "100000",
  "impactMsat": "100000",
  "satsMsat": "100000",
  "expiresAtMs": "100000",
  "oracleTsMs": "100000"
}

---

POST /v1/usdhb/mints

Accept a mint quote (Idempotency-Key = quoteId). One transaction: sats in, hedge opened, USDhb credited. 409 usdhb_requote carries a fresh quote.

Auth: API key (x-api-key)

Parameters

• idempotency-key (header), required: string

Request body

• quoteId · string · required

{
  "quoteId": "string"
}

Responses

• 201: Created
  • sagaId · string · required
  • side · enum(mint, redeem) · required
  • state · enum(hedging, minted, queued, redeeming, paid) · required
  • usdhb · string · required
  • contracts · string · unit contracts · required
  • satsMsat · string · unit msat · required
  • queuedReason · string | null · required
  • queuedSinceMs · string | null · unit ms · required
  • createdTsMs · string · unit ms · required
  • updatedTsMs · string · unit ms · required
• 401: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 409: Conflict
  • error · string · required
  • code · string · required
  • reason · string · optional
  • headroom · string · optional
  • limit · enum(organic_oi, hard_cap, oi_cap, skew, velocity) · optional
  • quote · object · optional
    • quoteId · string · required
    • side · enum(mint, redeem) · required
    • usdhb · string · required
    • contracts · string · unit contracts · required
    • priceQ8 · string · unit q8 · required
    • spreadQ9 · string · unit q9 · required
    • feeMsat · string · unit msat · required
    • dynFeeMsat · string · unit msat · required
    • impactMsat · string · unit msat · required
    • satsMsat · string · unit msat · required
    • expiresAtMs · string · unit ms · required
    • oracleTsMs · string · unit ms · required
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 201 response:

{
  "sagaId": "string",
  "side": "mint",
  "state": "hedging",
  "usdhb": "string",
  "contracts": "100000",
  "satsMsat": "100000",
  "queuedReason": "string",
  "queuedSinceMs": "100000",
  "createdTsMs": "100000",
  "updatedTsMs": "100000"
}

---

POST /v1/usdhb/redemptions

Accept a redeem quote (Idempotency-Key = quoteId). A withdrawal: works in every halt mode; 202 = queued on a stale oracle, completes at the first fresh price.

Auth: API key (x-api-key)

Parameters

• idempotency-key (header), required: string

Request body

• quoteId · string · required

{
  "quoteId": "string"
}

Responses

• 201: Created
  • sagaId · string · required
  • side · enum(mint, redeem) · required
  • state · enum(hedging, minted, queued, redeeming, paid) · required
  • usdhb · string · required
  • contracts · string · unit contracts · required
  • satsMsat · string · unit msat · required
  • queuedReason · string | null · required
  • queuedSinceMs · string | null · unit ms · required
  • createdTsMs · string · unit ms · required
  • updatedTsMs · string · unit ms · required
• 202: Accepted
  • sagaId · string · required
  • side · enum(mint, redeem) · required
  • state · enum(hedging, minted, queued, redeeming, paid) · required
  • usdhb · string · required
  • contracts · string · unit contracts · required
  • satsMsat · string · unit msat · required
  • queuedReason · string | null · required
  • queuedSinceMs · string | null · unit ms · required
  • createdTsMs · string · unit ms · required
  • updatedTsMs · string · unit ms · required
• 401: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 409: Conflict
  • error · string · required
  • code · string · required
  • reason · string · optional
  • headroom · string · optional
  • limit · enum(organic_oi, hard_cap, oi_cap, skew, velocity) · optional
  • quote · object · optional
    • quoteId · string · required
    • side · enum(mint, redeem) · required
    • usdhb · string · required
    • contracts · string · unit contracts · required
    • priceQ8 · string · unit q8 · required
    • spreadQ9 · string · unit q9 · required
    • feeMsat · string · unit msat · required
    • dynFeeMsat · string · unit msat · required
    • impactMsat · string · unit msat · required
    • satsMsat · string · unit msat · required
    • expiresAtMs · string · unit ms · required
    • oracleTsMs · string · unit ms · required
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 201 response:

{
  "sagaId": "string",
  "side": "mint",
  "state": "hedging",
  "usdhb": "string",
  "contracts": "100000",
  "satsMsat": "100000",
  "queuedReason": "string",
  "queuedSinceMs": "100000",
  "createdTsMs": "100000",
  "updatedTsMs": "100000"
}

---

GET /v1/usdhb/sagas

My mint/redeem sagas, newest first (cursor by createdTsMs).

Auth: API key (x-api-key)

Parameters

• limit (query): string
• beforeTsMs (query): string

Responses

• 200: OK
  • sagas · object[] · required
    • sagaId · string · required
    • side · enum(mint, redeem) · required
    • state · enum(hedging, minted, queued, redeeming, paid) · required
    • usdhb · string · required
    • contracts · string · unit contracts · required
    • satsMsat · string · unit msat · required
    • queuedReason · string | null · required
    • queuedSinceMs · string | null · unit ms · required
    • createdTsMs · string · unit ms · required
    • updatedTsMs · string · unit ms · required
  • nextBeforeTsMs · string | null · unit ms · required
• 401: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "sagas": [
    {
      "sagaId": "string",
      "side": "mint",
      "state": "hedging",
      "usdhb": "string",
      "contracts": "100000",
      "satsMsat": "100000",
      "queuedReason": "string",
      "queuedSinceMs": "100000",
      "createdTsMs": "100000",
      "updatedTsMs": "100000"
    }
  ],
  "nextBeforeTsMs": "100000"
}

---

GET /v1/usdhb/sagas/{id}

One of my mint/redeem sagas (404 for anyone else's).

Auth: API key (x-api-key)

Parameters

• id (path), required: string

Responses

• 200: OK
  • sagaId · string · required
  • side · enum(mint, redeem) · required
  • state · enum(hedging, minted, queued, redeeming, paid) · required
  • usdhb · string · required
  • contracts · string · unit contracts · required
  • satsMsat · string · unit msat · required
  • queuedReason · string | null · required
  • queuedSinceMs · string | null · unit ms · required
  • createdTsMs · string · unit ms · required
  • updatedTsMs · string · unit ms · required
• 401: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "sagaId": "string",
  "side": "mint",
  "state": "hedging",
  "usdhb": "string",
  "contracts": "100000",
  "satsMsat": "100000",
  "queuedReason": "string",
  "queuedSinceMs": "100000",
  "createdTsMs": "100000",
  "updatedTsMs": "100000"
}

---

POST /v1/usdhb/stake

Stake USDhb for sUSDhb shares at the share price (mint-class flow: gated, refuses when mints are halted).

Auth: API key (x-api-key)

Parameters

• idempotency-key (header), required: string

Request body

• usdhb · string · required

{
  "usdhb": "string"
}

Responses

• 201: Created
  • usdhb · string · required
  • susdhb · string · required
  • sharePriceQ9 · string · unit q9 · required
• 401: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 409: Conflict
  • error · string · required
  • code · string · required
  • reason · string · optional
  • headroom · string · optional
  • limit · enum(organic_oi, hard_cap, oi_cap, skew, velocity) · optional
  • quote · object · optional
    • quoteId · string · required
    • side · enum(mint, redeem) · required
    • usdhb · string · required
    • contracts · string · unit contracts · required
    • priceQ8 · string · unit q8 · required
    • spreadQ9 · string · unit q9 · required
    • feeMsat · string · unit msat · required
    • dynFeeMsat · string · unit msat · required
    • impactMsat · string · unit msat · required
    • satsMsat · string · unit msat · required
    • expiresAtMs · string · unit ms · required
    • oracleTsMs · string · unit ms · required
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 201 response:

{
  "usdhb": "string",
  "susdhb": "string",
  "sharePriceQ9": "100000"
}

---

POST /v1/usdhb/unstake

Request an unstake: shares cool for unstakeCooldownMs and release at the share price AT release (a withdrawal-class request; no halt reads).

Auth: API key (x-api-key)

Parameters

• idempotency-key (header), required: string

Request body

• susdhb · string · required

{
  "susdhb": "string"
}

Responses

• 202: Accepted
  • unstakeId · string · required
  • susdhb · string · required
  • requestedTsMs · string · unit ms · required
  • releaseAtMs · string · unit ms · required
  • state · enum(cooling, released) · required
  • releasedUsdhb · string | null · required
  • releasedTsMs · string | null · unit ms · required
• 401: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 409: Conflict
  • error · string · required
  • code · string · required
  • reason · string · optional
  • headroom · string · optional
  • limit · enum(organic_oi, hard_cap, oi_cap, skew, velocity) · optional
  • quote · object · optional
    • quoteId · string · required
    • side · enum(mint, redeem) · required
    • usdhb · string · required
    • contracts · string · unit contracts · required
    • priceQ8 · string · unit q8 · required
    • spreadQ9 · string · unit q9 · required
    • feeMsat · string · unit msat · required
    • dynFeeMsat · string · unit msat · required
    • impactMsat · string · unit msat · required
    • satsMsat · string · unit msat · required
    • expiresAtMs · string · unit ms · required
    • oracleTsMs · string · unit ms · required
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 202 response:

{
  "unstakeId": "string",
  "susdhb": "string",
  "requestedTsMs": "100000",
  "releaseAtMs": "100000",
  "state": "cooling",
  "releasedUsdhb": "string",
  "releasedTsMs": "100000"
}

---

GET /v1/usdhb/unstakes

My unstake requests (cooling and released).

Auth: API key (x-api-key)

Responses

• 200: OK
  • unstakes · object[] · required
    • unstakeId · string · required
    • susdhb · string · required
    • requestedTsMs · string · unit ms · required
    • releaseAtMs · string · unit ms · required
    • state · enum(cooling, released) · required
    • releasedUsdhb · string | null · required
    • releasedTsMs · string | null · unit ms · required
• 401: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "unstakes": [
    {
      "unstakeId": "string",
      "susdhb": "string",
      "requestedTsMs": "100000",
      "releaseAtMs": "100000",
      "state": "cooling",
      "releasedUsdhb": "string",
      "releasedTsMs": "100000"
    }
  ]
}

---

GET /v1/usdhb/activity

My USDhb activity: one entry per applied USDhb money movement (mint, redeem, stake, unstake, off-venue withdrawal/deposit), cursor-paginated on the same global event seq as /v1/fills. Each entry is the WS account frame for that event minus channel.

Auth: API key (x-api-key)

Parameters

• limit (query): string
• beforeSeq (query): string

Responses

• 200: OK
  • activity · any[] · required
  • nextBeforeSeq · string | null · unit seq · required
• 401: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "activity": [
    null
  ],
  "nextBeforeSeq": "100000"
}

---

GET /v1/usdhb/history

Waterfall history: one entry per applied funding boundary (public, newest first).

Auth: none (public)

Parameters

• limit (query): string
• beforeTsMs (query): string

Responses

• 200: OK
  • waterfalls · object[] · required
    • boundaryTsMs · string · unit ms · required
    • markQ8 · string · unit q8 · required
    • flowMsat · string · unit msat · required
    • toReserveMsat · string · unit msat · required
    • toStakersMsat · string · unit msat · required
    • overflowMsat · string · unit msat · required
    • shortfallMsat · string · unit msat · required
    • markdown · string · required
    • yieldMinted · string · required
    • sharePriceQ9Before · string · unit q9 · required
    • sharePriceQ9After · string · unit q9 · required
  • nextBeforeTsMs · string | null · unit ms · required

Example 200 response:

{
  "waterfalls": [
    {
      "boundaryTsMs": "100000",
      "markQ8": "100000",
      "flowMsat": "100000",
      "toReserveMsat": "100000",
      "toStakersMsat": "100000",
      "overflowMsat": "100000",
      "shortfallMsat": "100000",
      "markdown": "string",
      "yieldMinted": "string",
      "sharePriceQ9Before": "100000",
      "sharePriceQ9After": "100000"
    }
  ],
  "nextBeforeTsMs": "100000"
}

---

GET /v1/usdhb/deposit-address

My USDhb receive address on the issuer wallet (allocated on first request). 503 token_rail_unavailable where no token rail is wired.

Auth: API key (x-api-key)

Responses

• 200: OK
  • address · string · required
  • accountNumber · string · unit int · required
  • tokenIdentifier · string | null · required
• 401: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "address": "string",
  "accountNumber": "100000",
  "tokenIdentifier": "string"
}

---

GET /v1/usdhb/withdrawals

My USDhb withdrawals (requested and paid).

Auth: API key (x-api-key)

Responses

• 200: OK
  • withdrawals · object[] · required
    • withdrawalId · string · required
    • usdhb · string · required
    • sparkAddress · string · required
    • state · enum(requested, paid) · required
    • issuerRef · string | null · required
    • requestedTsMs · string · unit ms · required
    • paidTsMs · string | null · unit ms · required
• 401: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "withdrawals": [
    {
      "withdrawalId": "string",
      "usdhb": "string",
      "sparkAddress": "string",
      "state": "requested",
      "issuerRef": "string",
      "requestedTsMs": "100000",
      "paidTsMs": "100000"
    }
  ]
}

---

POST /v1/usdhb/withdrawals

Withdraw USDhb to a Spark address (two-phase: pending -> paid when the custody transfer lands). A withdrawal: no halt reads. 503 where no token rail is wired.

Auth: API key (x-api-key)

Parameters

• idempotency-key (header), required: string

Request body

• usdhb · string · required
• sparkAddress · string · required

{
  "usdhb": "string",
  "sparkAddress": "string"
}

Responses

• 201: Created
  • withdrawalId · string · required
  • usdhb · string · required
  • sparkAddress · string · required
  • state · enum(requested, paid) · required
  • issuerRef · string | null · required
  • requestedTsMs · string · unit ms · required
  • paidTsMs · string | null · unit ms · required
• 401: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 409: Conflict
  • error · string · required
  • code · string · required
  • reason · string · optional
  • headroom · string · optional
  • limit · enum(organic_oi, hard_cap, oi_cap, skew, velocity) · optional
  • quote · object · optional
    • quoteId · string · required
    • side · enum(mint, redeem) · required
    • usdhb · string · required
    • contracts · string · unit contracts · required
    • priceQ8 · string · unit q8 · required
    • spreadQ9 · string · unit q9 · required
    • feeMsat · string · unit msat · required
    • dynFeeMsat · string · unit msat · required
    • impactMsat · string · unit msat · required
    • satsMsat · string · unit msat · required
    • expiresAtMs · string · unit ms · required
    • oracleTsMs · string · unit ms · required
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 201 response:

{
  "withdrawalId": "string",
  "usdhb": "string",
  "sparkAddress": "string",
  "state": "requested",
  "issuerRef": "string",
  "requestedTsMs": "100000",
  "paidTsMs": "100000"
}

---

GET /v1/usdhb/freezes

The public USDhb freeze log (every freeze/unfreeze, newest first, requested until the custody worker applies it) and the addresses currently frozen on-chain.

Auth: none (public)

Responses

• 200: OK
  • freezes · object[] · required
    • seq · string · unit seq · required
    • opId · string | null · required
    • sparkAddress · string · required
    • action · enum(freeze, unfreeze) · required
    • state · enum(requested, applied) · required
    • reason · string | null · required
    • issuerRef · string | null · required
    • impactedMicro · string | null · unit int · required
    • tsMs · string · unit ms · required
    • appliedTsMs · string | null · unit ms · required
    • recovered · boolean · required
  • frozen · string[] · required

Example 200 response:

{
  "freezes": [
    {
      "seq": "100000",
      "opId": "string",
      "sparkAddress": "string",
      "action": "freeze",
      "state": "requested",
      "reason": "string",
      "issuerRef": "string",
      "impactedMicro": "100000",
      "tsMs": "100000",
      "appliedTsMs": "100000",
      "recovered": true
    }
  ],
  "frozen": [
    "string"
  ]
}

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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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

{
  "code": "string"
}

Responses

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

Example 201 response:

{
  "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

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 201 response:

{
  "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

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 201 response:

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

---

GET /v1/promoter

Promoter profile + status.

Auth: API key (x-api-key)

Responses

• 200: OK
• 401: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 404: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 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

{
  "code": "string",
  "label": "string",
  "kickbackQ9": "100000"
}

Responses

• 201: Created
• 401: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 201 response:

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 409: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional

Example 201 response:

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 201 response:

{
  "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:

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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:

{
  "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

{
  "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: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 403: A refusal carrying a stable machine code (ErrorCode) beside human error prose.
  • error · string · required
  • code · ErrorCode · optional
• 429: A token bucket is exhausted.
  • error · string · required
  • code · ErrorCode · optional

Example 200 response:

{
  "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, usdhb_capacity, usdhb_oracle_stale, usdhb_whole_units, usdhb_dust, usdhb_mints_halted, usdhb_requote, usdhb_quote_expired, token_rail_unavailable

---

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