API Reference

Signer Endpoints (Authenticated)

All signer endpoints require X-Api-Key. The state-changing endpoints (/v1/submit, /v1/trades) additionally require the full HMAC envelope (X-Signature + X-Timestamp). Each endpoint below lists its exact auth requirement. See Authentication for header details, signing algorithm, and rate limits.

POST /v1/keys

Auth: X-Api-Key only.

Create or retrieve a delegated keypair for a user.

Request:

{"user_id": "your-internal-user-id"}

Response:

{"user_id": "user-123", "public_key": "7yQ3mH9a..."}

The public_key is deterministic -- same user_id always returns the same key.

POST /v1/submit

Auth: X-Api-Key + X-Signature + X-Timestamp (full HMAC envelope).

Sign and submit an order in one call. This is the primary trading endpoint.

Request:

{
  "user": "7yQ3mH9a...",
  "market_id": "abc123def456...",
  "side": "buy",
  "outcome": "yes",
  "price": 6500,
  "size": 100,
  "order_type": "gtc",
  "nonce": 1,
  "fee_bps": 100
}

Field	Type	Description
`user`	string	User's public key (from `/v1/keys`)
`market_id`	string	Hex-encoded 32-byte market ID
`side`	`"buy"` or `"sell"`
`outcome`	`"yes"` or `"no"`
`price`	int	1-9999 basis points (5000 = $0.50)
`size`	int	Number of contracts
`order_type`	string	`"gtc"`, `"ioc"`, `"fok"`, `"post_only"`
`nonce`	int	Monotonically increasing per user
`fee_bps`	int	Your builder fee in basis points (optional, default 0)

Response:

{
  "order_id": 42,
  "market_id": "abc123...",
  "fills": [
    {
      "quantity": 50,
      "price": 6200,
      "taker_fee": 7,
      "maker_rebate": 0,
      "builder_fee": 31,
      "builder_api_key": "pk_live_...",
      "settlement_type": "mint",
      "outcome": "yes",
      "taker_side": "buy",
      "maker_side": "sell",
      "maker": "11111111111111111111111111111111",
      "taker": "7yQ3mH9a...",
      "maker_order_id": 10,
      "taker_order_id": 42,
      "timestamp": 1700000000
    }
  ],
  "remaining": 50
}

!!! note "Fill Field Naming" Live order fills returned by /v1/submit and /v1/orders use quantity and timestamp. The historical /v1/trades/{user} and /v1/markets/{id}/trades REST endpoints return size and time instead. Client code should handle both forms when unifying data sources.

Market Orders

To place a "market" order (fill immediately at best available price), use ioc with an extreme price:

Market Buy: { "side": "buy", "price": 9999, "order_type": "ioc" } — fills at best asks
Market Sell: { "side": "sell", "price": 100, "order_type": "ioc" } — fills at best bids

The remaining field in the response indicates any unfilled portion (which is automatically cancelled for IOC orders).

Canonical Order Message (for client-side signing)

