HTTP Conventions

Senticore HTTP endpoints use JSON request and response bodies, stable error envelopes, and explicit headers for rate limits and idempotency.

Headers

Header	Direction	Purpose
Authorization	Request	Bearer session token or delegated credential token where applicable
X-Client-Order-Id	Request	Idempotency key for order placement and retry safety
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	Response	Unix timestamp for window reset
Retry-After	Response	Backoff guidance for 429 and 503

JSON conventions

• Quantities, prices, and notionals are encoded as decimal strings.
• Timestamps use Unix milliseconds unless explicitly documented otherwise.
• Market identifiers use hyphenated 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

Order placement accepts clientOrderId or X-Client-Order-Id. Retrying the same order with the same identifier returns the existing order state instead of creating a duplicate.

See Idempotency.

Errors

All error responses use the same envelope:

{
  "error": {
    "code": "insufficient_collateral",
    "message": "Available collateral below order requirement",
    "retryable": false,
    "details": {
      "required": "1500.00",
      "available": "1200.00"
    }
  }
}

See Error Model.