> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trydocent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Trade on Hyperliquid and Polymarket programmatically using API keys.

The Docent API lets you create API agents, fund a dedicated wallet, place trades, check balances, and move funds between Hyperliquid and Polymarket. Each API account gets its own non-custodial wallet powered by [Privy](https://www.privy.io/).

## Base URL

```text theme={null}
https://api.trydocent.com
```

## Authentication

All endpoints except `POST /v1/auth/register` require a Bearer token.

```bash theme={null}
curl https://api.trydocent.com/v1/balances \
  -H "Authorization: Bearer dk_live_a1b2c3d4..."
```

API keys use the `dk_live_` prefix. You receive your key exactly once during registration.

## Permissions

Each API key has four permission scopes.

| Permission   | What it controls                                           |
| ------------ | ---------------------------------------------------------- |
| `read`       | Balances, positions, markets, actions, and transfer status |
| `trade`      | Order placement                                            |
| `transfer`   | Venue-to-venue transfers                                   |
| `strategies` | Reserved for coming soon strategy endpoints                |

All permissions are enabled by default on new keys.

## Rate limits

| Tier     | Limit               |
| -------- | ------------------- |
| Standard | 60 requests/minute  |
| Premium  | 300 requests/minute |

When rate limited, the response includes a `Retry-After` header in seconds and a `retryAfter` field in milliseconds.

## Asynchronous execution

Orders and transfers run through durable workflows.

1. Call `POST /v1/orders/perp`, `POST /v1/orders/spot`, `POST /v1/orders/polymarket`, or `POST /v1/transfers`.
2. Docent returns an `actionId` for orders or a `transferId` for transfers.
3. The workflow handles funding and execution in the background.
4. Poll `GET /v1/actions?actionId=...` for orders or `GET /v1/transfers?transferId=...` for transfers.

This is why a request can be accepted before the trade or transfer is finished.

## Error format

All errors follow the same shape.

```json theme={null}
{
  "error": "Human-readable message",
  "code": "MACHINE_CODE"
}
```

| Status | Code               | Meaning                                       |
| ------ | ------------------ | --------------------------------------------- |
| 400    | `BAD_REQUEST`      | Invalid query params or business-rule failure |
| 400    | `VALIDATION_ERROR` | Invalid request body                          |
| 400    | `ORDER_REJECTED`   | Order could not be accepted                   |
| 400    | `ORDER_FAILED`     | Order request failed before execution         |
| 400    | `TRANSFER_FAILED`  | Transfer request failed before execution      |
| 401    | `UNAUTHORIZED`     | Missing, invalid, or expired API key          |
| 403    | `FORBIDDEN`        | Key lacks the required permission             |
| 404    | `NOT_FOUND`        | Requested action or transfer was not found    |
| 429    | `RATE_LIMITED`     | Too many requests                             |
| 501    | `NOT_IMPLEMENTED`  | Endpoint exists but is not live yet           |

## Supported venues

| Venue                      | What you can trade                            |
| -------------------------- | --------------------------------------------- |
| **Hyperliquid** perpetuals | BTC, ETH, SOL, and other perpetual markets    |
| **Hyperliquid** spot       | PURR, HFUN, and other Hyperliquid spot tokens |
| **Polymarket**             | Prediction markets with Yes/No outcomes       |

The API supports trading and venue-to-venue transfers. External withdrawals to arbitrary addresses are not supported.