If you are signing orders yourself (not using the signer's delegated key), the Ed25519 signature must be computed over this exact 90-byte layout:

market_id   32 bytes
user        32 bytes
outcome      1 byte   (0 = yes, 1 = no)
side         1 byte   (0 = buy, 1 = sell)
price        8 bytes  (u64 little-endian, basis points)
size         8 bytes  (u64 little-endian, contracts)
nonce        8 bytes  (u64 little-endian)

Total: 90 bytes. This format is shared verbatim between the frontend wallet, the builder signer, and the engine's signature verification — any deviation will be rejected.

POST /v1/sign

Auth: X-Api-Key only.

Sign an order without submitting. Returns the signature for you to submit to the gateway yourself.

Same request body as /v1/submit.

Response:

{"signature": "deadbeef...", "message_hash": "abc123..."}

POST /v1/deposit/address

Auth: X-Api-Key only.

Get a deposit address for a user. Returns the user's deterministic proxy wallet PDA.

Request:

{"user": "7yQ3mH9a...", "chain": "solana"}

Supported chains: "solana", "fogo"

Response:

{
  "chain": "solana",
  "address": "4xR2kF...",
  "instructions": "Send native SOL or USDC (SPL token) to this address on Solana. Native SOL is credited at a fixed testnet rate (1 SOL = 150 USDC). USDC is credited 1:1. Deposits are detected automatically.",
  "initialized": true,
  "usdc_token": "EPjFWdd5..."
}

Staging vs Production:

Environment	Solana Chain	Fogo Chain	Native Tokens
Staging	Solana Devnet	Fogo Testnet	Accepted at 1 SOL/FOGO = 150 USDC
Production	Solana Mainnet	Fogo Mainnet (via Wormhole)	USDC only

Calling this endpoint auto-registers the user's proxy wallet with the deposit monitor, so any subsequent transfers are automatically detected and credited.

POST /v1/trades

Auth: X-Api-Key + X-Signature + X-Timestamp (full HMAC envelope).

Get your builder's trade history and fee revenue.

Request:

{"limit": 100, "market_id": "abc123..."}

All fields optional.

Response:

{
  "trades": [...],
  "total_builder_fees": 15000,
  "total_protocol_fees": 3750,
  "user_count": 42
}

Only returns trades from users created through your API key.

Gateway Endpoints (Public, No Auth)

Read market data directly from the gateway. No API key needed.

GET /v1/markets

Every entry has event_id + outcomes[]. Binary = 1 outcome. Multi = N outcomes. Use market_id from outcomes when placing orders.

{
  "markets": [
    {
      "event_id": "abc123...",
      "question": "Will BTC reach $200k?",
      "category": {"name": "crypto", "sub": "bitcoin"},
      "status": "active",
      "fee_bps": 25,
      "expiry": 1798761600,
      "outcomes": [
        {"label": "Yes", "market_id": "def456...", "yes_price": 7200, "yes_bid": 7000, "yes_ask": 7400}
      ]
    }
  ]
}

GET /v1/events

List all events (multi-outcome markets grouped under one question).

GET /v1/events/{id}

Event details with per-outcome prices.

GET /v1/markets/{id}

Single market with full price data.

GET /v1/markets/{id}/book

Full order book snapshot (yes/no bids and asks).

GET /v1/markets/{id}/trades?limit=100&before=500

Trade history for a market. Cursor-paginated, newest first.

GET /v1/markets/{id}/candles?interval=5m&from=0&to=9999999999

OHLCV candlestick data. Intervals: 1m, 5m, 15m, 1h, 1d.

GET /v1/balance/{public_key}

User's balance (available, locked, total) in micro-USDC.

GET /v1/position/{market_id}/{public_key}

User's position in a market (yes_contracts, no_contracts).

GET /v1/trades/{public_key}

User's trade history across all markets.

GET /v1/fees

Public fee schedule -- all categories, rates, and builder info.

POST /v1/orders/cancel

Cancel a single order.

{"market_id": "abc...", "order_id": 42, "user": "7yQ...", "signature": "..."}

POST /v1/orders/cancel-all

Cancel all orders for a user. Optional market_id to scope to a single market.

{
  "user": "7yQ...",
  "market_id": "abc...",
  "signature": "deadbeef...",
  "nonce": 42
}

Field	Type	Description
`user`	string	Base58-encoded user public key
`market_id`	string	Optional. Hex-encoded 32-byte market ID. Omit to cancel across all markets.
`signature`	string	Hex-encoded Ed25519 signature over the canonical cancel-all message
`nonce`	int	Replay-protection nonce, monotonically increasing per user

Canonical Cancel-All Message

The Ed25519 signature must cover this exact 74-byte layout:

tag              1 byte   (0x01 — domain separator vs. order message)
user            32 bytes
market_present   1 byte   (0 = all markets, 1 = single market)
market_id       32 bytes  (zeros if market_present == 0)
nonce            8 bytes  (u64 little-endian)

Total: 74 bytes. The tag byte ensures a cancel-all signature can never be replayed as an order signature.

Order Types

Type	Behavior
`gtc`	Good-til-cancelled. Rests unmatched portion on the book.
`ioc`	Immediate-or-cancel. Fills what it can, cancels the rest.
`fok`	Fill-or-kill. Must fill entirely or is rejected.
`post_only`	Must rest as maker. Rejected if it would match immediately.

Price Format

All prices are in basis points (1-9999): - 5000 = $0.50 (50% probability) - 7500 = $0.75 (75% probability) - 100 = $0.01 (1% probability)

Balance Format

All balances in micro-USDC (6 decimals): - 1,000,000 = $1.00 - 10,000,000 = $10.00