API 文档

# HTTP
curl https://api.pmwallets.com/v1/account/fills?limit=100 -H "Authorization: Bearer $PMW_KEY"

# WebSocket — the handshake cannot set Authorization, so the key goes in its own header
const ws = new WebSocket("wss://api.pmwallets.com/v1/ws", { headers: { "x-api-key": process.env.PMW_KEY } });

# the board itself: who is making money, and on what. No key needed for the
# free sample; a key on an account with an active subscription raises the caps.
curl -s "https://api.pmwallets.com/v1/leaderboard?sort=realizedPnl&dir=desc&limit=50" \
  -H "Authorization: Bearer $PMW_KEY"

# ...and the same endpoint filtered. Every filter is a floor or an exact match;
# they combine with AND, and nothing here changes what a row CONTAINS.
curl -s "https://api.pmwallets.com/v1/leaderboard?\
minPnl=5000&\
minWinLo=0.55&\
minEligible=30&\
style=maker&\
category=sports&\
status=active&\
maxWallets=1&\
sort=winLo&dir=desc&limit=50" -H "Authorization: Bearer $PMW_KEY"

// GET /v1/leaderboard  →  200
{
  "periodId": "30d",
  "tier": "subscriber",
  "pricing": {
    "revealCents": 100,              // the cheapest band; what a row costs is on the row
    "subscriptionCentsPerHour": 5,
    "bands": [                       // from = the pnlExTop the band starts at; null = no floor
      { "band": 0, "from": null, "cents": 0 },
      { "band": 1, "from": 0.01, "cents": 100 },
      { "band": 5, "from": 5000, "cents": 500 }
    ]
  },
  "limits": { "maxRows": 200, "maxOffset": 100000, "capped": false,
              "dailyRows": 20000, "usedToday": 1250 },
  "rows": [
    {
      "entityId": "7KQ2MF9X4B1C",    // a HANDLE until you buy the address; then the address itself
      "label": "0x4b96…984e",        // masked until then
      "revealed": false,
      "revealCents": 300,            // what THIS address costs, from its own band
      "subscribed": false,
      "realizedPnl": 48213.5, "unrealizedPnl": 1204.0, "roiOnBuys": 0.184,
      "wins": 312, "losses": 89, "eligible": 401,
      "wr": 0.778, "lo": 0.735, "hi": 0.815,   // Wilson 95% bounds on the win rate
      "pnlExTop": 41902.1,           // profit with its single best market removed — the price band
      "style": "maker", "makerShare": 0.91,
      "wallets": 2, "nFills": 18422,
      "categories": [{ "category": "sports", "share": 0.62 }],
      "status": "active",
      "activity": { "lastFillTs": "2026-09-24 01:05:47", "fills24h": 412, "fills7d": 2980 },
      "dataSource": "live", "dataPeriodId": "30d"
    }
  ]
}

# buy the address behind a handle. maxPriceCents is REQUIRED and is a
# ceiling: it is the price you were shown, and the charge can never exceed it.
curl -X POST https://api.pmwallets.com/v1/account/reveals \
  -H "Authorization: Bearer $PMW_KEY" -H "content-type: application/json" \
  -d '{"entityId":"7KQ2MF9X4B1C","maxPriceCents":300}'

# what you already own, newest purchase first
curl -s https://api.pmwallets.com/v1/account/reveals -H "Authorization: Bearer $PMW_KEY"

// POST /v1/account/reveals  →  200
{
  "entityId": "0x4b96e2d59f0dabde95ae6f55f2d2d6d345ba984e",   // yours now
  "label": "0x4b96e2d59f0dabde95ae6f55f2d2d6d345ba984e",
  "priceCents": 300,
  "alreadyOwned": false            // true = you had it; nothing was charged
}

// 409 — the band moved between the page and the click. Nothing was charged.
{ "statusCode": 409, "error": "price_changed", "priceCents": 500, "agreedCents": 300 }

// 402 — not enough balance. Nothing was charged.
{ "statusCode": 402, "error": "insufficient_balance", "priceCents": 300, "balanceCents": 120 }

// GET /v1/account/reveals  →  200
[
  { "entityId": "0x4b96…984e", "priceCents": 300, "entitled": true,
    "createdAt": "2026-09-20T10:23:00.000Z", "paidAt": "2026-09-20T10:23:00.000Z" },
  // a FREE unlock whose wallet has since moved into a paid band: the address is masked again
  { "entityId": "9XQ4MF7K2B1C", "label": "0x8a1f…22ce", "priceCents": 0, "entitled": false,
    "revealCents": 200, "createdAt": "2026-09-18T08:00:00.000Z", "paidAt": null }
]

