SDKs
Java SDK.
The Phoenix Perpetuals API for Java: every REST call, the account stream and market data, with retries, idempotency keys, paging and typed errors. Java 17 or later; one dependency (Jackson).
Source: java/ on GitHub, MIT. Version 1.2.0, the same for all seven SDKs: releases. Java 17+. Package com.phoenixperpsfunding:phoenixperps-sdk.
repositories {
mavenCentral()
maven("https://phoenixperps.github.io/sdk/maven")
}
dependencies {
implementation("com.phoenixperpsfunding:phoenixperps-sdk:1.2.0")
}A first call:
import com.phoenixperpsfunding.sdk.PhoenixPerpsClient;
import com.phoenixperpsfunding.sdk.gen.*;
import java.math.BigDecimal;
PhoenixPerpsClient client = PhoenixPerpsClient.fromEnv(); // PHOENIXPERPS_API_KEY
Account account = client.accounts().list().data().get(0);
Order order = client.orders().create(account.id(), new CreateOrder()
.market("BTC-USD")
.side(OrderSide.BUY)
.type(CreateOrderType.MARKET)
.size(new BigDecimal("0.01")));The client#
PhoenixPerpsClient.builder().apiKey(..).environment(..).baseUrl(..).timeout(..).maxRetries(..).appInfo(..).httpClient(..).logger(..).build()
- The key comes from
apiKey, elsePHOENIXPERPS_API_KEY. The environment comes from the key itself (ppk_live_,ppk_test_;PHOENIXPERPS_ENVIRONMENTonly for a key without one;liveorsandboxin any case); a key of the other environment fails atbuild(), before any request. - Without a key the client is made all the same: the public calls (
markets(),platform()) work, sent without Authorization; any other answers the API'smissing_api_key. baseUrl(elsePHOENIXPERPS_BASE_URL) is the API host; the REST address as the docs write it (.../v1) works too. It moves the REST calls only: the streams takestreamUrls(account, market).- Every call has an overload taking
RequestOptions(withIdempotencyKey,withTimeout,withMaxRetries,withHeaders,withOnResponse). - The key never appears in
toString(), the client's JSON or an exception (client.maskedKey()shows its end). loggerreceives a line per retry (a call's, or a stream's reconnect with its cause) and one per deprecated API version.
Calls#
Resources follow the API: platform(), me(), markets(), accounts(), history(), margin(), positions(), orders(), fills(), exits(), strategies(), alerts(), events(), webhookEndpoints(), tradingView(). Prices and sizes are BigDecimal, exact, sent as strings. Enums are open: a value from a newer API is kept as is, and fields this version does not know land in extra().
- A call is tried again only when that is safe (a read, a route the API marks retry-safe, or a call carrying an Idempotency-Key: an order change given one with
withIdempotencyKeytoo), after a network failure, a timeout (the answer's body included) or an answer the API marksretryable(so a 409operation_in_progressis asked again, a 503sandbox_disabledis not). Writes get one Idempotency-Key, the same on every attempt. Retry-Afteris honoured, fractions included; one over 60 s is not slept: the call throwsRateLimitExceptionwithretryAfter().- With a rate-limit budget used up, the next call of that budget waits for its reset instead of drawing a 429.
- An
If-None-Match(withHeaders) that still matches answersnull(a list call too, never an empty page): the API's empty 304, nothing changed;withOnResponsesees the 304 and its ETag. - A 2xx whose body is not JSON (a proxy's page) is an error (
http_<status>), never an empty answer. - A route newer than this SDK:
client.request("GET", "/v1/...", query, body, options)sends it with the key, retries and errors, and answers theRawResponseas it came (a write is tried again only withwithIdempotencyKey).
Lists#
Page<Order> page = client.orders().list(accountId, new OrdersListParams().status(OrdersListParamsStatus.WORKING));
Page<Order> next = page.nextPage(); // null after the last
Object complete = page.extra().get("history_complete"); // the list's other fields
for (Fill fill : client.fills().listAutoPaging(accountId, null, RequestOptions.none().withMaxItems(500))) {
}Errors#
Every failure is a PhoenixPerpsException with code(), status(), getMessage(), requestId(), details(), retryAfter(), retryable(), docUrl(), orderId(), idempotencyKey() and headers(). Its class tells the family: AuthenticationException (401), PermissionException (403), NotFoundException, ConflictException (409), ValidationException (400), RuleRejectedException (422: the account's rules said no), RateLimitException, ServerException, ApiConnectionException, ApiTimeoutException, Webhooks.VerificationException. Every code the API answers is a constant of ErrorCodes.
Streams (read only; orders go through REST)#
AccountStream.Options options = AccountStream.options()
.risk(true).onRisk(frame -> System.out.println(frame)) // risk frames as they come
.onGap(after -> System.out.println("read GET /v1/events?after=" + after)); // what a reconnect could not resume
try (AccountStream stream = client.openAccountStream(options)) {
for (Event e : stream) { // each event once, resumed after reconnects; e.extra() keeps its frame's seq and replayed
}
}
try (MarketStream market = client.openMarketStream()) {
market.subscribe("ticker", List.of("BTC-USD"), Map.of("interval_ms", 250), Duration.ofSeconds(10));
for (MarketStream.Frame f : market) {
}
}- Both reconnect by themselves (a line to the
loggereach time). What a reconnect cannot change ends the stream, thrown bynext()/poll()and byready(): an upgrade refused for good (401, 403, 404...: not 429 or 5xx) with the server's error, the account stream's subscribe refused (too_many_accounts,account_not_found) with aValidationException(itsdetails()name the account), 4001 with anAuthenticationException. - A resume the server cannot cover (its
resume_gapnotice) and a 4008 (too far behind) are gaps: told toonGapand theloggerwith the last event id told, to readGET /v1/events?after=from. - A snapshot with an
error(state_unavailable) is an account that could not be read just now, not a flat one. stream.ping(wait)andstream.unsubscribe(accounts, wait)on the account stream (an account unsubscribed stays out after a reconnect);market.list(wait)andmarket.ping(wait)on the market stream.- A market subscription is one channel, one market and (candles) one interval; its other params are settings the last subscribe sets.
market.unsubscribe(channel, symbols, params, wait)names the markets and (candles, in params) the interval, nothing else; without an interval it ends every interval of those markets. Made again after a reconnect, a subscription asks its history again.market.limits()is what the hello allows (subscriptions,symbols_per_subscribe,messages_per_s); anerrorframe keeps itsdetails().
Helpers#
new MarketRules(client.markets().get("BTC-USD")):roundPrice,roundSize,sizeForNotional,sizeForRisk(riskUsd, stopDistance),worstPrice(side, price, slippagePct)(anOrderSide, or"buy"/"sell"in any case), in exact decimals, fromBigDecimals or decimal strings. Each answers theBigDecimalan order takes, at the step's decimals (.size(rules.sizeForNotional(usd, bid))). Another side, a slippage outside the market'smax_slippage_pctbounds, a price or stop distance of 0 or a string that is no decimal throws aValidationException. A size is answered as it rounds, 0 included: check it againstminSize()before you order.Webhooks.verify(rawBody, headers, secret): theWebhookPayload(the event, withapiVersion(),environment()andtest();webhook.pingincluded), or aWebhooks.VerificationException(missing_headers,stale,bad_signature,bad_body). Pass the body exactly as received.
Examples#
examples/01-accounts.java to 12-error-handling.java (compiled with the SDK), the same twelve programs as in every SDK, each one in every language in the docs' cookbook. From the SDK's source: gradle -q example -Pn=01.