API reference

Auth legend

The Auth column, where present in the route tables below, uses one of these levels. See Authentication for the signing model and Errors and limits for what a failed check returns.

Auth	What the caller sends
None	No credentials. Safe for unauthenticated reads.
JWT	A bearer token (Authorization: Bearer <jwt>) for an authenticated user.
JWT + wallet signature	A JWT plus a user-signed EIP-712 order payload.
JWT + agent signature	A JWT plus a signature from an approved agent wallet.
JWT + approved agent	A JWT, an active approved agent wallet, and (when waitlist gating is enabled) allowlist access.
JWT + signatures	A JWT plus the required wallet and/or agent signature(s) for the action.
JWT or deployment policy	A JWT; whether a caller may read another address is deployment/partner-contract dependent. May return 403 depending on deployment policy.
JWT when gated	No credentials unless the deployment gates the route, in which case a valid JWT is required.
None or gated by environment	No credentials by default, but a deployment may require a JWT.

Authentication (a valid JWT) and authorization (allowlist access) are distinct. When waitlist access is enabled, market-data and binary/trading routes enforce allowlist access on top of the JWT check: expect 401 without a token and 403 when the user is authenticated but not allowed. A few JWT routes require only a valid JWT and never apply the allowlist — notably GET/POST /v1/access/request, the route used to request access (gating it behind the allowlist would prevent onboarding).

Health and runtime

Method	Path	Auth	Notes
GET	/live	None	Process is running
GET	/ready	None	Service is ready to serve traffic
GET	/version	None	API version metadata
GET	/v1/runtime-config	None	Waitlist and feature flags

/metrics is not a public API endpoint.

Access

Method	Path	Auth	Notes
GET	/v1/access/self	JWT	Current identity and access state
GET	/v1/access/request	JWT	Current user's access request
POST	/v1/access/request	JWT	Submit or update an access request

Scalar market data

These routes are available in scalar mode. When waitlist access is enabled, they require an allowed JWT.

Method	Path	Notes
GET	/v1/markets	Scalar asset metadata
GET	/v1/bucket	Current and next bucket
GET	/v1/buckets	Historical buckets
GET	/v1/buckets/{asset_code}/{start_ts}	One bucket
GET	/v1/book?asset=NYCTMP1	Cached order book
GET	/v1/ticker?asset=NYCTMP1	Current mark, OI, and utilization
GET	/v1/oi-status	OI and close-only state

Scalar trading

Method	Path	Auth	Notes
POST	/v1/predict	JWT	Simple scalar prediction package
POST	/v1/orders	JWT + wallet signature	Direct signed scalar order
POST	/v1/orders/prepare	JWT	Prepare an agent-signed order
POST	/v1/orders/submit	JWT + agent signature	Submit prepared order
POST	/v1/leverage/prepare	JWT	Prepare leverage action
POST	/v1/leverage/submit	JWT + agent signature	Submit leverage action
POST	/v1/close	JWT + wallet signature	Reduce-only close
POST	/v1/agent/approve	JWT	Approve an agent wallet

/v1/close-all currently returns 501 Not Implemented. Build clients around explicit position reads and individual closes.

Binary markets

Binary routes are available in binary mode and are hidden in scalar mode. Send a JWT and expect allowlist checks.

Method	Path	Auth	Notes
GET	/v1/binary/status	JWT	Health, pause state, active asset
GET	/v1/binary/markets	JWT	Binary assets and phases
GET	/v1/binary/bucket	JWT	Current binary bucket
GET	/v1/binary/book?asset=GBETA	JWT	Best bid/ask snapshot
POST	/v1/binary/setup	JWT + signatures	Set binary leverage to 2
POST	/v1/binary/predict	JWT	Server-assisted binary entry
POST	/v1/binary/close	JWT	Reduce-only binary close

Binary diagnostic endpoints are not documented here as public trading APIs.

Outcome markets

Outcome routes require the outcome feature to be enabled; check /v1/runtime-config first. Prepare routes also need an active approved agent — see Outcome markets for the full prerequisite.

