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.

After a HIP-4 outcome resolves, every wallet that held a non-zero position at the moment of settlement gets a row here. The winning side gets 1 USDH per share, the losing side gets 0. This endpoint surfaces those payouts cleanly, without all the trade noise.

​
Endpoint

GET /v1/wallets/:addr/settlements
No query parameters — settlements aren’t paginated by default; one row per resolved market.

​
Response

{
  "user": "0xfaa4982c67494d8e778dd970236cf6b3d7a95d46",
  "count": 2,
  "totals": {
    "payout_total_usdh": "2350.0",
    "realized_pnl": "950.0",
    "wins": 1,
    "losses": 1,
    "win_rate": 0.5
  },
  "settlements": [
    {
      "outcome_id": 0,
      "title": "BTC >= $78213 by 2026-05-03 06:00 UTC (1d)",
      "underlying": "BTC",
      "target_price": "78213",
      "expiry_str": "20260503-0600",
      "settled_at": { "us": 1777788000000000, "iso": "2026-05-03T06:00:00+00:00", "relative": "0s ago" },
      "held_amount": "1000.0",
      "avg_cost": "0.65",
      "winning_side": 0,
      "held_winning": true,
      "result": "win",
      "payout_per_share": "1",
      "payout_total_usdh": "1000.0",
      "realized_pnl": "350.0"
    },
    {
      "outcome_id": 1,
      "title": "ETH >= $3500 by 2026-05-02 12:00 UTC (1h)",
      "settled_at": { "us": 1777723200000000, "iso": "...", "relative": "1d ago" },
      "held_amount": "5000.0",
      "avg_cost": "0.32",
      "winning_side": 1,
      "held_winning": false,
      "result": "loss",
      "payout_per_share": "0",
      "payout_total_usdh": "0",
      "realized_pnl": "-1600.0"
    }
  ]
}
FieldDescription
held_amountShares the wallet held when the market settled
avg_costWeighted-average cost basis at settle time (USDH per share)
winning_sideThe side that resolved YES
held_winningtrue if this wallet’s position was on the winning side
resultFriendly form: "win" or "loss"
payout_per_share1 if held_winning, else 0
payout_total_usdhheld_amount × payout_per_share
realized_pnlpayout_total - (held_amount × avg_cost)
Totals fieldDescription
payout_total_usdhSum of payouts across all settlements
realized_pnlSum of realized_pnl — net P/L from resolutions only
wins / lossesCounts of winning vs losing positions
win_ratewins / (wins + losses) — null if no settlements yet

​
Use cases

  • Resolution log for a wallet’s profile page — clean, no order/trade noise.
  • Track-record stats — win_rate and total realized P/L for a leaderboard or rep score.
  • Tax / accounting — payout_total and realized_pnl per resolved market is what you actually need to report.

​
Examples

curl -H "X-API-Key: hip4_live_..." \
  https://hip4.polynode.dev/api/v1/wallets/0xfaa4...5d46/settlements

​
Notes

  • Returns count: 0 cleanly when the wallet has no settled positions.
  • realized_pnl here is the FINAL P/L of that position (settlement payout minus cost basis). It does NOT match the intraday realized_pnl returned by /v1/wallets/:addr/positions, which is the intraday-close-only PnL before settlement.
  • A wallet with both a Yes and a No leg open at resolution gets TWO rows — one win, one loss. The total still nets out correctly.
  • Settlements appear here within seconds of the on-chain resolution event.