API documentation
build 2.0.0-dev · what the API is and how to get a key
The API and its data are provided as is, without warranty of any kind, and are not financial advice. Data comes from public blockchain networks and third-party sources and may be delayed, incomplete or wrong; unfinalized data can change. We accept no liability for loss arising from its use. API use is subject to your plan's limits. See the Terms of Use.
Machine-readable
/docs/endpoints.txt is one line per route — method, path, tier and purpose — generated from the same description.
Your first request
curl "https://api.pulsescanner.io/v2/blocks?limit=5" -H "X-Api-Key: psk_…"
A key travels as the X-Api-Key header or as an apikey query parameter — whichever your existing client already sends.
Starter, the lowest plan: 3 requests per second and 100,000 call units per day — what each endpoint costs, compare the plans.
The envelope
{"data": …, "next_cursor": "…" | null}
{"error": {"code": "…", "message": "…"}}Branch on which key is present, not on the status code — a 429 body is an error envelope, and a 401 or an unmatched route can arrive with no body at all.
An empty list is an answer, not an absence: a route with nothing to report answers {"data": []} and means it.
Paging
Lists are keyset-paginated. Pass the previous answer’s next_cursor back as ?cursor=.
It is set only when more rows exist — even on an exactly full page — and it is null on the last one. Formats differ per route and are not documented as parseable: send it back verbatim and never take it apart.
Parameters are strict: an unknown query parameter, a limit of zero, or a limit above a route’s ceiling are all rejected with a 400 naming what was wrong.
Status codes on this API
400The request was malformed — an unknown query parameter, or a limit above the route's ceiling.
401The request carried no key, or one this API does not recognise. A key comes with every plan and travels with every data call.
402The key is valid but the plan is not: either the account has no active plan (code plan_required, after the three-day grace) or the route starts at a higher plan than this one.
404No record matches. Can arrive with an empty body on an unmatched route.
429Rate limited. Transient — the same request succeeds shortly.
503Upstream unavailable. On /health during a replay this is by design, not an outage.
The Etherscan-compatible surface
curl "https://api.pulsescanner.io/api?module=proxy&action=eth_blockNumber&apikey=psk_…"
Every answer on this endpoint is HTTP 200, including refusals — a failure rides in the envelope. Branch on which key is present, never on the status code.
{"jsonrpc":"2.0","id":1,"result":"0x…"} — the call returned
{"jsonrpc":"2.0","id":1,"error":{"code","message"}} — the node refused it — `execution reverted` arrives here
{"status":"0","message":"NOTOK","result":"…"} — the gateway refused it before the node saw anything (bad module or action, missing key)
29 actions across 7 modules: account (7), block (3), logs (1), proxy (11), stats (2), token (3), transaction (2). Each action’s minimum tier is listed on the API page.
The v2 surface — 67 operations
Blocks and transactions /v2/blocks /v2/blocks/{num}/txs /v2/blocks/{num}/rewards /v2/txs/{hash} +4 more
The head lane /v2/head/blocks /v2/head/blocks/{num}/txs /v2/head/txs/{hash}
Tokens and pools /v2/tokens/{addr} /v2/tokens/{addr}/ohlc /v2/tokens/{addr}/richlist /v2/pools/{addr}/stats +6 more
Wallets /v2/wallets/{addr}/txs /v2/wallets/{addr}/networth /v2/wallets/{addr}/holdings +8 more
Consensus layer /v2/beacon/stats /v2/epochs /v2/slots /v2/validators/{idx} +5 more
Search and market /v2/search /v2/home/stats /v2/swaps /v2/protocols
Account and keys /v2/account /v2/account/keys /v2/account/usage /v2/account/siwe/nonce +17 more
Open, in no plan group /v2/plans
The complete list, with parameters and response schemas, is in /openapi.json.
What each call costs
A call unit (CU) is the API's metering unit; each endpoint costs a fixed number of units per request — see the cost list below.
| Operation | What it does | Plan required | Units per call |
|---|---|---|---|
GET /api | What it does Etherscan-compatible query surface: the module, action and address parameters an existing client already sends | Plan required Starter | Units per call 1, 2, 3 or 5 |
POST /api | What it does Etherscan-compatible query surface: the module, action and address parameters an existing client already sends | Plan required Starter | Units per call 1, 2, 3 or 5 |
GET /health | What it does Liveness probe: 503 once the indexed head is older than the configured staleness limit | Plan required None | Units per call 0 |
GET /openapi.json | What it does This API description, served from the same document the build publishes | Plan required None | Units per call 0 |
POST /rpc | What it does JSON-RPC 2.0 for wallets — key in the `X-Api-Key` header or `?apikey=` | Plan required Starter | Units per call 2 or 5 |
POST /rpc/{key} | What it does JSON-RPC 2.0 for wallets — key in the URL path segment (`/rpc/<key>`) | Plan required Starter | Units per call 2 or 5 |
GET /v2/account | What it does The signed-in account: its wallet, tier and current limits | Plan required None | Units per call 1 |
GET /v2/account/entitlements | What it does Every entitlement on the signed-in account, with its tier, bonus and effective window | Plan required None | Units per call 1 |
GET /v2/account/keys | What it does The account's API keys by prefix and status; a key's secret is shown once at creation and never again | Plan required None | Units per call 1 |
POST /v2/account/keys | What it does Create an API key and return its secret once | Plan required None | Units per call 1 |
DELETE /v2/account/keys/{id} | What it does Revoke an API key | Plan required None | Units per call 1 |
GET /v2/account/lists | What it does The account's address lists, each with its member count | Plan required None | Units per call 1 |
POST /v2/account/lists | What it does Create an address list | Plan required None | Units per call 1 |
DELETE /v2/account/lists/{id} | What it does Delete an address list and its members | Plan required None | Units per call 1 |
GET /v2/account/lists/{id} | What it does One address list and its members | Plan required None | Units per call 1 |
PATCH /v2/account/lists/{id} | What it does Rename an address list | Plan required None | Units per call 1 |
POST /v2/account/lists/{id}/addresses | What it does Add an address to a list | Plan required None | Units per call 1 |
DELETE /v2/account/lists/{id}/addresses/{address} | What it does Remove an address from a list | Plan required None | Units per call 1 |
POST /v2/account/logout | What it does End the current session | Plan required None | Units per call 1 |
GET /v2/account/pending | What it does Tier credits paid for by this wallet and not yet claimed | Plan required None | Units per call 1 |
POST /v2/account/siwe/nonce | What it does Issue a single-use nonce for a Sign-In With Ethereum message | Plan required None | Units per call 1 |
POST /v2/account/siwe/verify | What it does Verify a signed Sign-In With Ethereum message and open a session | Plan required None | Units per call 1 |
GET /v2/account/tags | What it does The account's private address labels | Plan required None | Units per call 1 |
GET /v2/account/tags/lookup | What it does Private labels for a batch of addresses, for annotating a page the account is viewing | Plan required None | Units per call 1 |
DELETE /v2/account/tags/{address} | What it does Delete the account's private label for one address | Plan required None | Units per call 1 |
PUT /v2/account/tags/{address} | What it does Create or replace the account's private label for one address | Plan required None | Units per call 1 |
GET /v2/account/usage | What it does Call units and request counts for the signed-in account, by day and endpoint class | Plan required None | Units per call 1 |
GET /v2/beacon/stats | What it does Beacon-chain totals: validator counts by status, participation, and the epoch they were read at | Plan required Starter | Units per call 1 |
GET /v2/blocks | What it does Recent blocks, newest first | Plan required Starter | Units per call 1 |
GET /v2/blocks/{num}/rewards | What it does One block's fee recipient, gas use and burnt fees, with its consensus reward | Plan required Starter | Units per call 1 |
GET /v2/blocks/{num}/txs | What it does Transactions in one block | Plan required Starter | Units per call 1 |
GET /v2/epochs | What it does Recent beacon epochs and their participation | Plan required Starter | Units per call 1 |
GET /v2/head/blocks | What it does Blocks from the head preview lane, ahead of the indexed head | Plan required Starter | Units per call 1 |
GET /v2/head/blocks/{num}/txs | What it does Transactions in one head-lane block, ahead of the indexed head | Plan required Starter | Units per call 1 |
GET /v2/head/txs/{hash} | What it does One transaction from the head preview lane, ahead of the indexed head | Plan required Starter | Units per call 1 |
GET /v2/home/stats | What it does The front page's headline numbers: PLS price and its 24-hour change, PLS burned, transaction count, and the block they were computed at | Plan required Starter | Units per call 1 |
GET /v2/plans | What it does Plans, limits and the endpoint map the web builds its comparison table from | Plan required None | Units per call 0 |
GET /v2/pools/new | What it does Pools registered most recently | Plan required Starter | Units per call 1 |
GET /v2/pools/{addr}/stats | What it does One pool's tokens, fee tier, reserves and recent volume | Plan required Lite | Units per call 3 |
GET /v2/protocols | What it does Registered dex protocols and the factories they are discovered by | Plan required Starter | Units per call 1 |
GET /v2/search | What it does Resolve a query to a transaction, block, address, token, validator, slot or epoch | Plan required Starter | Units per call 1 |
GET /v2/slots | What it does Recent beacon slots, including the ones no block was proposed for | Plan required Starter | Units per call 1 |
GET /v2/slots/{slot} | What it does One beacon slot: its proposer, block and status | Plan required Starter | Units per call 1 |
GET /v2/swaps | What it does Recent dex swaps across every registered protocol | Plan required Starter | Units per call 3 |
GET /v2/tokens/new | What it does Tokens seen most recently | Plan required Starter | Units per call 1 |
GET /v2/tokens/{addr} | What it does One token's metadata, supply and trust tier | Plan required Starter | Units per call 1 |
GET /v2/tokens/{addr}/ohlc | What it does Open, high, low and close candles for one token | Plan required Starter | Units per call 1 |
GET /v2/tokens/{addr}/pools | What it does Every registered pool holding one token | Plan required Starter | Units per call 1 |
GET /v2/tokens/{addr}/price | What it does One token's current price, with the anchor it was priced against | Plan required Starter | Units per call 1 |
GET /v2/tokens/{addr}/price/history | What it does One token's price over time | Plan required Starter | Units per call 1 |
GET /v2/tokens/{addr}/richlist | What it does The largest holders of one token, ranked by balance | Plan required Lite | Units per call 3 |
GET /v2/tokens/{addr}/transfers | What it does Transfers of one token, newest first | Plan required Starter | Units per call 1 |
GET /v2/txs/{hash} | What it does One transaction: its status, value, gas and decoded action | Plan required Starter | Units per call 1 |
GET /v2/txs/{hash}/internal | What it does Internal value transfers made by one transaction | Plan required Starter | Units per call 1 |
GET /v2/txs/{hash}/swaps | What it does Dex swaps decoded from one transaction | Plan required Starter | Units per call 1 |
GET /v2/txs/{hash}/trace | What it does The call tree of one transaction | Plan required Starter | Units per call 1 |
GET /v2/txs/{hash}/transfers | What it does Token transfers emitted by one transaction | Plan required Starter | Units per call 1 |
GET /v2/validators | What it does Validators in index order, oldest first, optionally narrowed to one status | Plan required Starter | Units per call 1 |
GET /v2/validators/entities | What it does Validators grouped by withdrawal address, or blocks grouped by the graffiti they carried | Plan required Starter | Units per call 1 |
GET /v2/validators/missed | What it does Validators ranked by the proposals they missed inside a 1d/7d/30d/90d window | Plan required Starter | Units per call 1 |
GET /v2/validators/slashed | What it does Validators that have been slashed | Plan required Starter | Units per call 1 |
GET /v2/validators/{idx} | What it does One validator: its status, balance and activation window | Plan required Starter | Units per call 1 |
GET /v2/wallets/{addr}/bridge | What it does Bridge transfers made by one wallet | Plan required Starter | Units per call 1 |
GET /v2/wallets/{addr}/holdings | What it does Every token one wallet holds, with its current value | Plan required Lite | Units per call 3 |
GET /v2/wallets/{addr}/networth | What it does One wallet's current net worth | Plan required Lite | Units per call 3 |
GET /v2/wallets/{addr}/networth/history | What it does One wallet's net worth over time | Plan required Lite | Units per call 3 |
GET /v2/wallets/{addr}/networth/replay | What it does One wallet's net worth recomputed across a window, for charting | Plan required Lite | Units per call 3 |
GET /v2/wallets/{addr}/positions | What it does One wallet's open liquidity positions | Plan required Lite | Units per call 3 |
GET /v2/wallets/{addr}/positions/items | What it does The individual items behind one wallet's liquidity positions | Plan required Lite | Units per call 3 |
GET /v2/wallets/{addr}/summary | What it does One wallet's headline balances and activity | Plan required Starter | Units per call 1 |
GET /v2/wallets/{addr}/trades | What it does Dex trades made by one wallet | Plan required Starter | Units per call 1 |
GET /v2/wallets/{addr}/txs | What it does Transactions involving one wallet, newest first | Plan required Starter | Units per call 1 |
GET /v2/wallets/{addr}/validators | What it does Validators whose withdrawal address is this wallet | Plan required Starter | Units per call 1 |
73 operations, read from the API's published description. Every one of them carries a cost class. The units are the document's own, read from its class table. The minimum tier 24 of them declare is a word no plan claims, so it is shown as the document writes it.
Keys
A key travels as the X-Api-Key header or as an apikey query parameter — whichever your existing client already sends.
An account can hold up to five keys. The key's value exists in exactly one response and nowhere else. Revoking is soft: the row stays in your key list marked revoked, so the list never disagrees with the API about what exists.
A minimum tier names the plan a route starts at: the standard endpoints start at Starter, and the heavy ones — the holder walks, the pool statistics and the wallet analytics — start at Lite.
Calls keep answering for three days after a plan's valid_until. After that grace period they answer plan_required, and buying a new term in the portal starts them again.
The portal reads the tier table straight out of the billing contract at the moment you look at it, so the figure it charges is the contract's own — a number copied onto a page could only go stale.
A term is bought and renewed in the same portal the keys live in. A lapse is not a key problem — the key stays valid and the refusal is a 402 about the plan, which is why nothing needs to be re-issued.
Renew or buy a term in the portal →Keys are minted, listed and revoked in the portal, which signs you in with your wallet rather than a password — see the API page.