Method	Path	Auth	Notes
GET	/v1/outcomes/meta	None	Outcome registry, sides, expiry state
GET	/v1/outcomes/price-history	None	Recent price series for outcome coins
GET	/v1/outcomes/ohlc	None	OHLC series for outcome coins
POST	/v1/outcomes/transfer/prepare	JWT	Prepare USDH transfer
POST	/v1/outcomes/transfer/submit	JWT + wallet signature	Submit prepared transfer
POST	/v1/outcomes/orders/prepare	JWT + approved agent	Prepare outcome order
POST	/v1/outcomes/orders/submit	JWT + agent signature	Submit prepared order
POST	/v1/outcomes/cancel/prepare	JWT + approved agent	Prepare cancel by cloid
POST	/v1/outcomes/cancel/submit	JWT + agent signature	Submit prepared cancel
GET	/v1/outcomes/orders/open/{address}	JWT	Open outcome orders
POST	/v1/outcomes/order-status	JWT	Lookup order status by oid or cloid
POST	/v1/outcomes/conversions/prepare	JWT + approved agent	Prepare an outcome conversion
POST	/v1/outcomes/conversions/submit	JWT + agent signature	Submit a prepared conversion
GET	/v1/outcomes/conversions/history	JWT	Conversion history

Conversion routes require outcome_conversions_enabled; check /v1/runtime-config first.

When the deployment gates access (waitlist enabled), every protected outcome route — including the submit calls, the transfer routes, GET /v1/outcomes/orders/open/{address}, and POST /v1/outcomes/order-status — enforces allowlist access on top of the auth shown above and returns 403 — not_allowlisted for a waitlisted user, or access_revoked for a blocked or revoked user. GET /v1/outcomes/conversions/history is JWT-only and never applies the allowlist.

Account and history

Some address-scoped reads may accept an address in the path, but access policy is deployment and partner-contract dependent. Clients should be ready to send a JWT and handle 403.

Method	Path	Auth	Notes
GET	/v1/positions/{address}	JWT or deployment policy	Reconstructed positions
GET	/v1/account/{address}	JWT or deployment policy	Account summary
GET	/v1/fees/{address}	JWT or deployment policy	Effective fee rates
GET	/v1/trades/{address}	JWT or deployment policy	Fills
GET	/v1/orders/open/{address}	JWT or deployment policy	Open orders
GET	/v1/orders/history/{address}	JWT or deployment policy	Filled order history
GET	/v1/profile/{address}	JWT or deployment policy	Trader profile
PUT	/v1/profile	JWT	Update own profile
GET	/v1/stats/{address}	JWT when gated	Trading statistics
GET	/v1/pnl/calendar/{address}	JWT when gated	PnL calendar

Referrals and rewards

Method	Path	Auth	Notes
GET	/v1/referrals/resolve?code=...	None	Resolve a referral code
GET	/v1/referrals/code	JWT	User's codes
POST	/v1/referrals/code	JWT	Create or update a code
POST	/v1/referrals/intent	JWT	Set referral relationship
GET	/v1/referrals/tree	JWT	Referral tree and earnings
GET	/v1/referrals/payouts	JWT	Payout history
GET	/v1/rewards/{address}	None or gated by environment	Points and rewards

POST /v1/referrals is legacy. When the newer referral system is enabled it returns 410 Gone.

WebSocket and charts

Path	Notes
/v1/ws	Versioned WebSocket endpoint
/ws	Alias
/tv/config	TradingView UDF config
/tv/symbols	TradingView symbols
/tv/history	TradingView history
/tv/time	TradingView server time
/tv/search	TradingView symbol search
/tv-mark/*	Mark-price chart endpoints in binary mode

OpenAPI spec

The repository includes a machine-readable OpenAPI document (openapi.yaml) at its root, handy for generating typed clients, validating requests, and standing up mock servers. Treat this page as the authority on which routes are public: the published OpenAPI spec currently includes internal and admin routes that are not part of the public contract, so generate clients against the public subset documented here.

Excluded routes

Admin, analytics, whitelist, runtime-setting mutation, HIP-3 deployer action, referral admin, service metrics, and operator routes are intentionally excluded from public docs. If your integration needs one of those capabilities, treat it as a partner contract issue, not a public API assumption.

POST /v1/cancel and POST /v1/schedule-cancel are also excluded. They look like order endpoints, but they are not public user endpoints in the current API.