Skip to content

Getting started

Start here

Get a key, make your first call, and understand why the sandbox is the safe place to build.

Start on the sandbox: your own simulated paper account, priced off real marks, where nothing counts. It is a separate account from the in-app demo terminal's, and trades on one never show on the other. Build and rehearse there. When your agent is ready, a live key trades your real accounts (free trial, challenge, tournament and funded) under the same rules as the terminal - see Live trading.

The fastest path to a working call is three steps: get a key, check it, place an order. Under five minutes.

Get a key

  1. Open Settings and go to the Developer tab, section API keys (you need beta access - see the developer overview if you do not have it yet).
  2. Choose Create API key, pick Sandbox, and Generate key. It starts with pk_test_ and is shown once, right after creation. Copy it then; the server only stores a hash and can never show it again.
  3. Put it in an environment variable, never in your code or a commit:
export PERPSFUND_API_KEY="pk_test_your_key_here"

Treat the key like a password

Anyone holding the key can act as your agent. Keep it in an environment variable or a secrets manager, never in source control. You can revoke a key any time from Settings. Revoking does not issue a replacement: create a new key yourself and give it to your agent.

Make your first call

GET /me resolves your key to its owner and environment. It is the quickest "is my key working?" check.

curl https://api.perpsfund.com/v1/me \  -H "X-API-Key: $PERPSFUND_API_KEY"
{ "userId": "clx0abc123", "environment": "sandbox", "keyId": "clx0def456" }

Place your first order

Open a small long on Bitcoin. The order fills at a fresh mark and returns the resulting position and account.

curl -X POST https://api.perpsfund.com/v1/sandbox/orders \  -H "X-API-Key: $PERPSFUND_API_KEY" \  -H "Content-Type: application/json" \  -d '{"symbol":"BTC","side":"long","size":0.01,"leverage":5}'

That is the whole loop: authenticate with a header, send JSON, read JSON back. The rest of the reference is the full menu of what you can read and do.

Give this to your AI
I am building a trading agent on the Perps Fund sandbox API.Base URL: https://api.perpsfund.com/v1Auth: send my key in the header  X-API-Key: pk_test_...   (sandbox keys start with pk_test_)Every request except /health needs the key. Responses are JSON.
Quick check that my key works:GET /me  ->  { userId, environment, keyId }
Place a market order (fills at a fresh mark):POST /sandbox/orders   body: { "symbol": "BTC", "side": "long", "size": 0.01, "leverage": 5 }
It is a simulated paper account - no real money. Help me write a client for this API in my language.

Test safely

The sandbox is where you should start, and that is a feature. Every order and position there lives in a simulated paper account, priced off the same live marks the real markets use. You can be wrong, blow up, and try again with zero consequence.

  • Nothing on the sandbox counts. A pk_test_ key can only reach /sandbox/*, and a sandbox result never touches a challenge, a tournament or a funded account. Your real accounts need a separate pk_live_ key.
  • Start clean whenever you want. POST /sandbox/reset wipes your demo account back to its opening balance, so an experiment gone wrong is one call away from a fresh start.
  • It is a rehearsal engine, not the live one. The sandbox runs the demo engine: real marks and the same fee rates and loss floors, but its own code for fills and caps, not the code path your real accounts use. Take-profit and stop-loss fire only when you read the account or positions, there are no resting limits and no Pro orders, and an orderType it does not know (such as "scale") is placed as a market order instead of being refused. The live routes behave as the terminal does; see Live trading.
  • It expires when idle. A sandbox with no writes (orders, closes, TP/SL changes, resets) for 30 days is deleted, and your next call starts a fresh account.

A safe place to let an agent loose

Because the sandbox cannot touch real funds, it is the right place to hand the controls to an autonomous agent and watch how it behaves over a few hundred trades before you ever consider real capital.

Read these docs from your editor

The docs and this reference are also an MCP server, so an assistant in your editor can look things up while it writes your agent. The address is https://docs.perpsfund.com/mcp. It needs no account and no key.

  • Install it in one click. The arrow beside Copy page, at the top of every docs page and every section here, has Connect to Cursor and Connect to VS Code. Each opens your editor's own install prompt. Any other MCP client takes the address above as a Streamable HTTP server.
  • Two tools. search_docs runs the same search as the docs search box and returns the matching pages and headings. get_page returns one page as Markdown, the same text as the page's own .md address; pass a docs page (payouts) or a section here (reference/errors).
  • Public docs and nothing else. The server reads the published docs pages and this reference, and nothing more. It cannot see your account, your trades, your keys or anything in the admin console, and it cannot place or change an order. Calls are rate limited per network address.