# REST API v1

## Endpoints

### Mainnet

* Spot: `https://mainnet-gw.sodex.dev/api/v1/spot`
* Perps: `https://mainnet-gw.sodex.dev/api/v1/perps`

### Testnet

* Spot: `https://testnet-gw.sodex.dev/api/v1/spot`
* Perps: `https://testnet-gw.sodex.dev/api/v1/perps`

## Authentication

* Public market-data endpoints are unsigned.
* Authenticated REST writes use EIP-712 signatures.
* API keys are used for signing only.
* Account queries should use the target `accountID`.

For the full API key, nonce, and typed-signing rules, see the top-level [Sodex Developer Documentation](https://sodex.com/documentation/api/api).

## Nonces and Signing

* Nonces are tracked per API key.
* Each new nonce must be unique and larger than the smallest nonce in the stored high-water set.
* Valid nonces must remain within `(T - 2 days, T + 1 day)`.
* Use domain `spot` for spot actions and `futures` for perps actions.

## Rate Limits

All REST API requests consume request weight from a rolling one-minute window.

* Weight budget: `1200` per minute
* Scope: per IP address
* Default unmatched endpoint weight: `20`

For the full per-endpoint weight table, dynamic rules, order-placement limits, and WebSocket limits, see [API Rate Limits](https://sodex.com/documentation/api/api-rate-limits).

## Request Headers

### Public read endpoints

Public read endpoints usually only require:

* `Accept: application/json`

### Signed write endpoints

Signed write endpoints use the following default headers:

| Name           | Type        | Required | Description                                                                                      |
| -------------- | ----------- | -------- | ------------------------------------------------------------------------------------------------ |
| `Content-Type` | `string`    | `true`   | `application/json`                                                                               |
| `Accept`       | `string`    | `true`   | `application/json`                                                                               |
| `X-API-Key`    | `string`    | `true`   | Name of the API key used for the signature. Must match the key name registered.                  |
| `X-API-Sign`   | `HexString` | `true`   | Typed signature signed by API key or main wallet.                                                |
| `X-API-Nonce`  | `uint64`    | `true`   | Recommended: current timestamp in milliseconds. Must be within `(T - 2 days, T + 1 day)` window. |

Endpoint pages include a dedicated `Headers` section only when they differ from this shared default.

### Signed request example

```bash
curl -X POST ${SPOT_ENDPOINT}/trade/orders \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: <API-Key>' \
  -H 'X-API-Sign: <API-Sign>' \
  -H 'X-API-Nonce: <API-Nonce>' \
  -d <JSON-Request-Body>
```

Use the shared default headers above for normal signed writes.

## Response Format

REST endpoints return a common response envelope with:

* `code` for status
* `timestamp` for the server time in milliseconds
* `error` when the request fails
* `data` containing the endpoint-specific payload

Each endpoint's `Response` section only describes the endpoint-specific `data` payload, or notes when no endpoint-specific `data` is returned.

See the endpoint pages and [Schema](https://sodex.com/documentation/api/rest-v1/schema) for concrete response payload definitions.

## Reference Pages

* [Spot REST API V1](https://sodex.com/documentation/api/rest-v1/sodex-rest-spot-api)
* [Perps REST API V1](https://sodex.com/documentation/api/rest-v1/sodex-rest-perps-api)
* [Schema V1](https://sodex.com/documentation/api/rest-v1/schema)