Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.context.markets/llms.txt

Use this file to discover all available pages before exploring further.

​
API reference

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

​
Base URL

Mainnet: 
https://api.context.markets/v2
Testnet: 
https://api-testnet.context.markets/v2
If you do not override the chain or base URL, SDK HTTP requests default to the mainnet base URL.

​
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 from Profile → Settings at context.markets. See API keys for details. Public endpoints (no auth required):
MethodPathDescription
GET/activityGlobal activity feed
GET/marketsList markets
GET/markets/searchSearch markets
GET/markets/:idGet market details
GET/markets/:id/activityGet market activity
GET/markets/:id/oracleGet oracle summary
GET/markets/:id/oracle/quotesList oracle quotes
POST/markets/:id/oracle/quotesRequest a new oracle quote
GET/markets/:id/oracle/quotes/latestGet the latest oracle quote
GET/markets/:id/orderbookGet the orderbook snapshot
GET/markets/:id/pricesGet price history
GET/markets/:id/quotesGet current bid and ask quotes
POST/markets/:id/simulateSimulate a market trade
Authenticated endpoints (API key required):
MethodPathDescription
GET/ordersList orders
POST/ordersCreate an order
GET/orders/recentList recent orders
GET/orders/:idGet an order by id
POST/orders/cancelCancel an order
POST/orders/cancel-replaceCancel and replace an order
POST/orders/bulkRun mixed bulk order operations
POST/orders/bulk/createBulk-create orders
POST/orders/bulk/cancelBulk-cancel orders
POST/orders/simulateSimulate order execution
GET/portfolio/:addressGet portfolio summary
GET/portfolio/:address/claimableGet claimable positions
GET/portfolio/:address/positionsGet portfolio positions
GET/portfolio/:address/statsGet portfolio stats
GET/balanceGet an ERC-20 balance
GET/balance/:addressGet balance summary for an address
GET/balance/settlementGet settlement balance
POST/balance/mint-test-usdcMint testnet collateral
GET/account/migrationGet migration status for the API key user or an authorized wallet
POST/account/migration/startStart migration for the API key user or an authorized wallet
POST/account/migration/migrate-fundsSubmit signed funds migration actions
POST/account/migration/restore-ordersRestore retired legacy limit orders as new v2 orders
POST/account/migration/dismiss-ordersDismiss failed or unwanted migration restorations
POST/gasless/operatorRelay setOperatorBySig
POST/gasless/deposit-with-permitRelay depositWithPermit to Holdings
POST /balance/mint-test-usdc is testnet-only and is limited to 100 requests/hour per API key. Migration endpoints default to the API key user’s primary wallet. Some mutation requests also accept an explicit address override, which requires a signed wallet authorization payload. When migration is active, wallets that still have legacy balances, legacy open orders, or pending/failed restorations cannot continue normal trading through the API. Those wallets receive 409 responses on:
  • POST /orders
  • POST /orders/bulk/create
  • POST /orders/bulk
  • POST /orders/cancel-replace
Pure cancel flows remain available:
  • POST /orders/cancel
  • POST /orders/bulk/cancel
POST /gasless/operator defaults to Settlement V2 when migration is active, and explicit legacy settlementVersion: 1 approvals are rejected. Market creation endpoints (API key with can_create_markets permission):
MethodPathDescription
POST/questionsSubmit a question for market creation
POST/questions/agent-submitSubmit a market draft directly
GET/questions/submissions/:idPoll submission status
POST/markets/createCreate a market from a processed question

​
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)
403Forbidden (missing required permission)
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 (USDC 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..."
}

​
Orderbook polling

The GET /markets/:id/orderbook 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.context.markets/v2/markets/{id}/orderbook
# Returns 304 Not Modified if unchanged