PhoenixPerpetualsDocs API v1
Get an API key

Tools

The command line⁠.

pperp puts your accounts in your terminal: sign in once, then read, trade, flatten and follow everything live, or script it with JSON and exit codes.

View as Markdown

On this page
  1. Install
  2. Sign in
  3. Profiles
  4. Every day
  5. Every API operation
  6. Scripting
  7. When something is off
  8. AI assistants on your computer

pperp is the Phoenix Perpetuals command line: one small program for macOS, Linux and Windows. It has a command for every API operation, plus short ones for what you do every day.

pperp positions
pperp buy BTC-USD 0.001 --tp 2% --sl 1%
pperp stream account

Install#

curl -fsSL https://docs.phoenixperpsfunding.com/install.sh | sh

The installer puts pperp in your user folder (no administrator rights), checks the download against the signed checksums of the release, and tells you if it has to add the folder to your PATH. pperp version shows what you have.

pperp is open source (MIT): github.com/phoenixperps/pperp. With Go installed, go install github.com/phoenixperps/pperp/cmd/pperp@latest builds it from there instead.

Sign in#

pperp login --sandbox    # the sandbox
pperp login              # live

Your browser opens on the Phoenix Perpetuals sign-in, where you choose what the command line may do: Read, or Read and trade (on live, trading takes a code we email you), and which accounts. Then you are back in the terminal, signed in for 90 days. Nothing is copied by hand.

  • No browser on this computer (a server over SSH)? pperp login --manual prints an address to open on any device; you paste back the code it shows.
  • The sandbox also takes a sandbox API key: pperp login --sandbox --api-key asks for it without showing it, --api-key-stdin reads it from a pipe.
  • pperp whoami says what you are signed in as, its access, accounts and limits. pperp logout ends the sign-in on our side too.

The sign-in is kept in your system's keychain (macOS Keychain, Windows Credential Manager, the Secret Service on Linux), never in a file in your home folder. Where there is no keychain, pperp login --store file keeps it in a file only you can read.

Profiles#

live and sandbox are two profiles, each with its own sign-in and settings. --sandbox (or --profile sandbox) picks one for a command; the first one you sign in to becomes the default.

pperp profiles                        # which exist, which is the default, which are signed in
pperp profiles use sandbox            # the default from now on
pperp use SANDBOX-00042-001           # the default account of this profile
pperp config set confirm_trades true  # ask before every trade on this profile
pperp login --profile bot --env sandbox   # another profile of your own

When a command needs an account, it takes --account, else the profile's default account, else your only one.

Every day#

CommandWhat it does
pperp accountsYour accounts and their state
pperp positions, orders, fillsOpen positions, working orders (--status history), fills
pperp riskEquity, margin, and the room left to the daily loss and drawdown limits
pperp history equity, history dailyThe equity curve, results by trading day
pperp markets, quote BTC-USDThe markets and their rules, bid, ask and last
pperp buy, sellA market, limit, stop or stop-limit order, with exits
pperp close BTC-USDClose a position (--percent 50 or --size)
pperp cancel ID, cancel --allCancel orders
pperp flattenCancel every order and close every position (--every-account)
pperp stream accountEvery event of your accounts, live (--risk for live risk too)
pperp stream prices BTC-USD ETH-USDPrices live; also book, trades, candles, stats

Orders#

pperp buy BTC-USD 0.01                              # at the market
pperp buy BTC-USD '$500'                            # 500 USD worth at the market, sized down to its step
pperp sell ETH-USD 0.1 --stop <price> --limit <price>  # a stop-limit, below the price for a sell
pperp buy BTC-USD 0.01 --tp 2% --sl 1%              # exits set from the fill price
pperp buy BTC-USD 0.01 --sl 1% --trail 500          # a stop 1% under the fill, trailing by 500
pperp buy BTC-USD 0.01 --leverage 5                 # the market's leverage first
pperp buy BTC-USD 0.01 --dry-run                    # what it would do now; nothing is sent

On live, every trade is shown first with what it would do now (the price, the fee, the margin it needs) and placed only when you say yes. Turn it off for a profile with pperp config set confirm_trades false. flatten and cancel --all ask you to type the account's name.

Every API operation#

Every operation of the API reference is a command of the same name: pperp list-orders, pperp set-exits, pperp create-strategy. Path values are arguments, query and body fields are flags, and anything nested goes in --data or --set:

pperp list-orders --status history --market BTC-USD --all-pages
pperp get-order ord_01JAB7Q8XK4M2N5P7R9S3T5V7W
pperp set-exits BTC-USD --data @exits.json
pperp place-order --market BTC-USD --side buy --type market --size 0.001 \
  --set exits.stop_loss.percent=1 --set exits.take_profit.0.percent=2
pperp api GET /v1/limits                            # any path, for operations newer than your pperp

pperp help COMMAND lists a command's flags with what each field means.

Scripting#

On a terminal pperp prints tables; piped, it prints JSON. Choose with -o table, json, jsonl or csv, or pick fields with --jq:

pperp positions -o json | jq '.[] | {market, unrealized_pnl}'
pperp fills --all-pages -o csv > fills.csv
pperp risk --jq '.daily_loss.room'

Prices and sizes are printed exactly as the API sends them, never rounded.

Writes carry an Idempotency-Key. When a call fails without a clear answer (the network dropped), pperp prints its key: check with pperp orders, then repeat with --idempotency-key and the action happens once at most. Without a terminal to ask, live trades and flatten need --yes.

Exit codes#

CodeMeaning
0Done
1Failed, or you answered no
2The command was not used right, or the request was invalid
3Not signed in, or not allowed (401, 403)
4Not found
5Conflict (409)
6Refused by a rule of the account or a limit of the key (422)
7Rate limited
8Our side failed (5xx)
9No answer: the network, or an outcome not known

When something is off#

pperp doctor checks your settings, the keychain, the sign-in and its expiry, that the API answers, and your computer's clock. --verbose prints every request and answer line, with the credential cut to its last four characters; --include prints the rate-limit headers.

AI assistants on your computer#

pperp mcp serves the MCP tools over stdio, signed in as your profile, for assistants that run local servers. It only reads unless you add --allow-trading.

claude mcp add phoenix-perps -- pperp mcp --sandbox

Guides, endpoints, fields and error codes.