Explorer REST API
This is the ExtraSafe Explorer API (not an Etherscan-compatible API). Base URL:
https://testnet-api.extrasafe.net.
All quantities are exact integer strings; responses carry generationId, recovery and
block-observation context where relevant. Errors use {code, message, requestId, retryAfterSeconds?}
with Retry-After on 429. The full machine-readable spec is at
/openapi.json.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/network | Authoritative network manifest (chain id, RPC URL, assets, contracts, policies). |
| GET | /api/v1/status | Operational status: node/restore state, heads, checkpoint age, faucet, price, swap. |
| GET | /api/v1/blocks?cursor=&limit= | Canonical blocks, newest first (cursor pagination, default 25, max 100). |
| GET | /api/v1/blocks/{numberOrHash} | One block by decimal number or 0x-hash. |
| GET | /api/v1/blocks/{numberOrHash}/transactions | Transactions of a block. |
| GET | /api/v1/transactions?cursor=&limit= | Recent canonical transactions. |
| GET | /api/v1/transactions/{hash} | Transaction detail: receipt status, fee (gasUsed × effectiveGasPrice), logs, decoded token transfers and project swap events. |
| GET | /api/v1/addresses/{address} | Checksummed address: live vETH balance + nonce with observation block, code label, vUSD balance, indexed activity. |
| GET | /api/v1/addresses/{address}/transactions | Top-level transactions for an address. |
| GET | /api/v1/addresses/{address}/token-balances | Supported token balances at an observed block. |
| GET | /api/v1/addresses/{address}/token-transfers | ERC-20 transfer events touching the address. |
| GET | /api/v1/tokens/{address} | Registered token: metadata, initial vs current supply, mint/burn totals, genesis allocation ("Installed at genesis", null deployment tx). |
| GET | /api/v1/tokens/{address}/transfers | Token transfer history. |
| GET | /api/v1/search?q= | Exact address / tx hash / block hash / decimal block number. |
| GET | /api/v1/prices/eth-usd | External ETH/USD REFERENCE price (scale 1e8) with source + provider timestamp + freshness. |
| GET | /api/v1/initial-grants/{address} | One-time grant record/status for the active generation (explicit not_yet_requested state). |
| POST | /api/v1/initial-grants/challenges | Short-lived challenge bound to recipient + program. |
| POST | /api/v1/initial-grants/ensure | Idempotent ensure of THE single entitlement (Idempotency-Key header; 202). |
| GET | /api/v1/faucet/policy | Both recurring choices, exact units, shared 60s cooldown, 1000.00 combined threshold, price-freshness rules. |
| GET | /api/v1/faucet/eligibility?address=&assetId= | Advisory eligibility with both observed balances at one block + priceId. |
| POST | /api/v1/faucet/challenges | Challenge bound to recipient, asset, program, generation, client and server-selected amount. |
| POST | /api/v1/faucet/claims | Accepts a claim (202 + claimId + statusUrl + nextEligibleAt). Clients never choose amounts. |
| GET | /api/v1/faucet/claims/{id} | Actual transaction/receipt/checkpoint state of a claim. |
| GET | /api/v1/swap/config | Swap contract, canonical EIP-712 domain/types, bounds, fee and freshness policy. |
| GET | /api/v1/swap/liquidity | Observed reserves (never a reservation). |
| POST | /api/v1/swap/quotes | Signed exact-input quote {chainId, generationId, taker, direction, amountIn}. |
| GET | /api/v1/swaps?address=&cursor=&limit= | Indexed SwapExecuted history. |
| GET | /api/v1/swaps/{transactionHash} | One indexed swap. |
| GET | /openapi.json | Machine-readable OpenAPI specification. |
| GET | /health/live · /health/ready | Liveness vs readiness (distinct). |
| POST | /rpc/{chainId} | Restricted wallet JSON-RPC: standard reads + eth_sendRawTransaction only; admin/node-signing methods are blocked, including inside batches. |
curl: request a faucet grant
# 1. challenge
curl -s https://testnet-api.extrasafe.net/api/v1/faucet/challenges \
-H 'content-type: application/json' \
-d '{"recipient":"0xYourAddress","assetId":"vUSD","clientId":"my-app"}'
# 2. claim (one 60s cooldown per address across BOTH assets)
curl -s https://testnet-api.extrasafe.net/api/v1/faucet/claims \
-H 'content-type: application/json' \
-H 'Idempotency-Key: my-unique-key-1' \
-d '{"recipient":"0xYourAddress","assetId":"vUSD",
"clientId":"my-app","challengeId":"<from step 1>",
"turnstileToken":"<when required>"}'
# 3. poll actual transaction state
curl -s https://testnet-api.extrasafe.net/api/v1/faucet/claims/<claimId> JavaScript: read a transaction
const res = await fetch(
'https://testnet-api.extrasafe.net/api/v1/transactions/0x…hash…',
{ credentials: 'omit' }
)
const tx = await res.json()
// receipt.status based — null receipt is pending/unknown, never success
console.log(tx.status) // 'success' | 'reverted' | 'pending' | …
console.log(tx.fee) // gasUsed × effectiveGasPrice, wei string
console.log(tx.tokenTransfers) // decoded from successful receipt logs
Wallet JSON-RPC
curl -s https://testnet-api.extrasafe.net/rpc/<chainId> \
-H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' Integration notes
- Public endpoints use CORS with
credentials: 'omit'; registered origins may also sendIdempotency-KeyandX-Client-Id. Public client ids are not authentication. - Owner/admin endpoints (
/auth/*,/api/v1/admin/*) are same-origin only through the site's proxy, Google-authenticated, CSRF-protected and never cached. They are not available to widget origins. - There is no endpoint that accepts plaintext owner keys, mnemonics or backup passphrases; encrypted owner backups move directly between the owner's browser and Google Drive.
- Unsupported JSON-RPC methods return proper JSON-RPC errors — also inside batch requests.