# BSCPulse AI — paid on-chain signal API for AI agents

Machine-to-machine paid API. Pay per call with x402 (HTTP 402) on BNB Smart Chain,
or buy a prepaid license key and call with a Bearer token.

Base URL: https://api.newbeebnb.cn
Network: eip155:56 (BNB Smart Chain mainnet)
Asset: USDT 0x55d398326f99059fF775485246999027B3197955 (18 decimals)
Pay to: 0xeB6611AAB4E9a23e44E685AF4D2B787DF77F08Eb  |  facilitator pays gas

## How to pay (per call)
1. GET any priced route without payment -> HTTP 402 with `accepts[0]` (x402 v2 PaymentRequired).
2. Sign it with your wallet:  baw x402-payment preview --paymentRequirements "<402 body>" --json
                              baw x402-payment sign --paymentId <id> --selectedIndex 1 --json
3. Replay the same request with header:  PAYMENT-SIGNATURE: <paymentHeaderValue>
4. On success you get HTTP 200 with `{ok, via, data, payment:{amount,payer,tx}}`.

Free tier: the first N calls per IP per day on free routes return 200 with `via:"free"`.

## Routes
- GET /v1/flap/status  —  0.02 U  (free tier)
    FLAP snapshot: price, liquidity, market cap, holders, top10 concentration, 24h/4h volume, 24h deltas.
- GET /v1/signal/{symbol}  —  0.05 U  (free tier)
    Latest scanner record for one BSC token: liquidity, market cap, holders, 1h inflow, change, analyst note.
- GET /v1/signals/recent  —  0.1 U
    Recent scanner alerts (deduped) as a ranked list. Query: hours(1-168), limit(1-100).
- GET /v1/token/{contract}/report  —  0.2 U
    Full observation dossier for one token (chain: 56=BSC, CT_501=Solana): observation count, first/last seen, market-cap first/last/peak multiple, liquidity & holder deltas, alert counts, downsampled timeline. Query: points(1-100).
- GET /v1/attribution/{contract}  —  0.2 U
    Post-alert attribution: baseline at first alert, market cap at +1h/+6h/+24h, peak multiple, latest drawdown. Query: horizon(1-168).
- GET /v1/alerts/today  —  0.05 U
    Rolling alert digest: deduped count, source breakdown, top by liquidity and by 1h net inflow. Query: hours(1-168), limit(1-50).
- GET /v1/kol/leaderboard  —  0.05 U
    KOL leaderboard from Binance Web3 public KOL labels: label, X handle, realized PnL, balance, last 7 daily PnL. Query: chain(all|56|CT_501), limit(1-50).
- GET /v1/kol/dumps  —  0.1 U
    KOL dump board: every (KOL, token) pair that trips a fixed rule - 割 (followers underwater >=40%), 背刺 (first buy then clear within 24h, token -25% after), 先跑 (sold, token -30% after). Points at the KOL by name with recomputable evidence. Query: hours(1-720), limit(1-100), verdict(all|割|背刺|先跑).
- GET /v1/kol/token/{contract}  —  0.05 U
    KOL view of one token: which KOLs bought/sold it, net USD per KOL, first-buy/last-sell times, and any verdicts on this token.
- GET /v1/kol/{address}  —  0.1 U
    One KOL dossier: label, X handle, realized PnL, current holdings across tokens, recent trades with USD value, and verdict counts (割/背刺/先跑) with evidence. Query: limit(1-100).
- GET /v1/license/{plan}  —  day=0.5 U, pro=8 U
    Buy a prepaid license key (plan: day|pro). Pay once, then call with Authorization: Bearer <key>.

## License (recommended for agents: bypasses the 20 USDT/day x402 wallet cap)
- plan `day`: 0.5 U, quota 200 calls, valid 24h
- plan `pro`: 8 U, quota 5000 calls, valid 720h
  Buy: GET /v1/license/{plan} with the x402 flow above -> response contains `data.licenseKey`.
  Use: Authorization: Bearer <licenseKey>   Check: GET /v1/license/status

## Errors
- 402 payment required / payment invalid  (retry after signing a fresh 402)
- 409 signature already used  (that exact signature was already settled; sign a new one)
- 429 rate limit exceeded
- 404 no data for that symbol

Machine-readable price list: https://api.newbeebnb.cn/pricing.json
OpenAPI: https://api.newbeebnb.cn/openapi.json

KOL endpoints use Binance Web3 public KOL labels. Verdicts (割/背刺/先跑) are computed by
fixed rules over those trades and market-cap snapshots, and every verdict ships its evidence
(timestamps, USD size, market cap at buy/sell, drawdown after exit) so it can be recomputed.
Labels are Binance's, not ours, and may be wrong or stale.

Data is aggregated from public on-chain sources. Not investment advice.