# the full 40-hex address the leaderboard shows — an abbreviated one is a 400"""
ENTITY=0x9d84ce0306f8551e02efef1680475fc0f1dc1344

curl -X POST https://api.pmwallets.com/v1/account/subscriptions \
  -H "Authorization: Bearer $PMW_KEY" -H 'content-type: application/json' \
  -d "{\"entityId\":\"$ENTITY\",\"channels\":[\"ws\",\"webhook\"]}"

# 409 if the entity has had no fill in 7 days — resend with "acceptInactive": true
# 402 if the balance will not cover the first hour; body carries price and balance

// POST /v1/account/subscriptions  →  201
{
  "id": "sub_9f2c1a7e",
  "userId": "usr_3b8d",
  "chain": 137,
  "entityId": "0x9d84ce0306f8551e02efef1680475fc0f1dc1344",
  "channels": ["ws", "webhook"],
  "status": "active",
  "fromBlock": 94146218,       // delivery starts AFTER this block
  "createdAt": "2026-09-21T02:14:07.611Z",
  "canceledAt": null
}

// GET /v1/account/subscriptions  →  200   (active + paused, newest first)
[ { "id": "sub_9f2c1a7e", "entityId": "0x9d84…", "status": "active", "fromBlock": 94146218, … } ]

// 402 — the balance will not cover the first hour
{ "statusCode": 402, "message": "insufficient balance for the first hour",
  "priceCentsPerHour": 5, "balanceCents": 0 }

// 409 — the entity has not traded recently; resend with acceptInactive
// (no figures about the entity: naming an address here would otherwise describe it for free)
{ "statusCode": 409, "message": "entity is dormant: no fill in the last 7 days",
  "status": "dormant", "hint": "resend with acceptInactive: true to subscribe anyway" }

# what is still being pushed — active and paused only, newest first
curl -s https://api.pmwallets.com/v1/account/subscriptions -H "Authorization: Bearer $PMW_KEY"

# stop one. Billing stops here; the hour already paid for is not refunded
curl -s -X DELETE https://api.pmwallets.com/v1/account/subscriptions/$SUB_ID \
  -H "Authorization: Bearer $PMW_KEY"

# restart one that ran out of balance. Charges another hour and resumes from the
# CURRENT head — the gap while it was paused is not backfilled
curl -s -X POST https://api.pmwallets.com/v1/account/subscriptions/$SUB_ID/resume \
  -H "Authorization: Bearer $PMW_KEY"

import WebSocket from "ws";

const ws = new WebSocket("wss://api.pmwallets.com/v1/ws", {
  headers: {
    "x-api-key": process.env.PMW_KEY,       // a handshake cannot set Authorization
  },
});

// Persist these across reconnects — comparing against a session you just overwrote
// can never detect anything.
let session = load("session"), seq = load("seq") ?? 0;
let lastBlock = load("block") ?? 0, lastLogIndex = load("logIndex") ?? 0;

// One message at a time: a replay is awaited, and a second frame arriving meanwhile
// would advance the cursor past the gap being repaired. Note the catch — chaining
// onto a rejected promise skips every later .then(), so a single failed replay would
// leave the socket open and silently processing nothing at all.
let queue = Promise.resolve();
ws.onmessage = (e) => {
  queue = queue
    .then(() => handleFrame(JSON.parse(e.data)))
    .catch((err) => { report(err); ws.close(); });   // reconnect and replay rather than go quiet
};

async function handleFrame(m) {
  if (m.type === "hello") {
    // A NEW session means frames were missed while the socket was down. Replay BEFORE
    // adopting it — overwriting session here is what silently swallows the outage.
    // a failing replay must not be swallowed: leave the cursor where it is and throw, so the
    // handler above closes the socket and the next connection tries again from the same place
    if (session !== null && m.session !== session) await replayFrom(lastBlock, lastLogIndex);
    session = m.session; seq = m.seq; save();
    return;
  }
  if (m.type !== "fill") return;

  if (m.session !== session || m.seq !== seq + 1) {   // dropped frame, or a session we never saw
    await replayFrom(lastBlock, lastLogIndex);
    session = m.session;
  }
  seq = m.seq;

  if (!seen.has(m.data.eventId)) { seen.add(m.data.eventId); handle(m.data); }
  lastBlock = m.data.block; lastLogIndex = m.data.logIndex;
  save();
}

