GET /account/activity

Account activity

Account activity.

operationId: fetchAccountActivity · Rate-limit cost: 5

Declared server: https://api.testnet.nexus.xyz/v1. See Networks.

Not reachable through CCXT. CCXT's ledger is a record of balance movements: its amount is the change to the account's balance and its before / after bracket that change. This venue still cannot state either per entry — a fill's balance effect is its fee plus realized PnL, and no response anywhere carries a balance before or after — so the trade/liquidation rows here state quote notional in amount instead. A badge would still assert a correspondence that is false in the one field the method exists for, on a client published to npm that cannot be rolled back.

Authentication: agentAuth, hmacAuth.

Account activity

get

/account/activity

The account's activity as one time-ordered list, newest first — deposits, withdrawals, faucet claims, operator credits, fills, trading fees, funding payments and ordinary transfers merged server-side, each row carrying a typed cause.

Why this exists rather than five calls. A merge of five independently paginated lists cannot be paged correctly from the client: page 2 of the merge is not derivable from page 2 of each part, so a client-side join either loads everything or drops rows at the boundary. This operation does the merge before paginating, so the cursor walks the merged order.

This is a bounded window, and the bound is a merge of five. Each source is read to its own retained depth, and the answer is a complete merge only back to the shallowest of those floors. x-nexus-activity-truncated says whether any source ran out inside this answer and x-nexus-activity-complete-since-ms says where. Read both before concluding an account had no activity in a period — rows below the floor are still returned, they are just no longer a merge of all five causes.

Fee rows are separate rows. A fill that was charged a non-zero fee produces both a trade row and a fee row at the same timestamp. A fill charged nothing, and a fill that stated no fee at all, both produce no fee row — no money moved either way. GET /fills is where those two remain distinguishable, via the optional Fill.fee key.

Do not sum amount down the page as a balance reconciliation. trade and liquidation rows state quote notional, not a collateral movement, and failed withdrawals are listed too. A closing fill's real settled PnL is now available separately on those rows as realized_pnl (amount is unchanged by this). See ActivityEntry for the per-cause meaning of both fields.

Authorizations

X-API-KeystringRequired

HMAC API key authentication. Send three headers:

• X-API-Key: your key ID (e.g. nx_a1b2c3...)
• X-Timestamp: current time in unix milliseconds
• X-Signature: hex(hmac_sha256(secret, timestamp + "\n" + METHOD + "\n" + path + "\n" + query + "\n" + sha256_hex(body)))

Timestamp must be within 30 seconds of server time.

The key is network-scoped; the signature is not. The canonical string above has no network component, so the same signed request is byte-identical on every host. What stops a testnet key from authenticating against mainnet is that the key does not exist in that host's key store — sign only for the host that minted the key, and never replay a signed payload against another network. Presented to the wrong host, a key is refused with the same opaque 401 as an unknown key and must not be retried there. See “API keys are bound to one network” in the API description.

Query parameters

limitinteger · max: 1000Optional

Rows per page (default 100, capped at 1000). Bounds one page, not a cursor walk — see “Cursor pagination”. It does not deepen the merge either: each source is read to its own retained depth whatever limit asks for.

Default: 100

causestringOptional

Comma-separated ActivityEntry.cause values to return, e.g. cause=deposit,withdrawal. Omit for every cause. Repeats collapse and order is ignored.

Filtering happens server-side, before pagination, which is the point: filtering a page client-side gives you a short page rather than a filtered list.

An unrecognized value is a 400, not a silently unfiltered list — a filter that did not apply would show rows the caller asked to exclude with no way to tell. An empty value (cause=) is treated as no filter.

cursorstringOptional

Opaque pagination cursor returned in the previous response's X-Next-Cursor header. Omit to fetch the first page. Treat the token as opaque: its format is not part of the contract and may change. Cursors do not expire. A malformed (unparseable) cursor is not an error — the server serves the first page. A well-formed cursor whose exact position has since been evicted from the retained window is not reset to the first page: pagination resumes at the nearest surviving boundary, so a resumed response is a continuation, not a fresh first page. A cursor is not bound to an operation or an account, so use it only with the operation that issued it. See “Cursor pagination” in the API description for how a walk terminates and what it does and does not guarantee.

Responses

200

Activity rows, newest first.

application/json

400

cause named a value that is not an ActivityEntry.cause. Body: {"code": "unknown_cause", "message": …}.

401

Authentication failed. All 401 responses return the same opaque body to prevent information leakage. A credential minted on a different network is one of the causes it hides — by design, so that a key id cannot be probed for existence on another network. Do not retry it against another host.

application/json

429

Rate limit exceeded. Retryable — honour retry-after and back off; this is what separates a 429 from the permanent 403 jurisdiction refusals. Branch on the body's code, which is always RATE_LIMIT_EXCEEDED, and on bucket to learn WHICH budget bottlenecked — the buckets are independent, so a caller at its read ceiling can still submit orders and should not back off the whole client. Do not parse message: it is a diagnostic whose wording is not stable. Requests are charged by weight, so exhausting a budget takes fewer heavy calls than x-ratelimit-limit suggests. See “Rate limits” in the API description.

application/json

get/account/activity

GET /v1/account/activity HTTP/1.1
Host: api.testnet.nexus.xyz
X-API-Key: YOUR_API_KEY
Accept: */*

[
  {
    "id": "fee:cf72c7f3-1234-5678-abcd-ef0123456789",
    "timestamp": 1779225381434,
    "cause": "fee",
    "asset": "USDX",
    "amount": "-0.84",
    "amount_error": null,
    "realized_pnl": null,
    "market_id": "BTC-USDX-PERP",
    "reference_id": "ord_a1b2c3d4e5f6",
    "status": null,
    "tx_hash": null
  },
  {
    "id": "fill:cf72c7f3-1234-5678-abcd-ef0123456789",
    "timestamp": 1779225381434,
    "cause": "trade",
    "asset": "USDX",
    "amount": "-842.50",
    "amount_error": null,
    "realized_pnl": "12.50",
    "market_id": "BTC-USDX-PERP",
    "reference_id": "ord_a1b2c3d4e5f6",
    "status": null,
    "tx_hash": null
  },
  {
    "id": "funding:BTC-USDX-PERP:1779224400000",
    "timestamp": 1779224400000,
    "cause": "funding",
    "asset": "USDX",
    "amount": "-0.1273",
    "amount_error": null,
    "realized_pnl": null,
    "market_id": "BTC-USDX-PERP",
    "reference_id": null,
    "status": null,
    "tx_hash": null
  },
  {
    "id": "funds:00000000001779220000",
    "timestamp": 1779220000000,
    "cause": "deposit",
    "asset": "USDX",
    "amount": "5000",
    "amount_error": null,
    "realized_pnl": null,
    "market_id": null,
    "reference_id": null,
    "status": "confirmed",
    "tx_hash": "0x9f1c..."
  }
]

Test it cannot sign this request. X-Signature is an HMAC computed per call: see Authentication, or use an SDK.

---

_{API version 0.9.131}