SDKs
Python SDK.
The Phoenix Perpetuals API for Python: every REST call (sync and async), the account stream and market data, with retries, idempotency keys, paging and typed errors. Python 3.10 or later.
On this page
Source: python/ on GitHub, MIT. Version 1.2.0, the same for all seven SDKs: releases. Python 3.10+. Package phoenixperps.
pip install https://github.com/phoenixperps/sdk/releases/download/v1.2.0/phoenixperps-1.2.0-py3-none-any.whlA first call:
from phoenixperps import PhoenixPerps
client = PhoenixPerps() # PHOENIXPERPS_API_KEY from the environment
account = client.accounts.list().data[0]
order = client.orders.create(account["id"], {
"market": "BTC-USD", "side": "buy", "type": "market", "size": "0.01",
"exits": {"take_profit": [{"distance": "600", "size_pct": 100}], "stop_loss": {"distance": "300"}},
})Async: AsyncPhoenixPerps, the same calls awaited (async with AsyncPhoenixPerps() as client: ...).
The client#
PhoenixPerps(api_key=None, *, environment=None, base_url=None, timeout=30.0, max_retries=2, app_info=None, http_client=None, account_stream_url=None, market_stream_url=None, logger=None)
api_key: elsePHOENIXPERPS_API_KEY. Without one the client is still made: the public calls (markets, status) work, any other answers the API'smissing_api_key(AuthenticationError), and no Authorization header goes out.- The environment comes from the key itself (
ppk_live_,ppk_test_;environment=orPHOENIXPERPS_ENVIRONMENT,liveorsandboxin any case, only for a key without either); a key of the other environment fails before any request. base_url: elsePHOENIXPERPS_BASE_URL, else the environment's host; the REST address as the docs write it (https://api.phoenixperpsfunding.com/v1) works too. It moves the REST calls only: the streams takeaccount_stream_urlandmarket_stream_url.- Every call also takes
idempotency_key=,timeout=,max_retries=,headers=andraw_response=. - The key never appears in
repr(client), an error or a log line (client.masked_keyshows its end).
Calls#
Resources follow the API: platform, me, markets, accounts, history, margin, positions, orders, fills, exits, strategies, alerts, events, webhook_endpoints, tradingview. Prices and sizes are decimal strings; a Decimal or a float goes out in plain decimal form, never an exponent.
- Answers are plain dicts, typed for your type checker with the TypedDicts of
phoenixperps.types(orders.createanswers anOrder,fills.listaPage[Fill]):from phoenixperps.types import Order. A body is any mapping in the API's words, one of those TypedDicts too (CreateOrder). - A call is tried again only when that is safe (a read, a call carrying an Idempotency-Key, an order change given one too, or a route the API marks retry-safe), after a network failure, a timeout, or an answer the API marks
retryable(429 or 5xx when the answer is not the API's own). Writes get one Idempotency-Key, the same on every attempt. Retry-Afteris honoured (fractions too); one over 60 s is not slept: the call raisesRateLimitErrorwithretry_after.- The rate limit is kept per budget (
client.rate_limits: read, trade, public); with one used up, the next call of that budget waits for its reset instead of drawing a 429. raw_response=RawResponse()keeps the answer as it came:status_code,headers(Idempotent-Replayed,ETag),body,request_id. Withheaders={"if-none-match": etag}, an unchanged answer is a 304: the call returnsNone(a list call too), never an error. A 2xx whose body is not JSON (a proxy's page) is an error (http_200).- A route this version does not know:
client.request("GET", "/v1/status", query=None, body=None)answers aRawResponse(.json(), its body as it came), with the same key, retries and errors.
from phoenixperps import RawResponse
raw = RawResponse()
order = client.orders.create(account["id"], body, idempotency_key=key, raw_response=raw)
print(raw.request_id, raw.headers.get("idempotent-replayed") == "true") # the first order, sent againLists#
page = client.orders.list(account["id"], {"status": "working"}) # page.data, page.has_more, page.next_cursor
for fill in client.fills.list(account["id"]).auto_paging_iter(500): # every page, at most 500 items
...
async for fill in aclient.fills.list(account_id, max_items=500): # async (await it: the first page, iterable too)
...A page also has every other field of the list as the API names it (page.as_of, page.history_complete), and each next page is asked with the first call's options (headers=, timeout=, ...).
Errors#
Every failure is a PhoenixPerpsError with code, status, message, request_id, details, retry_after, retryable (the same call may work later: the API's own flag), doc_url, order_id, idempotency_key and the answer's headers. Its class tells the family: AuthenticationError (401), PermissionDeniedError (403), NotFoundError, ConflictError (409), ValidationError (400), RuleRejectedError (422: the account's rules said no), RateLimitError, ServerError, APIConnectionError, APITimeoutError.
Streams (async, read only; orders go through REST)#
async with aclient.account_stream(risk=True) as stream:
async for event in stream: # each event once, resumed after reconnects
if event["type"] == "risk": # an account's risk, as it changes (risk=True only)
print(event["account_id"], event["data"]["equity"])
elif event["type"] == "notice": # a gap: what came after event["after"] may be missing here
async for missed in aclient.events.list({"after": event["after"]}):
print(missed["type"], missed["data"])
else:
print(event["type"], event["seq"], event["replayed"], event["data"])
async with aclient.market_stream() as market:
await market.subscribe("ticker", ["BTC-USD", "ETH-USD"], interval_ms=250)
async for frame in market:
print(frame)- The account stream tells each event once, with its frame's
seqandreplayed; withrisk=True, risk frames too (also kept instream.risks). A resume the server cannot cover, or a 4008 (too far behind), is a gap: a{"type": "notice", "code": "resume_gap", "after": <the last event told>}, to readGET /v1/events?after=from. await stream.ping();await stream.unsubscribe(["SANDBOX-00042-002"]): an account unsubscribed stays out after a reconnect.- A subscribe the account stream refuses (
account_not_found,too_many_accounts) ends it withValidationError(account_idanddetailsname the account);stream.readyis set either way. A snapshot witherrorset could not be read now (its orders and positions are then empty): read that account by REST. - A refused upgrade (429 or 5xx) or a dropped connection is tried again (after its Retry-After), one log line each (
logging.getLogger("phoenixperps")at INFO, or the client'slogger); any other refusal ends the stream with the API's own error, as a REST call would. - The market stream reconnects after three heartbeats of silence and makes again the subscriptions the server still holds: unsubscribe needs only the channel and symbols (and
intervalfor candles; without it, every interval; without symbols, the whole channel).await market.list(),await market.ping();market.limitsare the hello's (subscriptions, symbols_per_subscribe, messages_per_s).
Helpers#
MarketRules(client.markets.get("BTC-USD")):round_price,round_size,size_for_notional,size_for_risk(risk_usd, stop_distance),worst_price(side, price, slippage_pct), in exact decimals with the market's own steps and slippage bounds (a side other than buy or sell, a slippage out of bounds or a value that is no decimal:ValidationError, aValueErrortoo). A size is rounded down to the step, even belowmin_size(it may be0): check it againstmin_sizebefore you order.Webhooks.verify(raw_body, headers, secret_or_secrets, tolerance_seconds=300): the WebhookPayload (the event, withapi_version,environmentandtest;webhook.pinghas noaccount_id), orWebhookVerificationError(aPhoenixPerpsError:missing_headers,stale,bad_signature,bad_body). Pass the body exactly as received.
Examples#
examples/01_accounts.py to 12_error_handling.py, the same twelve programs as in every SDK, each one in every language in the docs' cookbook. From the SDK's source: python examples/01_accounts.py.