Skip to main content
POST
Copy PnL Batch
Uses the same Copy PnL calculation, coverage, and response fields for each wallet. This replaces the deprecated V2 on-demand batch.

Request

Send parameters in a JSON object, with a body no larger than 16 KiB. Unknown fields, invalid options, and invalid batch sizes return 400. An invalid wallet within an otherwise valid batch produces an error for that row. Results preserve input order and duplicate entries. Duplicate normalized wallets with the same options share calculation work. Wallets use different snapshots; relative periods are anchored to each calculation, so use explicit from and to to fix the same dates across the batch. The whole HTTP batch counts as one API request under normal V3 account limits; the old V2 five-second throttle does not apply. Every successful row includes separately scoped lifetime realized_pnl_context. Date filters apply to the copying simulation, not to that stored lifetime context. In auto, some wallets may return full history and others the completed recent-window fallback. Inspect data.coverage.served_history, history_truncated, and fallback_reason for every row. In full, incomplete histories become individual errors. See history modes and work limits.

Response and partial failures

The envelope contains results, requested, succeeded, failed, max_trades, and elapsed_ms. A valid batch returns HTTP 200 even if some or all wallets fail. Always inspect status on every result. For example, an invalid wallet row is:
Work is scheduled with bounded concurrency. Each calculation has a ten-second database budget, and the batch has a 25-second queue/result deadline inside the public request timeout. A maximum-size batch is accepted, but 100 uncached heavy wallets are not guaranteed to finish in that deadline. Start with batches of 5–10 for interactive use. Keep successful results and retry only transient failures in smaller batches; changing max_trades changes the analysis window. Automatic expansion has up to two additional seconds per wallet within the existing ten-second calculation budget. It never silently lowers the requested fallback cap or returns a partly calculated financial total. The endpoint does not create a background job or update V2 BYOB wallets.

Authorizations

x-api-key
string
header
required

Body

application/json
wallets
string[]
required

Invalid addresses produce per-row errors.

Required array length: 1 - 100 elements
max_trades
integer
default:50000

Recent/fallback fill cap per wallet; initial scan size in full mode. Auto/full may return more fills, up to the 500000-fill work limit.

Required range: 1 <= x <= 50000
history
enum<string>
default:recent

recent keeps the cap; auto attempts full history with an explicit recent fallback; full requires complete matching history or returns an error.

Available options:
recent,
auto,
full
period
enum<string>

Optional window ending at to or the calculation snapshot. No default period. Explicit from overrides period.

Available options:
7d,
14d,
30d,
60d,
90d,
180d
from

Inclusive start: Unix seconds or YYYY-MM-DD at UTC midnight. Applies to fills and settlement events, not lifetime realized-PnL context.

Required range: 0 <= x <= 253402300799
to

Exclusive end: Unix seconds or YYYY-MM-DD at UTC midnight. Defaults to the calculation snapshot.

Required range: 0 <= x <= 253402300799

Response

Ordered results; inspect status on every row

results
object[]
required
requested
integer
required
succeeded
integer
required
failed
integer
required
max_trades
integer
required
elapsed_ms
integer
required