PearlStack exposes a versioned JSON API for Pearl explorer data. Start anonymously, add an API key for a higher bucket, and use cursor pagination for list endpoints.
Anonymous requests work immediately:
curl "https://api.pearlstack.net/v1/status" curl "https://api.pearlstack.net/v1/blocks?limit=5" curl "https://api.pearlstack.net/v1/search?q=PearlHash"
Use an API key when you want a separate, higher rate-limit bucket:
curl -H "X-API-Key: psk_live_..." "https://api.pearlstack.net/v1/api/me" curl -H "Authorization: Bearer psk_live_..." "https://api.pearlstack.net/v1/blocks?limit=5"
API keys are optional for now. When present, the key is checked server-side and responses identify the current bucket through /v1/api/me.
X-API-Key: psk_live_... Authorization: Bearer psk_live_...
Every rate-limited response includes headers your client can use to avoid noisy retries.
X-RateLimit-Limit: 300 X-RateLimit-Remaining: 299 X-RateLimit-Reset: 1782466380 Retry-After: 12
List endpoints accept limit and cursor. The first request omits cursor. Use pagination.nextCursor for the next page.
curl "https://api.pearlstack.net/v1/blocks?limit=10" curl "https://api.pearlstack.net/v1/blocks?limit=10&cursor=<nextCursor>"
Legacy offset still works, but new integrations should use cursors.
JSON responses include meta so clients can log request ids and know how fresh the indexed data is.
PearlStack.net{
"meta": {
"requestId": "...",
"cached": false,
"indexedTip": 78030,
"indexedTipHash": "...",
"txIndexedTip": 78030,
"nodeHeight": 78404,
"servedAt": "..."
}
}Supported list endpoints return CSV with format=csv or Accept: text/csv.
curl "https://api.pearlstack.net/v1/blocks?limit=100&format=csv" curl "https://api.pearlstack.net/v1/txs?limit=100&format=csv" curl "https://api.pearlstack.net/v1/addresses/<prl1-address>/utxos?format=csv" curl "https://api.pearlstack.net/v1/miners/top?format=csv" curl "https://api.pearlstack.net/v1/pools/top?format=csv"
Pool detail CSV exports addresses by default. Use export=payouts or export=summary for the other flat views.
curl "https://api.pearlstack.net/v1/pools/PearlHash?format=csv" curl "https://api.pearlstack.net/v1/pools/PearlHash?format=csv&export=payouts" curl "https://api.pearlstack.net/v1/pools/PearlHash?format=csv&export=summary"
const baseUrl = "https://api.pearlstack.net";
async function latestBlocks() {
const response = await fetch(`${baseUrl}/v1/blocks?limit=5`, {
headers: { "X-API-Key": process.env.PEARLSTACK_API_KEY ?? "" },
});
if (!response.ok) throw new Error(`PearlStack HTTP ${response.status}`);
const data = await response.json();
return data.blocks;
}
latestBlocks().then(console.log);import os
import requests
base_url = "https://api.pearlstack.net"
headers = {}
if os.getenv("PEARLSTACK_API_KEY"):
headers["X-API-Key"] = os.environ["PEARLSTACK_API_KEY"]
response = requests.get(f"{base_url}/v1/blocks", params={"limit": 5}, headers=headers, timeout=10)
response.raise_for_status()
print(response.json()["blocks"]){
"ok": true,
"blocks": [...],
"pagination": {
"limit": 10,
"cursor": null,
"nextCursor": "eyJvZmZzZXQiOjEwfQ"
},
"meta": {
"requestId": "...",
"cached": false,
"indexedTip": 78030,
"nodeHeight": 78404,
"servedAt": "..."
}
}Errors return ok: false, an error message, and response metadata when they happen inside /v1.
HTTP/1.1 400 Bad Request
{
"ok": false,
"error": "cursor must be a valid pagination cursor",
"meta": {
"requestId": "...",
"indexedTip": 78030,
"nodeHeight": 78404,
"servedAt": "..."
}
}curl "https://api.pearlstack.net/v1/blocks?limit=5"
curl "https://api.pearlstack.net/v1/blocks/78030" curl "https://api.pearlstack.net/v1/blocks/78030/certificate"
curl "https://api.pearlstack.net/v1/txs?limit=5" curl "https://api.pearlstack.net/v1/txs/<txid>/flow" curl "https://api.pearlstack.net/v1/txs/<txid>/outputs?limit=25"
curl "https://api.pearlstack.net/v1/addresses/<prl1-address>" curl "https://api.pearlstack.net/v1/addresses/<prl1-address>/utxos?limit=25" curl "https://api.pearlstack.net/v1/addresses/<prl1-address>/flows?limit=25"
curl "https://api.pearlstack.net/v1/pools/top?limit=10" curl "https://api.pearlstack.net/v1/pools/PearlHash" curl "https://api.pearlstack.net/v1/pools/PearlHash/payout-outputs?limit=25"
curl "https://api.pearlstack.net/v1/market" curl "https://api.pearlstack.net/v1/market/chart?days=7" curl "https://api.pearlstack.net/v1/analytics/supply"
Browse indexed blocks, block transactions, block outputs, raw RPC payloads, and Pearl certificates.
GET /v1/blocksRecent blocks with miner labels and block fields. CSV supported.GET /v1/blocks/{heightOrHash}Block summary by height or hash.GET /v1/blocks/{heightOrHash}/txsTransactions included in a block.GET /v1/blocks/{heightOrHash}/outputsOutputs created in a block.GET /v1/blocks/{heightOrHash}/coinbase-outputsAll coinbase payout outputs for a block.GET /v1/blocks/{heightOrHash}/certificatePearl-native block certificate metadata.GET /v1/blocks/{heightOrHash}/rawStored raw block JSON.Fetch recent transaction flows, tx summaries, raw payloads, inputs, outputs, and counterparties.
GET /v1/txsRecent transaction feed with value, fee, type, and counterparties. CSV supported.GET /v1/txs/{txid}Transaction summary.GET /v1/txs/{txid}/flowInputs, outputs, fee, net flow, and counterparties.GET /v1/txs/{txid}/inputsPaginated transaction inputs.GET /v1/txs/{txid}/outputsPaginated transaction outputs.GET /v1/txs/{txid}/rawStored raw transaction JSON.Inspect balances, UTXOs, transaction history, balance history, and address flows.
GET /v1/addresses/{address}Address summary, balance, first/last seen, and known label.GET /v1/addresses/{address}/txsTransactions related to an address. CSV supported.GET /v1/addresses/{address}/utxosUnspent outputs for an address. CSV supported.GET /v1/addresses/{address}/balance-historyBalance history over indexed blocks.GET /v1/addresses/{address}/flow-summaryInflow/outflow summary.GET /v1/addresses/{address}/flowsPaginated address flow rows. CSV supported.Pool-aware miner analytics using payout addresses, known labels, and coinbase tag inference.
GET /v1/miners/topTop payout addresses by mined blocks. CSV supported.GET /v1/miners/{address}Miner summary and mined blocks for a payout address. CSV exports mined blocks.GET /v1/miners/{address}/blocks-over-timeDaily mined block counts for a payout address.GET /v1/pools/topTop pool groups by known label or inferred tag. CSV supported.GET /v1/pools/{poolId}Pool summary, payout addresses, and recent payout outputs. CSV exports addresses by default.GET /v1/pools/{poolId}/blocks-over-timeDaily mined block counts for a pool.GET /v1/pools/{poolId}/payout-outputsPaginated pool payout outputs. CSV supported.Network health, PoUW, supply, pool share, chart windows, and cached CoinGecko market data.
GET /v1/statusNode, database, and indexer status.GET /v1/analytics/networkDifficulty, hashrate estimates, node height, and indexer lag.GET /v1/analytics/block-windowsBlock chart windows for 24h, 7d, and 30d.GET /v1/analytics/tx-windowsTransaction chart windows for 24h, 7d, and 30d.GET /v1/analytics/pouwPoUW certificate analytics.GET /v1/analytics/supplyChain-derived emitted/circulating supply.GET /v1/analytics/holdersTop holders, rich list concentration, and wealth distribution.GET /v1/analytics/poolsPool share windows and difficulty/hashrate overlay data.GET /v1/marketCached CoinGecko market data enriched with PearlStack supply.GET /v1/market/chartCached price history. Supports days=1,7,30,90,365.GET /v1/analytics/marketStored market snapshots and cache health.Search, labels, mempool, and API introspection.
GET /v1/search?q=...Resolve block heights/hashes, txids, addresses, miners, and pool labels.GET /v1/search/suggest?q=...Autocomplete-style search suggestions.GET /v1/known-addressesKnown address and pool labels.GET /v1/mempoolPearl node mempool summary with bounded enrichment.GET /v1/mempool/txs/{txid}Pending mempool transaction details when available.GET /v1/api/meCurrent auth identity and rate-limit bucket.GET /v1/openapi.jsonOpenAPI 3.1 machine-readable schema.Use the OpenAPI document to generate clients, import into Postman, or keep a typed SDK in sync with the public API.
curl "https://api.pearlstack.net/v1/openapi.json"
Cache stable historical resources in your app, retry 429 only after Retry-After, and include your meta.requestId when reporting API problems.