# Conventions

> Request format, headers, identifiers, amounts, pagination and the other rules shared by every Proxima endpoint.

The Proxima API is a JSON-over-HTTPS API. The rules on this page apply to every endpoint unless its reference entry
says otherwise.

## Requests

- Send requests over HTTPS to the [base URL](/getting-started/environments/) of the environment you target.
- Bodies are JSON, sent with `Content-Type: application/json`. `GET` and most `DELETE` requests take no body.
- Endpoints that upload images, such as token logos, take `multipart/form-data`. Their reference entry is labelled
  **Form fields** instead of **Body parameters**.
- Paths are case-sensitive. Path parameters appear in braces in this reference, for example
  `/wallets/{network_type}/add`. Replace the whole placeholder, braces included.
- Query strings use standard URL encoding. Booleans are written `true` and `false`.

## Headers

| Header | When | Description |
| --- | --- | --- |
| `Authorization` | Every endpoint except the public ones | `Bearer <jwt>`. See [Authentication](/getting-started/authentication/). |
| `Content-Type` | Requests with a body | `application/json`, or `multipart/form-data` with a boundary for uploads. |
| `X-Sent-At` | Optional | Client send time in epoch milliseconds. The web client stamps it on every attempt, retries included, so the platform can measure network latency. Generate it right before sending; never reuse a value. |
| `X-2FA-Algo-Id`, `X-2FA-Response`, `X-2FA-Backup` | Retrying a protected action | Answer a second-factor challenge. See [Two-factor step-up](/getting-started/two-factor-step-up/). |
| `If-Match` | Optimistic-concurrency writes | The version you read. A stale value is refused instead of overwriting someone else's change. Used by launch share grants. |

## Responses

Successful responses return a JSON object. Endpoints that only confirm an action return the acknowledgement shape:

```json
{ "ok": true, "message": "Wallet folder updated" }
```

Failures return `ok: false` with a machine-readable `code` and a human-readable `message`; see [Errors](/getting-started/errors/).
Branch on `code` and on the HTTP status, never on `message`: messages are written for people and can change.

A handful of endpoints return a file instead of JSON, for example a key export. They answer with the file's
content type and a `Content-Disposition: attachment; filename="…"` header.

## Chains and networks

Single-chain endpoints carry a `{chain_id}` path segment (`sol`, `eth`, `bsc`, `base`, `robinhood`, `arc`,
`xlayer`). Wallet endpoints that apply to a whole virtual machine carry `{network_type}` instead (`svm` or `evm`).
The full list, with the native asset of each chain, is in [Environments & Chains](/getting-started/environments/#chains).

A request for a chain the endpoint does not serve fails with `400 unsupported_chain` and names the chain:

```json
{ "ok": false, "code": "unsupported_chain", "message": "this endpoint is not supported for this chain", "chain": "monad" }
```

## Amounts and large integers

- **Base units.** Fields ending in `_atomic`, and amounts the reference documents as base units, are integers in
  the chain's smallest unit: lamports on Solana (10⁹ per SOL), wei on EVM chains (10¹⁸ per native unit).
- **Decimal amounts.** Fields documented as decimal numbers, such as a buy size in SOL, are in whole native units.
- **Multipliers, not exponents.** In the platform constants, a token's `decimals` holds the multiplier
  (`1000000` for a 6-decimal token), not the exponent.
- **Precision.** Atomic amounts and some identifiers, for example history `id` and `launch_ext_id`, exceed
  2⁵³ − 1 and arrive as bare JSON numbers. A standard `JSON.parse` silently rounds them. Parse those keys
  losslessly (a big-number parser, or a pre-pass that quotes them), and keep them as strings or `BigInt` afterwards.
- **Sending large values.** When you send an integer of 10²¹ or more, send it as a decimal string. The web client
  does this automatically, because JavaScript would otherwise print it in exponent notation.

> **Warning:** Rounding an atomic amount is not cosmetic: a withdraw or sell built from a rounded value moves a different amount
> than the one you displayed. Keep amounts as integers or strings end to end.

## Identifiers

| Identifier | Format | Example |
| --- | --- | --- |
| Wallet address, Solana | Base58 public key | `7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU` |
| Wallet address, EVM | `0x`-prefixed hex, checksummed or lowercase | `0x52908400098527886E0F7030069857D2E4169EE7` |
| Token | The mint address (Solana) or contract address (EVM) | `So11111111111111111111111111111111111111112` |
| Launch | `ext_id`, a numeric identifier unique per launch | `184467440737095516` |
| License | The license key string issued at sign-up | `<license_key>` |
| Session | UUID | `0f8fad5b-d9cb-469f-a165-70867728950e` |

## Timestamps

Timestamps are UTC. Depending on the resource, a timestamp is either an epoch number or an ISO 8601 string
(`2026-11-02T09:30:00Z`); the type column of each field tells you which. `GET /health` returns `ts` in epoch
milliseconds, which you can use to measure clock drift.

## Pagination

List endpoints that can grow without bound are cursor-paginated:

1. Send the first request without a cursor (or with `cursor=0` where the endpoint documents it), plus an optional `limit`.
2. Read `next_cursor` from the response.
3. Pass it back as `cursor` to get the next page. A `null` `next_cursor` means you have reached the end.

Treat cursors as opaque strings. The API clamps `limit` to the range each endpoint documents.

## Rate limits

Sensitive endpoints, such as sign-in, two-factor enrolment, backup code regeneration and invites, are rate-limited
per client over a fixed window. Going over returns `429 too_many_requests`. The response carries no `Retry-After`
header: back off exponentially, starting at a few seconds.

## Versioning and stability

The API is not versioned in the path. Additive changes, such as new endpoints, new optional parameters and new
response fields, ship without notice, so ignore fields you do not recognise. Endpoints marked **Beta** in this
reference may change shape; endpoints marked **Internal** are reserved for Proxima operators.
