> For the complete documentation index, see [llms.txt](https://docs.pangolin.exchange/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pangolin.exchange/pangoperps/api-fundamentals.md).

# API fundamentals

Introduction

PangoPerps, available at perps.pangolin.exchange, connects client applications to perpetual futures trading. This section explains the REST and WebSocket interfaces, endpoint environments, request conventions, authentication, rate limits, and error responses.

### API overview

PangoPerps provides two interfaces for client integrations:

| Interface     | Use                                                                                |
| ------------- | ---------------------------------------------------------------------------------- |
| REST API      | Submit or cancel orders, retrieve balances, and manage account resources.          |
| WebSocket API | Receive live market data, order-book updates, and private account or order events. |

### Base endpoints

Choose the API environment that matches the account and key in use.

| Environment | REST base URL                     |
| ----------- | --------------------------------- |
| Mainnet     | <https://api.orderly.org/>        |
| Testnet     | <https://testnet-api.orderly.org> |

### REST request conventions

| Method      | Parameter location | Content-Type     |
| ----------- | ------------------ | ---------------- |
| GET, DELETE | URL query string   | —                |
| POST, PUT   | JSON request body  | application/json |

Parameters may be sent in any order.

### Symbol format

Perpetual market symbols follow this pattern:

```
PERP_<SYMBOL>_USDC
```

For example, the ETH perpetual market uses `PERP_ETH_USDC`.

### Authorization

Private endpoints require a signed request made with a registered Ed25519 API key. Include `orderly-account-id`, `orderly-key`, `orderly-timestamp`, and `orderly-signature` in the request headers. See API Authentication for the signing steps and header requirements.

### Rate limits

Rate limits are counted per API key and may differ by endpoint. If a request exceeds its limit, the API returns HTTP `429`. Wait until the limit window resets before retrying.

### Error responses

Failed API requests return an error code, a message with details, and `success: false`. The `message` field describes the specific failure. For example:

```json
{
  "success": false,
  "code": -1005,
  "message": "order_price must be a positive number"
}
```

All API failures use this structure. See Error Codes for the complete list.