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

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.

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.