// walk forward until the page is short; every row carries the same eventId as the stream
async function replayFrom(block, logIndex) {
  for (;;) {
    const r = await fetch(
      `https://api.pmwallets.com/v1/account/fills?sinceBlock=${block}&sinceLogIndex=${logIndex}&limit=500`,
      { headers: { "x-api-key": PMW_KEY } },
    );
    if (!r.ok) throw new Error(`replay failed: HTTP ${r.status}`);   // do NOT advance the cursor
    const page = await r.json();

    for (const row of page.rows) if (!seen.has(row.eventId)) { seen.add(row.eventId); handle(row); }
    if (!page.next) return;
    ({ sinceBlock: block, sinceLogIndex: logIndex } = page.next);
  }
}

import { createHmac, timingSafeEqual } from "node:crypto";

app.post("/hook", express.raw({ type: "application/json" }), (req, res) => {
  const sent = Buffer.from(req.header("x-pmw-signature") ?? "", "hex");
  const mine = createHmac("sha256", process.env.PMW_SECRET).update(req.body).digest();

  // compare the RAW body, before any JSON parsing: re-serialising changes the bytes
  if (sent.length !== mine.length || !timingSafeEqual(sent, mine)) return res.sendStatus(401);

  res.sendStatus(200);          // 2xx first — we retry anything else
  void handle(JSON.parse(req.body.toString()));
});

{
  "type": "fill",
  "data": {
    "eventId": "137:93912410:0x8f2c…a91b:0x4d0e…77c3:41",
    "chain": 137,
    "entityId": "0x9a3f…21e8",
    "wallet": "0x5b71…0cd2",
    "ts": "2026-09-16 14:02:11",
    "block": 93912410,
    "blockHash": "0x8f2c…a91b",
    "txHash": "0x4d0e…77c3",
    "logIndex": 41,
    "exchange": "pm_ctf_v2",
    "side": "BUY",
    "role": "taker",
    "tokenId": "3200000000…",
    "price": "0.570000",
    "shares": "3200000000",
    "usdc": "1824000000",
    "fee": "0"
  }
}

curl -X POST https://api.pmwallets.com/v1/account/exports/quote \
  -H 'content-type: application/json' \
  -H "Authorization: Bearer $PMW_KEY" \
  -d '{"entityIds":["0x9a3f…21e8"],"from":"2026-06-01","to":"2026-08-29"}'

{
  "window":   { "from": "2026-05-04", "to": "2026-09-19", "days": 139 },
  "from": "2026-06-01", "to": "2026-08-29", "days": 90,
  "sellable": true,
  "entities": 1,
  "orderPriceCents": 1260,
  "perEntityCents": 1260,
  "discount": 1,
  "price": { "cents": 1260, "usd": 12.6, "cny": 82 },
  "breakdown": [
    { "fromDay": 1,  "toDay": 30, "days": 30, "perDayCents": 17, "cents": 510 },
    { "fromDay": 31, "toDay": 60, "days": 30, "perDayCents": 14, "cents": 420 },
    { "fromDay": 61, "toDay": 90, "days": 30, "perDayCents": 11, "cents": 330 }
  ]
}

# same body as the quote — the price is recomputed here, never taken from the client
curl -X POST https://api.pmwallets.com/v1/account/exports \
  -H 'content-type: application/json' -H "Authorization: Bearer $PMW_KEY" \
  -d '{"entityIds":["0x9a3f…21e8"],"from":"2026-06-01","to":"2026-08-29"}'
# → {"id":"7c1e…","priceCents":1260,"days":90,"rows":12483,"status":"paid"}

# poll until ready
curl https://api.pmwallets.com/v1/account/exports/7c1e… -H "Authorization: Bearer $PMW_KEY"
# → {"id":"7c1e…","status":"ready","rows":12483,"fileBytes":412887,…}

# then mint a link (valid 15 minutes, minted fresh each time)
curl https://api.pmwallets.com/v1/account/exports/7c1e…/download -H "Authorization: Bearer $PMW_KEY"
# → {"url":"https://…r2.cloudflarestorage.com/…","expiresInSec":900,"fileName":"pmwallets-fills-…csv.gz"}

eventId,chain,entityId,wallet,ts,block,blockHash,txHash,logIndex,exchange,side,role,tokenId,price,shares,usdc,fee
137:93912410:0x8f2c…:0x4d0e…:41,137,0x9a3f…21e8,0x5b71…0cd2,2026-09-16 14:02:11,93912410,0x8f2c…,0x4d0e…,41,pm_ctf_v2,BUY,taker,3200000000…,0.570000,3200000000,1824000000,0