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.
On this page
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 accountInstall#
curl -fsSL https://docs.phoenixperpsfunding.com/install.sh | shirm https://docs.phoenixperpsfunding.com/install.ps1 | iexThe 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 # liveYour 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 --manualprints 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-keyasks for it without showing it,--api-key-stdinreads it from a pipe. pperp whoamisays what you are signed in as, its access, accounts and limits.pperp logoutends 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 ownWhen a command needs an account, it takes --account, else the profile's default account, else your only one.
Every day#
| Command | What it does |
|---|---|
pperp accounts | Your accounts and their state |
pperp positions, orders, fills | Open positions, working orders (--status history), fills |
pperp risk | Equity, margin, and the room left to the daily loss and drawdown limits |
pperp history equity, history daily | The equity curve, results by trading day |
pperp markets, quote BTC-USD | The markets and their rules, bid, ask and last |
pperp buy, sell | A market, limit, stop or stop-limit order, with exits |
pperp close BTC-USD | Close a position (--percent 50 or --size) |
pperp cancel ID, cancel --all | Cancel orders |
pperp flatten | Cancel every order and close every position (--every-account) |
pperp stream account | Every event of your accounts, live (--risk for live risk too) |
pperp stream prices BTC-USD ETH-USD | Prices 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 sentOn 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 pperppperp 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#
| Code | Meaning |
|---|---|
| 0 | Done |
| 1 | Failed, or you answered no |
| 2 | The command was not used right, or the request was invalid |
| 3 | Not signed in, or not allowed (401, 403) |
| 4 | Not found |
| 5 | Conflict (409) |
| 6 | Refused by a rule of the account or a limit of the key (422) |
| 7 | Rate limited |
| 8 | Our side failed (5xx) |
| 9 | No 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