Conventions

The contract that applies to every endpoint.

Base URL

https://gw.carbon.inc/v1

• HTTPS only.

• /v1 is the API version (URI versioning). Breaking changes would ship under a new prefix without disturbing /v1.

• Interactive docs (Swagger UI): https://gw.carbon.inc/api.

Methods

Method	Used for
GET	Reads — params in the query string.
POST	Writes and actions — JSON body.
PUT	Updates (e.g. rename a key).
DELETE	Removals (revoke a key, delete a delegation).

Requests

• Send Content-Type: application/json with any body.

• Every non-public endpoint needs a credential header — a session JWT or an API key. See Authentication.

• Input is validated strictly and coerced to declared types. Malformed input, missing required fields, or unknown enum values are rejected with 400.

Response envelope

Every response — success or error — uses the same envelope. Your payload is always under data.

Success

{ "success": true, "statusMessage": "Success", "data": { /* result */ } }

Error

{
  "success": false,
  "statusMessage": "Human-readable message",
  "error": { "code": "400", "message": "Human-readable message" },
  "httpStatusCode": 400
}

Branch on success (and the HTTP status). On success read data; on failure read error. A collection is an array inside data, not the root object. See Errors.

Encoding

• Numbers as strings. Prices, sizes, amounts, and margin values are often strings to preserve precision (from on-chain fixed-point). Parse with a decimal/big-number library — never native floats.

• Wei fields (e.g. amountWei) are base-unit integers (18 decimals) as strings; divide by 10^18 for human units. Fields without Wei are already human-readable.

• Addresses are 0x hex. Chain id is an integer (42161, Arbitrum). Timestamps are Unix seconds. Enums are UPPER_SNAKE strings.

Pagination

History endpoints accept page and limit and return metadata:

{ "success": true,
  "data": { "items": [ … ], "page": 1, "limit": 50, "total": 320, "totalPages": 7 } }

Increment page until page === totalPages. Time-ranged endpoints also accept fromTimestamp / toTimestamp (Unix seconds).

CORS

CORS is enabled, so the API can be called from browsers — but never ship a secret API key to a browser (see Authentication).