Skip to main content

Documentation Index

Fetch the complete documentation index at: https://hypernode-docs.polynode.dev/llms.txt

Use this file to discover all available pages before exploring further.

One call, four event types merged into a single chronological stream. Each row has a kind field (trade, order, ledger, settlement) plus the type-specific payload. Use this to render an activity feed without making four separate requests.

​
Endpoint

GET /v1/wallets/:addr/activity

​
Query parameters

ParamTypeDefaultDescription
kindsstring CSVallFilter to specific kinds: trade,order,ledger,settlement
fromint0Lower bound time_us
toint—Upper bound time_us
limitint200Max rows total across all kinds (cap 1000)

​
Response (one row per kind)

{
  "user": "0xfaa4982c67494d8e778dd970236cf6b3d7a95d46",
  "kinds_included": ["ledger", "order", "settlement", "trade"],
  "count": 5,
  "limit": 5,
  "activity": [
    {
      "kind": "order",
      "at": { "us": 1777747230234902, "iso": "...", "relative": "12m ago" },
      "oid": 407758903701,
      "status": { "raw": "open", "label": "open", "description": "Order placed and resting in the book." },
      "outcome_id": 0,
      "coin": "#0",
      "side_index": 0,
      "side_label": "Yes",
      "side": { "raw": "B", "label": "buy", "description": "..." },
      "limit_px": "0.64404",
      "sz": "16.0",
      "orig_sz": "16.0",
      "order_type": "Limit",
      "tif": { "raw": "Ioc", "label": "Immediate Or Cancel", "description": "..." }
    },
    {
      "kind": "trade",
      "at": { "us": 1777745780036000, "iso": "...", "relative": "36m ago" },
      "tid": 315031529611098, "oid": 407741532851,
      "outcome_id": 0, "coin": "#1",
      "side_index": 1, "side_label": "No",
      "side": { "raw": "B", "label": "buy", "description": "..." },
      "px": "0.40485", "sz": "18.0", "notional_usdh": "7.287300",
      "role": { "raw": "true", "label": "taker", "description": "..." },
      "direction": "Buy",
      "closed_pnl": "0", "fee": "0",
      "fee_token": { "raw": "+1", "label": "No shares", "description": "..." }
    },
    {
      "kind": "ledger",
      "at": { "us": 1777733000000000, "iso": "...", "relative": "5h ago" },
      "id": 142,
      "delta_type": "spotTransfer",
      "tx_hash": "0x...",
      "counterparty": "0x...",
      "token": "USDH",
      "amount": "1000.0",
      "usdc_value": "1000.0"
    },
    {
      "kind": "settlement",
      "at": { "us": 1777788000000000, "iso": "...", "relative": "12h ago" },
      "outcome_id": 0,
      "held_amount": "1000.0",
      "avg_cost": "0.65",
      "winning_side": 0,
      "held_winning": true,
      "payout_per_share": "1",
      "payout_total": "1000.0",
      "realized_pnl": "350.0"
    }
  ]
}

​
Event kinds

KindWhat it is
tradeA fill on one of your orders (or one of your makers being hit)
orderOrder placement, fill, cancel, rejection — the full state machine
ledgerSpot-balance changes: transfers, sends, borrows, lending
settlementMarket resolution event with payout + realized PnL

​
Use cases

  • Wallet activity feed — render a unified stream like Etherscan or Polymarket’s “Activity” tab.
  • Audit trail — every state change to a wallet’s HIP-4 footprint, time-ordered.
  • Filter to specific event — kinds=ledger for a deposits-only view, kinds=settlement for a closed-trade log.

​
Examples

# Last 100 events of any kind
curl -H "X-API-Key: hip4_live_..." \
  "https://hip4.polynode.dev/api/v1/wallets/0xfaa4...5d46/activity?limit=100"

# Only trades + settlements (clean P/L view)
curl -H "X-API-Key: hip4_live_..." \
  "https://hip4.polynode.dev/api/v1/wallets/0xfaa4...5d46/activity?kinds=trade,settlement"

​
Notes

  • The limit is global across all kinds — if you ask for 200 with all 4 kinds enabled, you get 200 events total (newest-first), not 200 of each.
  • Events sorted reverse-chronological by time_us (or settled_us for settlements).
  • Same tid will appear once per fill — both sides of a self-trade show as separate rows.
  • Order placements that immediately fill produce BOTH an order event (with status open then filled) AND a trade event with the same oid.