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

# Personal API keys

> Trade your own account from your own scripts, bots and tools.

A **personal API key** lets you use the Trade API from your own code: a
trading bot, a script, a spreadsheet, a local tool. You create the key
yourself, so you don't need a partner app or Hyperprop's approval.

A personal key reaches all your accounts, on crypto perpetuals and futures.
Market data isn't included.

## How it differs from the other credentials

| | Personal key | Partner integration | Organization key |
| - | - | - | - |
| Who it's for | A trader's own tools | A third-party app a trader connects | A prop firm's backend |
| Credential | Your `hpp_...` key | Partner app credentials + the trader's `hpk_...` key | `hp_live_...` org key |
| Markets | Every market; market data isn't included | Every market | Every market |
| Who can revoke | You, at any time | The trader, at any time | Firm admin |

Building an app that other traders connect to? Use a
[partner integration](https://docs.hyperprop.com/guides/partner-integrations.md) instead.

## Quickstart

**1. Create a key**

In **Settings → API keys → Personal Keys**, choose **Create Key**, give it
a label and choose its access. Copy the key: it looks like `hpp_...` and is
shown only once.

**2. Exchange the key for a session token**

```bash theme={null}
curl -X POST "https://api.hyperprop.com/trade/api-keys/session" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "hpp_your_personal_key"}'
```

**3. Use the token as a Trade API bearer token**

```bash theme={null}
curl "https://api.hyperprop.com/trade/positions?account_id=YOUR_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

> [!WARNING]
>
> Treat a personal key like a password. Keep it on your own machine or server;
> never put it in a browser page, a public repository or anything someone else
> can read.

## Keys and access

Each key has one of two access levels, chosen when you create it:

| Access | Can do |
| - | - |
| **Read and write** | Read accounts, orders and positions, and place, modify and cancel orders |
| **Read only** | Read accounts, orders and positions; any order request returns `403` with code `READ_ONLY_KEY` |

* You can have up to **5 active personal keys**.
* Revoking a key in **Settings → API keys** stops new sessions at once, and
  sessions already opened with it end within 30 seconds.
* Personal keys and partner keys are separate. A personal key never works with
  partner app credentials, and a partner key never works on
  `/trade/api-keys/session`.

## The session

`POST /trade/api-keys/session` takes:

| Field | Required | Meaning |
| - | - | - |
| `api_key` | Yes | Your personal key (`hpp_...`) |
| `email` | No | Your sign-in email. When sent, it must match the key's owner |
| `firm` | No | Organization id, slug or name. Limits the session to your accounts at that firm |

The response:

```json theme={null}
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 900,
  "session_type": "personal_api_key",
  "scope": "trade",
  "markets": ["crypto", "futures"],
  "organization_id": null,
  "organization_name": null,
  "organization_slug": null,
  "organizations": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "name": "Your Prop Firm",
      "slug": "your-prop-firm",
      "account_ids": ["7c1e0a4e-1b2c-4d5e-8f90-1234567890ab"]
    }
  ],
  "account_ids": ["7c1e0a4e-1b2c-4d5e-8f90-1234567890ab"]
}
```

* The token lasts 15 minutes. Exchange the key again for a fresh one.
* `account_ids` lists the accounts the session can reach: all of yours (at one
  firm, when you sent `firm`).
* `scope` is `trade` for a **Read and write** key and `read` for a
  **Read only** key.
* Every response to a personal key session carries the header
  `x-hyperprop-session: personal-api-key`.

## What a personal key session can do

| Area | Available |
| - | - |
| Reading accounts, risk settings and lockout status | Yes |
| Orders and positions (`/trade/orders`, `/trade/positions`, history, trades) | Yes, every market |
| Placing, modifying and cancelling orders, brackets, closing positions | Yes, every market, with **Read and write** access |
| Cancel all, close all, flatten | Yes, with **Read and write** access |
| Trade events over `wss://api.hyperprop.com/trade/ws?token=...` | Order, position and account updates |
| Prices, order books and candles | No: market data isn't included |
| API key management, copy trading setup | No |

Your trading records are always included: order, stop and fill prices,
realized P\&L, fees, balances and history. Live values based on futures prices
are not:

* A futures position has `mark_price`, `marked_at` and `unrealized_pnl` set
  to `null`, and `"market_data_withheld": true`. Crypto positions keep them.
* While an account has an open futures position, its `equity`,
  `unrealized_pnl`, `current_drawdown` and `drawdown_from_hwm` are `null`, and
  the account has `"market_data_withheld": true`. The same applies to its
  account updates on the trade event stream.

For crypto prices, order books and candles, use the
[HDL market data API](https://docs.hyperprop.com/hdl/api.md). Futures prices aren't available through the
API: `GET /trade/perp/mark` serves perpetuals only and returns `403` for a
futures symbol.

A route that personal keys can't use returns `403` with code
`PERSONAL_KEY_FORBIDDEN`.

## Reading your journal

The journal endpoints on the Platform API accept a personal key too:
`GET /platform/v1/user/trading/trades` and
`GET /platform/v1/user/trading/orders`. Send the key on its own, or send the
session token:

```bash theme={null}
curl "https://api.hyperprop.com/platform/v1/user/trading/trades" \
  -H "X-Trader-Api-Key: hpp_your_personal_key"
```

Results cover all your accounts, on every market.

## Using your key with an AI assistant

Connect Claude, ChatGPT, Cursor or your own agent with your personal key to
let it read your accounts and journal or, with a **Read and write** key, place
orders after you approve them. See [MCP connector](https://docs.hyperprop.com/guides/mcp-connector.md).

## Limits and errors

| Situation | Response |
| - | - |
| Wrong, revoked or expired key | `401` |
| Revoked key on an open session | `401` with code `API_KEY_REVOKED` |
| Too many failed key exchanges | `429`; wait a minute |
| More than 30 successful key exchanges a minute with one key | `429` with code `RATE_LIMITED` and `Retry-After`; reuse the session until it expires |
| More than 10 reads a second (bursts of 20 allowed), across all your keys | `429` with code `RATE_LIMITED` and `Retry-After` |
| More than 5 open trade event connections | The extra connection is refused with `429` |
| More journal requests than the journal limits allow | `429` with code `RATE_LIMITED` and `Retry-After` |
| Repeated failed journal requests with a wrong key | `429` with `Retry-After: 60` |
| Order with a read-only key | `403` with code `READ_ONLY_KEY` |

Order submissions and modifications follow the same per-account limits as
every other session. Exits (cancels, closes, flattens) have their own
allowance for your personal keys, so a script or agent that uses it up can't
stop you closing from the terminal. See [Rate limits](https://docs.hyperprop.com/concepts/rate-limits.md)
for every number.


## Related topics

- [Create a personal API key session](https://docs.hyperprop.com/trade-api/account/create-a-personal-api-key-session.md)
- [Authentication](https://docs.hyperprop.com/authentication.md)
- [Rate limits & quotas](https://docs.hyperprop.com/concepts/rate-limits.md)
- [Introduction](https://docs.hyperprop.com/introduction.md)
- [Get order history (keyset-paginated)](https://docs.hyperprop.com/platform-api/partner-access/get-order-history-keyset-paginated.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.