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

# Rest API

## Base URL

**Testnet**: `https://api.app.hello.trade/api`

**Mainnet**: N/A

***

## Request Format

All requests use standard HTTP methods with JSON payloads.

**Public Endpoints:**

```
GET /api/account_summary?wallet=0x...
```

**Authenticated Endpoints:**

```json
POST /api/margin/deposit
{
  "amount": "1000.00",
  "instrument": null,
  "marginMode": "Cross",
  "permitSignature": {
    "sig": "0x...",
    "payload": "0x05..."
  },
  "depositSignature": {
    "sig": "0x...",
    "payload": "0x07..."
  }
}
```

For signature construction, see [Signatures](/developer-tools/signatures.md).

***

## Authentication

Authenticated endpoints require EIP-712 signatures in the request body. See [Authentication & Account Model](/developer-tools/authentication-and-account-model.md) for details.

***

## Rate Limiting

Maximum request rate: **20 requests/second per wallet** (rolling 1-second window, orders included). Applies to wallet-authenticated requests; unauthenticated reads are limited per client IP — see [Nonce & Rate Limits](/developer-tools/nonce-and-rate-limits.md).

Same rate limit applies to both REST and WebSocket APIs. See [Nonce & Rate Limits](/developer-tools/nonce-and-rate-limits.md) for details.

***

## Error Responses

```json
{
  "error": "Error message"
}
```

| HTTP Status | Description                                                     |
| ----------- | --------------------------------------------------------------- |
| 400         | Bad Request (invalid parameters, signature verification failed) |
| 404         | Not Found (account/resource not found)                          |
| 500         | Internal Server Error                                           |

For detailed error descriptions, see [Error Codes](/developer-tools/error-codes.md).

***

## Available Endpoints

### Public Endpoints

| Endpoint                                 | Method | Description                                                                                                                                                           |
| ---------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/account_summary`                   | GET    | Account balance and positions                                                                                                                                         |
| `/api/historic/orders`                   | GET    | Historical order data                                                                                                                                                 |
| `/api/historic/trades`                   | GET    | Historical trade data                                                                                                                                                 |
| `/api/user/access-status/:walletAddress` | GET    | `{ hasAppAccess: boolean }` — invite-gate predicate. See [authentication-and-account-model.md](/developer-tools/authentication-and-account-model.md#app-access-gate). |

See [Public Endpoints](/developer-tools/rest-api/public-endpoints.md) for details.

### Authenticated Endpoints

| Endpoint                 | Method | Description                              | Signature                      |
| ------------------------ | ------ | ---------------------------------------- | ------------------------------ |
| `/api/referral/apply`    | POST   | Apply an invite code to grant app access | Canonical-JSON `personal_sign` |
| `/api/margin/deposit`    | POST   | Deposit collateral                       | EIP-2612                       |
| `/api/margin/withdrawal` | POST   | Withdraw collateral                      | EIP-712                        |
| `/api/update_leverage`   | POST   | Update position leverage                 | EIP-712                        |

See [Authenticated Endpoints](/developer-tools/rest-api/authenticated-endpoints.md) for details.

***