{
  "openapi": "3.1.0",
  "info": {
    "title": "ExtraSafe Explorer API",
    "version": "1.0.0",
    "description": "Public API of ExtraSafe Testnet, an operator-controlled educational EVM test network. vETH and vUSD are valueless test assets with no redemption rights. All quantities are exact integer strings. This is the ExtraSafe Explorer API, not an Etherscan-compatible API. Errors use {code,message,requestId,retryAfterSeconds?}; HTTP 429 responses carry Retry-After."
  },
  "servers": [
    { "url": "https://testnet-api.extrasafe.net", "description": "Production backend" },
    { "url": "http://127.0.0.1:4600", "description": "Local development" }
  ],
  "components": {
    "parameters": {
      "cursor": { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque pagination cursor from a previous response (stable ordering)." },
      "limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 100 } },
      "address": { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } },
      "txHash": { "name": "hash", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } },
      "idempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 200 }, "description": "Bound server-side to recipient, asset, program and generation. Replays return the existing resource; changed input conflicts (409)." }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["code", "message", "requestId"],
        "properties": {
          "code": { "type": "string", "enum": ["INVALID_ADDRESS", "WRONG_NETWORK", "INVALID_REQUEST", "CHALLENGE_FAILED", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "BALANCE_LIMIT_REACHED", "DISTRIBUTION_IN_PROGRESS", "IDEMPOTENCY_CONFLICT", "ACCOUNT_STATE_CONFLICT", "COOLDOWN_ACTIVE", "RATE_LIMITED", "PRICE_UNAVAILABLE", "PRICE_STALE", "FAUCET_DEPLETED", "NODE_UNAVAILABLE", "SERVICE_RESTORING", "INTERNAL"] },
          "message": { "type": "string" },
          "requestId": { "type": "string" },
          "retryAfterSeconds": { "type": "integer" }
        }
      },
      "IntegerString": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact integer base units as a decimal string (never floating point)." },
      "Challenge": { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid" }, "expiresInSeconds": { "type": "integer" } } },
      "PayoutLeg": { "type": "object", "properties": { "leg": { "type": "string", "enum": ["native", "token"] }, "amount": { "$ref": "#/components/schemas/IntegerString" }, "txHash": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["queued", "prepared", "submitted", "mined", "reverted", "orphaned", "rejected_before_broadcast", "needs_review"] } } },
      "InitialGrant": { "type": "object", "properties": { "address": { "type": "string" }, "generationId": { "type": "string" }, "status": { "type": "string", "enum": ["not_yet_requested", "accepted", "partial", "completed", "needs_review"] }, "amounts": { "type": "object" }, "legs": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutLeg" } }, "cooldownApplied": { "type": "boolean" }, "nextEligibleAt": { "type": ["string", "null"] } } },
      "Claim": { "type": "object", "properties": { "claimId": { "type": "string" }, "program": { "type": "string" }, "address": { "type": "string" }, "assetId": { "type": ["string", "null"] }, "amount": { "$ref": "#/components/schemas/IntegerString" }, "status": { "type": "string" }, "legs": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutLeg" } }, "statusUrl": { "type": "string" }, "serverTime": { "type": "string" }, "nextEligibleAt": { "type": ["string", "null"] } } },
      "Quote": {
        "type": "object",
        "description": "Canonical EIP-712 Quote message (domain: name 'ExtraSafe Testnet Swap', version '1', active chain id, swap contract). Timestamps are Unix seconds UTC as strings.",
        "properties": { "quoteId": { "type": "string" }, "generationHash": { "type": "string" }, "taker": { "type": "string" }, "direction": { "type": "integer", "enum": [0, 1] }, "amountIn": { "$ref": "#/components/schemas/IntegerString" }, "amountOut": { "$ref": "#/components/schemas/IntegerString" }, "priceE8": { "$ref": "#/components/schemas/IntegerString" }, "priceObservedAt": { "$ref": "#/components/schemas/IntegerString" }, "issuedAt": { "$ref": "#/components/schemas/IntegerString" }, "expiresAt": { "$ref": "#/components/schemas/IntegerString" }, "signerEpoch": { "$ref": "#/components/schemas/IntegerString" } }
      }
    },
    "responses": {
      "Error": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  },
  "paths": {
    "/api/v1/network": { "get": { "summary": "Authoritative public network manifest", "responses": { "200": { "description": "Manifest: chain name/id (decimal+hex), generation, RPC/explorer URLs, native currency, asset registry with initial issuance (labeled distinctly from current supply), contracts with code hashes ('Installed at genesis', null deployment tx), owner/faucet/quote-signer public addresses, grant/faucet policies, price rules, mining/history/reset policy, runtime versions." } } } },
    "/api/v1/status": { "get": { "summary": "Operational status", "responses": { "200": { "description": "Node/restore state, head, indexer heartbeat/lag, checkpoint age and degradation, faucet inventory status, price freshness, swap readiness. Liveness is not readiness." } } } },
    "/api/v1/blocks": { "get": { "summary": "Canonical blocks (newest first)", "parameters": [{ "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }], "responses": { "200": { "description": "Items + nextCursor + generation/recovery context." } } } },
    "/api/v1/blocks/{numberOrHash}": { "get": { "summary": "One block", "parameters": [{ "name": "numberOrHash", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Block detail (canonical/orphaned state included)." }, "404": { "$ref": "#/components/responses/Error" } } } },
    "/api/v1/blocks/{numberOrHash}/transactions": { "get": { "summary": "Transactions of a block", "parameters": [{ "name": "numberOrHash", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }], "responses": { "200": { "description": "Items." } } } },
    "/api/v1/transactions": { "get": { "summary": "Recent canonical transactions", "parameters": [{ "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }], "responses": { "200": { "description": "Items + context." } } } },
    "/api/v1/transactions/{hash}": { "get": { "summary": "Transaction detail", "description": "Status from receipt.status (null receipt = pending/unknown, never success). Actual fee = gasUsed * effectiveGasPrice. Token transfers decoded from SUCCESSFUL receipt logs; project SwapExecuted events decoded with provenance (not generic internal tracing). Contract creations show to=null and receipt.contractAddress.", "parameters": [{ "$ref": "#/components/parameters/txHash" }], "responses": { "200": { "description": "Detail." }, "404": { "$ref": "#/components/responses/Error" } } } },
    "/api/v1/addresses/{address}": { "get": { "summary": "Address detail", "description": "Live native balance/nonce/code at an identified observation block (never a sum of transfers), vUSD balance, code label (none / code-present / delegated-eoa), indexed activity.", "parameters": [{ "$ref": "#/components/parameters/address" }], "responses": { "200": { "description": "Detail." } } } },
    "/api/v1/addresses/{address}/transactions": { "get": { "summary": "Top-level transactions", "parameters": [{ "$ref": "#/components/parameters/address" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }], "responses": { "200": { "description": "Items (top-level only; internal native transfers are not generically traced)." } } } },
    "/api/v1/addresses/{address}/token-balances": { "get": { "summary": "Supported token balances", "parameters": [{ "$ref": "#/components/parameters/address" }], "responses": { "200": { "description": "Balances at one observed block." } } } },
    "/api/v1/addresses/{address}/token-transfers": { "get": { "summary": "Token transfers touching the address", "parameters": [{ "$ref": "#/components/parameters/address" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }], "responses": { "200": { "description": "Items with kind transfer|mint|burn." } } } },
    "/api/v1/tokens/{address}": { "get": { "summary": "Registered token detail", "parameters": [{ "$ref": "#/components/parameters/address" }], "responses": { "200": { "description": "Metadata, initial issuance vs current totalSupply(), mint/burn totals, observed holders (zero address excluded), genesis allocation records." }, "404": { "$ref": "#/components/responses/Error" } } } },
    "/api/v1/tokens/{address}/transfers": { "get": { "summary": "Token transfer history", "parameters": [{ "$ref": "#/components/parameters/address" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }], "responses": { "200": { "description": "Items." } } } },
    "/api/v1/search": { "get": { "summary": "Exact search", "parameters": [{ "name": "q", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 100 }, "description": "Exact address, transaction hash, block hash, or decimal block number." }], "responses": { "200": { "description": "{type: address|transaction|block|none, ...}" } } } },
    "/api/v1/prices/eth-usd": { "get": { "summary": "External ETH/USD reference price", "responses": { "200": { "description": "price (USD/ETH * 1e8 as string), scale, source, priceId, providerUpdatedAt, fetchedAt, ageSeconds, maxAgeSeconds, status fresh|stale. Labeled reference data for test-asset simulation only." }, "503": { "$ref": "#/components/responses/Error" } } } },
    "/api/v1/initial-grants/{address}": { "get": { "summary": "One-time initial grant record", "parameters": [{ "$ref": "#/components/parameters/address" }], "responses": { "200": { "description": "InitialGrant (explicit not_yet_requested when no entitlement exists).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialGrant" } } } } } } },
    "/api/v1/initial-grants/challenges": { "post": { "summary": "Issue an initial-grant challenge", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["recipient"], "properties": { "recipient": { "type": "string" }, "clientId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Challenge" } } } } } } },
    "/api/v1/initial-grants/ensure": { "post": { "summary": "Idempotently ensure THE single entitlement", "description": "Called from wallet create/open/unlock/select and enter-Testnet hooks. Creates or returns the one entitlement per chainId+generation+address+program; repeated lifecycle calls converge on that record. Exempt from the recurring threshold/cooldown; still subject to challenge/Turnstile, inventory and chain health.", "parameters": [{ "$ref": "#/components/parameters/idempotencyKey" }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["recipient", "challengeId"], "properties": { "recipient": { "type": "string" }, "clientId": { "type": "string" }, "challengeId": { "type": "string" }, "turnstileToken": { "type": "string" } } } } } }, "responses": { "202": { "description": "Current grant record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialGrant" } } } }, "400": { "$ref": "#/components/responses/Error" } } } },
    "/api/v1/faucet/policy": { "get": { "summary": "Recurring faucet policy", "responses": { "200": { "description": "Both choices with exact units (vUSD 5000000 units / vETH 50000000000000000 wei), defaultAssetId vUSD, cooldownSeconds 60, cooldownScope address-and-generation, combinedValueThreshold '1000.00', valuation unit, initial-grant relationship, price freshness rules, Turnstile requirements." } } } },
    "/api/v1/faucet/eligibility": { "get": { "summary": "Advisory eligibility", "parameters": [{ "name": "address", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "assetId", "in": "query", "schema": { "type": "string", "enum": ["vUSD", "vETH"] } }], "responses": { "200": { "description": "eligible flag + reasons, BOTH balances at one canonical block/hash, priceId/source/time, combined simulated value, serverTime, nextEligibleAt, unresolvedDistributionId." } } } },
    "/api/v1/faucet/challenges": { "post": { "summary": "Issue a faucet challenge", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["recipient", "assetId"], "properties": { "recipient": { "type": "string" }, "assetId": { "type": "string", "enum": ["vUSD", "vETH"] }, "clientId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Challenge bound to recipient, asset, program, generation, client and the SERVER-selected amount.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Challenge" } } } } } } },
    "/api/v1/faucet/claims": { "post": { "summary": "Submit one recurring claim", "description": "Clients never choose amounts, contracts, prices, thresholds or transaction data. One shared 60 s cooldown per recipient/generation across BOTH assets; refused at combined holdings >= 1000.00 simulated vUSD-equivalent (full-precision pre-claim rule).", "parameters": [{ "$ref": "#/components/parameters/idempotencyKey" }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["recipient", "assetId", "challengeId"], "properties": { "recipient": { "type": "string" }, "assetId": { "type": "string", "enum": ["vUSD", "vETH"] }, "clientId": { "type": "string" }, "challengeId": { "type": "string" }, "turnstileToken": { "type": "string" } } } } } }, "responses": { "202": { "description": "Accepted claim", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Claim" } } } }, "200": { "description": "Idempotent replay of an existing claim" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } },
    "/api/v1/faucet/claims/{id}": { "get": { "summary": "Claim status", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Actual transaction/receipt/checkpoint state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Claim" } } } }, "404": { "$ref": "#/components/responses/Error" } } } },
    "/api/v1/swap/config": { "get": { "summary": "Swap configuration", "responses": { "200": { "description": "Contract/token addresses, canonical EIP-712 domain and Quote type, directions, zero service fee policy, input bounds, freshness/deadline policy." } } } },
    "/api/v1/swap/liquidity": { "get": { "summary": "Observed reserves", "responses": { "200": { "description": "Native/token reserves with block context — never a promise of reserved liquidity." } } } },
    "/api/v1/swap/quotes": { "post": { "summary": "Signed exact-input quote", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["chainId", "taker", "direction", "amountIn"], "properties": { "chainId": { "type": "integer" }, "generationId": { "type": "string" }, "taker": { "type": "string" }, "direction": { "type": "string", "enum": ["NATIVE_TO_TOKEN", "TOKEN_TO_NATIVE"] }, "amountIn": { "$ref": "#/components/schemas/IntegerString" } } } } } }, "responses": { "200": { "description": "{quote: Quote, signature, minAmountOutDefault, price context, expiry}. A quote never proves execution; the user wallet submits the swap transaction via /rpc.", "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "$ref": "#/components/schemas/Quote" }, "signature": { "type": "string" }, "minAmountOutDefault": { "$ref": "#/components/schemas/IntegerString" } } } } } }, "503": { "$ref": "#/components/responses/Error" } } } },
    "/api/v1/swaps": { "get": { "summary": "Indexed swap history", "parameters": [{ "name": "address", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }], "responses": { "200": { "description": "Verified SwapExecuted events with canonical context." } } } },
    "/api/v1/swaps/{transactionHash}": { "get": { "summary": "One indexed swap", "parameters": [{ "name": "transactionHash", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Swap detail." }, "404": { "$ref": "#/components/responses/Error" } } } },
    "/rpc/{chainId}": { "post": { "summary": "Restricted wallet JSON-RPC", "description": "Standard read methods plus eth_sendRawTransaction only, validated per batch entry. anvil_*/evm_*/hardhat_*/personal_*/eth_sendTransaction/eth_sign are never available. Raw transactions must match the path chain id; unprotected legacy transactions are rejected.", "parameters": [{ "name": "chainId", "in": "path", "required": true, "schema": { "type": "integer" } }], "responses": { "200": { "description": "JSON-RPC response(s)." } } } },
    "/health/live": { "get": { "summary": "Liveness", "responses": { "200": { "description": "Process is up (NOT readiness)." } } } },
    "/health/ready": { "get": { "summary": "Readiness", "responses": { "200": { "description": "Chain operations available." }, "503": { "description": "Starting/restoring/maintenance/degraded." } } } }
  }
}
