HTTP Conventions

Senticore HTTP endpoints use JSON request and response bodies, explicit headers for tracing, rate limits, and idempotency, and a stable top-level error envelope for normalized transport and API errors.

Headers

Header	Direction	Purpose
Authorization	Request	Bearer session token or delegated credential token where applicable
Idempotency-Key	Request	Safe retry key for signed action submit, delegated batch, and replace/cancel flows
X-Client-Order-Id	Request	Strategy-level order identity on delegated place-order surfaces
X-Request-Id	Response	Support and trace identifier
X-RateLimit-Limit	Response	Allowed requests in current window
X-RateLimit-Remaining	Response	Remaining requests in current window
X-RateLimit-Reset-Ms	Response	Milliseconds until the current window resets
Retry-After	Response	Backoff guidance for 429 and 503
Cache-Control	Response	Route-specific public-read cache policy. Live/private responses are not made cacheable.
ETag	Response	Validator for cacheable catalog responses such as exchange info; send it back as If-None-Match.

JSON conventions

• Public market data uses typed JSON fields; delegated order-entry facades encode human quantities, prices, and notionals as decimal strings.
• Raw signed action quantities and prices use integer atomic units such as micro-USDC.
• Timestamps use Unix milliseconds unless explicitly documented otherwise.
• Canonical trading endpoints use numeric market ids. Product and display endpoints can also include symbols such as BTC-USDC.
• Cursor pagination is used for historical endpoints.

Pagination

{
  "data": [],
  "nextCursor": "eyJvZmZzZXQiOjEwMH0"
}

Clients should treat cursors as opaque and should not parse or construct them manually.

Public-read caching

Market catalog routes use a short public cache policy. Exchange info also supports conditional requests and returns 304 Not Modified when If-None-Match matches its current ETag. Order books, tickers, trades, and private/account state are intentionally not covered by that catalog cache policy. Consume live market data over WebSocket instead of polling REST in parallel.

Idempotency

Signed action submit and delegated batch flows should send Idempotency-Key for safe network retries. Delegated order placement can also use clientOrderId or X-Client-Order-Id as strategy-level order identity.

See Idempotency.

Errors

JSON API errors use this top-level envelope when the error can be normalized:

{
  "ok": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "retriable": true,
    "requestId": "req_01JZ...",
    "details": {
      "retryAfterMs": 500
    }
  }
}

Business-level order rejects can also be returned inside a successful submit envelope, especially on BSL and delegated order-entry surfaces. In that case inspect ok, actionResults[], items[], error, receipts, fills, and drop-copy before treating an order as live. Do not retry a business reject unless the documented response envelope or action-level reject reason is explicitly retriable.

See Error Model.