Working with the API
Pagination.
How lists answer: complete sets, pages with a cursor, the event log read from a point, and letting the SDK walk every page.
On this page
Every list answers in the same shape:
{ "data": [], "has_more": true, "next_cursor": "eyJzIjoiZmlsbHMi...", "as_of": 1791460800123 }as_of is when the oldest figure in the list was read, in Unix milliseconds.
Complete sets#
Some lists are always whole and never paged: the markets, your accounts, an account's open positions and working orders, your webhook endpoints and TradingView links. has_more is false and you have everything.
Pages#
History is paged, newest first: orders, fills, closed positions, strategies, webhook deliveries and TradingView alerts.
limitsets the page size: 1 to 200, 50 by default.- When
has_moreistrue, ask for the next page withcursorset tonext_cursor, and the same filters as the first call.
A cursor is good only for the list and filters that made it: anything else is refused with invalid_cursor. Pages never repeat an item or skip one, even when many share a millisecond.
The SDKs walk the pages for you:
import { PhoenixPerps } from "@phoenixperps/sdk";
const client = new PhoenixPerps();
for await (const fill of client.fills.list("SANDBOX-00042-001", {}, { maxItems: 500 })) {
console.log(fill.id, fill.price);
}for fill in client.fills.list("SANDBOX-00042-001").auto_paging_iter(500):
print(fill["id"], fill["price"])for fill, err := range client.Fills.ListAutoPaging(ctx, "SANDBOX-00042-001", nil, phoenixperps.WithMaxItems(500)) {
if err != nil {
log.Fatal(err)
}
fmt.Println(fill.ID, fill.Price)
}await foreach (var fill in client.Fills.ListAutoPagingAsync("SANDBOX-00042-001", options: new RequestOptions { MaxItems = 500 }))
Console.WriteLine($"{fill.Id} {fill.Price}");for (Fill fill : client.fills().listAutoPaging("SANDBOX-00042-001", null, RequestOptions.none().withMaxItems(500))) {
System.out.println(fill.id() + " " + fill.price());
}use futures_util::StreamExt; // the futures-util crate
let options = RequestOptions { max_items: Some(500), ..Default::default() };
let mut fills = client.fills().list_auto_paging("SANDBOX-00042-001", None, &options);
while let Some(fill) = fills.next().await {
let fill = fill?;
println!("{} {:?}", fill.id, fill.price);
}foreach ($client->fills->listAutoPaging('SANDBOX-00042-001', null, new PhoenixPerps\RequestOptions(maxItems: 500)) as $fill) {
echo $fill->id, ' ', $fill->price, PHP_EOL;
}The event log#
GET /v1/events is read from a point, oldest first: pass after the id of the last event you have, and you get the ones that came since. Without after, it starts from the oldest event kept (7 days). It is how you catch up after your bot was offline, and what the account stream uses to resume. Its next_cursor is that id: pass it as after (this list takes no cursor).