Skip to main content

​
API reference

The Context API provides programmatic access to markets, orders, and portfolio data. All endpoints use the v2 API.

​
Base URL

https://api-testnet.context.markets/v2

​
Authentication

Most endpoints require an API key passed as a Bearer token in the Authorization header: 
Authorization: Bearer your-api-key
Content-Type: application/json
Get an API key by visiting context.markets or reaching out on Discord. Public endpoints (no auth required):
  • GET /markets - List markets
  • GET /markets/:id - Get market details
  • GET /markets/:id/quotes - Get current bid/ask prices
  • GET /markets/:id/orderbook - Get orderbook (also supports SSE streaming)
  • GET /markets/:id/simulate - Simulate a trade
  • GET /markets/:id/prices - Get price history
  • GET /markets/:id/oracle - Get oracle data
  • GET /markets/:id/oracle/quotes - Get oracle probability estimates
  • POST /markets/:id/oracle/quotes - Request new oracle analysis
  • GET /markets/:id/activity - Get market activity
  • GET /activity - Global activity feed
Authenticated endpoints (API key required):
  • All /orders/* endpoints
  • All /portfolio/* endpoints
  • All /balance/* endpoints
  • All /gasless/* endpoints

​
Request format

​
Content types

  • Request bodies: application/json
  • Orderbook streaming: text/event-stream (via Accept header)

​
Response format

All responses are JSON with consistent structure:

​
Success response

{
  "markets": [...],
  "cursor": "..."
}

​
Error response

{
  "message": "Error description",
  "code": "ERROR_CODE"
}

​
Bulk operation errors

{
  "errors": [
    {
      "index": 0,
      "error": "description",
      "operation": "create"
    }
  ]
}

​
HTTP status codes

CodeDescription
200Success
201Created (new order)
400Bad Request (validation error, invalid signature)
404Not Found
409Conflict (duplicate order)
429Rate Limited
500Internal Server Error

​
Pagination

The API uses cursor-based pagination for list endpoints. Cursors are opaque strings - don’t parse or construct them manually. 
GET /markets?limit=50&cursor=...
Response includes the next cursor: 
{
  "markets": [...],
  "cursor": "next-page-cursor"
}
When cursor is null, you’ve reached the end of the results.

​
Price and size encoding

All prices and sizes use 6 decimal places (TUSD precision):
Human readableEncoded value
$0.50500000
$0.0110000
1 share1000000
0.5 shares500000
Quotes and orderbook endpoints return prices in cents (0-100) for convenience.

​
BigInt handling

All numeric values that could exceed JavaScript’s safe integer range (prices, sizes, balances) are returned as strings: 
{
  "price": "500000",
  "size": "1000000"
}
Always parse these as BigInt or use a decimal library for calculations.

​
Addresses and hashes

All Ethereum addresses and hashes are returned as checksummed hex strings: 
{
  "marketId": "0x1234567890abcdef...",
  "trader": "0xAbCdEf1234567890..."
}

​
Real-time orderbook streaming

The GET /markets/:id/orderbook endpoint supports Server-Sent Events (SSE) for real-time updates. Set the Accept header to text/event-stream to receive a stream instead of a JSON snapshot. 
curl -N -H "Accept: text/event-stream" \
  https://api-testnet.context.markets/v2/markets/{id}/orderbook

​
Event types

EventDescription
snapshotFull orderbook state (sent on connection)
price_changeA price level was added, updated, or removed
last_tradeA trade was executed
heartbeatKeep-alive signal (every 5 seconds)

​
Query parameters

ParamTypeDefaultDescription
depthinteger20Number of price levels (1-100)
outcomeIndexinteger0Outcome to stream (0 = Yes)

​
JSON snapshot mode

Without the SSE Accept header, the endpoint returns a JSON snapshot with ETag support for conditional requests. Use If-None-Match to avoid re-fetching unchanged data: 
curl -H "If-None-Match: \"abc123\"" \
  https://api-testnet.context.markets/v2/markets/{id}/orderbook
# Returns 304 Not Modified if unchanged