> For the complete documentation index, see [llms.txt](https://sodex.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sodex.com/documentation/for-developers/api-reference/trading-api/rest-v1.md).

# REST API

## Endpoints

### Mainnet

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

### Testnet

* Public: `https://testnet-gw.sodex.dev/api/v1`
* 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`.

See [API Keys and Nonces](/documentation/for-developers/developers/trading/api-keys-and-nonces.md) for credential and nonce rules, and [Authentication & Signing](/documentation/for-developers/developers/trading/authentication-and-signing.md) for EIP-712 structures and signing examples.

## Rate Limits

All REST API requests consume request weight from a fixed one-minute window. When the window's weight limit is reached, subsequent requests are rejected until the window resets.

* 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 [Rate Limits](/documentation/for-developers/developers/trading/api-rate-limits.md).

## 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`    | For API key signing | **Name** of the registered API key (e.g. `"api-key-01"`) — a plain string, not a public key or EVM address. Omit this header for direct master-wallet signing (the "default key"), which is supported but not recommended for routine trading.                                                                                         |
| `X-API-Sign`   | `HexString` | `true`              | EIP-712 typed signature produced with the **private key** of either the API key named in `X-API-Key`, or, if that header is omitted, the master wallet. The private key is never sent — only this signature is. See [Typed signature](/documentation/for-developers/developers/trading/authentication-and-signing.md#typed-signature). |
| `X-API-Nonce`  | `uint64`    | `true`              | Recommended: current timestamp in milliseconds. Must be within `(T - 2 days, T + 1 day)` window. Nonces are tracked per signing address (master wallet address or API key public key), not per account.                                                                                                                                |

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

### Signed request example

```bash
# ${API_KEY_NAME} is the `name` of an API key created from the SoDEX UI, e.g. "api-key-01".
# Not an EVM address, not a hex key — a plain string.
#
# ${API_SIGN} is produced by signing the payload hash with the corresponding
# API key's private key using EIP-712. See ../../products/trading/authentication-and-signing.md#typed-signature.

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

Direct master-wallet signing is supported but not recommended for routine trading. To use it, omit `X-API-Key` entirely and sign with the master wallet's private key. Prefer a dedicated, revocable API key for trading requests.

Use the shared default headers above for normal signed writes. Endpoints that require additional headers such as `X-API-Chain` document that exception locally.

## 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](/documentation/for-developers/api-reference/trading-api/rest-v1/schema.md) for concrete response payload definitions.

## Reference Pages

* [Public REST API](/documentation/for-developers/api-reference/trading-api/rest-v1/sodex-rest-public-api.md)
* [Spot REST API](/documentation/for-developers/api-reference/trading-api/rest-v1/sodex-rest-spot-api.md)
* [Perps REST API](/documentation/for-developers/api-reference/trading-api/rest-v1/sodex-rest-perps-api.md)
* [Schema V1](/documentation/for-developers/api-reference/trading-api/rest-v1/schema.md)