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.

Returns historical fills for one wallet, optionally filtered to a single market or time window. Same enriched row shape as /v1/markets/:id/trades, scoped to user_addr.

​
Endpoint

GET /v1/wallets/:addr/trades

​
Query parameters

ParamTypeDefaultDescription
outcome_idint—Filter to a single market
fromint—Lower bound time_us (microseconds since epoch)
toint—Upper bound time_us
limitint100Max rows (cap 1000)

​
Response (single trade row)

{
  "tid": 315031529611098,
  "oid": 407741532851,
  "outcome_id": 0,
  "coin": "#1",
  "side_index": 1,
  "side_label": "No",
  "side": {
    "raw": "B", "label": "buy",
    "description": "Bid side — buying outcome shares with USDH."
  },
  "px": "0.40485",
  "sz": "18.0",
  "notional_usdh": "7.287300",
  "role": {
    "raw": "true", "label": "taker",
    "description": "Removed liquidity by crossing the spread."
  },
  "direction": "Buy",
  "closed_pnl": "0",
  "fee": "0",
  "fee_token": {
    "raw": "+1", "label": "No shares",
    "description": "Buy-side fee deducted from received NO outcome shares (currently 0% rate).",
    "applies_to": "buy"
  },
  "builder_fee": null,
  "builder_addr": null,
  "deployer_fee": null,
  "tx_hash": "0x000...000",
  "at": { "us": 1777745780036000, "iso": "2026-05-02T18:16:20.036+00:00", "relative": "11m ago" }
}

​
Response wrapper

{
  "user": "0x14bb5440db38aa9f4eb3f11f9c12965ea6c342aa",
  "count": 100,
  "limit": 100,
  "trades": [ ... ]
}
FieldDescription
tidHL trade ID — unique per fill
oidHL order ID — multiple fills can share an oid for partial-fill orders
directionHL’s per-fill action label (Buy, Sell, Open Long, Close Short, etc.)
closed_pnlHL’s per-fill realized PnL — only set when this fill closes a position

​
Use cases

  • Wallet trade history page — paginated activity feed.
  • Tax export — combine with /positions?status=settled for full P/L reconstruction.
  • Backfill in chunks — page through history with to=<oldest tid time_us> shrinking each request.

​
Examples

# Last 50 fills for a wallet, all markets
curl -H "X-API-Key: hip4_live_..." \
  "https://hip4.polynode.dev/api/v1/wallets/0x14bb...c342aa/trades?limit=50"

# Only fills on outcome 0 in the last hour
curl -H "X-API-Key: hip4_live_..." \
  "https://hip4.polynode.dev/api/v1/wallets/0x14bb...c342aa/trades?outcome_id=0&from=$(date -d '1 hour ago' +%s)000000"

​
Notes

  • Sorted reverse-chronological (newest first).
  • A wallet can appear on BOTH sides of the same trade (self-trade). Those fills show with the same tid but different direction.
  • HIP-4 fills currently have tx_hash = 0x000...000 — they settle inside HL state, not on Polygon. The field is preserved for forward compatibility.