Skip to content
ExtraSafe Testnet Test assets only — no monetary value

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.

MethodPathDescription
GET/api/v1/networkAuthoritative network manifest (chain id, RPC URL, assets, contracts, policies).
GET/api/v1/statusOperational 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}/transactionsTransactions 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}/transactionsTop-level transactions for an address.
GET/api/v1/addresses/{address}/token-balancesSupported token balances at an observed block.
GET/api/v1/addresses/{address}/token-transfersERC-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}/transfersToken transfer history.
GET/api/v1/search?q=Exact address / tx hash / block hash / decimal block number.
GET/api/v1/prices/eth-usdExternal 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/challengesShort-lived challenge bound to recipient + program.
POST/api/v1/initial-grants/ensureIdempotent ensure of THE single entitlement (Idempotency-Key header; 202).
GET/api/v1/faucet/policyBoth 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/challengesChallenge bound to recipient, asset, program, generation, client and server-selected amount.
POST/api/v1/faucet/claimsAccepts 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/configSwap contract, canonical EIP-712 domain/types, bounds, fee and freshness policy.
GET/api/v1/swap/liquidityObserved reserves (never a reservation).
POST/api/v1/swap/quotesSigned 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.jsonMachine-readable OpenAPI specification.
GET/health/live · /health/readyLiveness 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