{"info":{"description":"Free Bitcoin fee rates and illustrative cost comparisons, plus an optional x402 v2 timing heuristic. Inspect payment state before attempting a paid call. The free preview does not require a wallet. Timing targets and potential savings are not guarantees.","title":"BitcoinsAPI x402 Edge Lab","version":"pre-release"},"openapi":"3.1.0","servers":[{"url":"https://bitcoinsapi.com"}],"components":{"schemas":{"FeePreview":{"type":"object","properties":{"data":{"type":"object","properties":{"fee_rates_sat_vb":{"type":"object","properties":{"fastest":{"type":"number","minimum":0},"half_hour":{"type":"number","minimum":0},"hour":{"type":"number","minimum":0},"economy":{"type":"number","minimum":0},"minimum":{"type":"number","minimum":0}},"required":["fastest","half_hour","hour","economy","minimum"]},"mempool":{"type":"object","properties":{"vsize":{"type":"number","minimum":0},"transaction_count":{"type":"number","minimum":0},"projected_block_count":{"type":"number","minimum":0}},"required":["vsize","transaction_count","projected_block_count"]},"potential_savings":{"type":"object","properties":{"sat_vb":{"type":"number","minimum":0},"percent":{"type":"number","minimum":0},"at_140_vbytes_sat":{"type":"number","minimum":0}},"required":["sat_vb","percent","at_140_vbytes_sat"]},"paid_resource":{"type":"object","properties":{"method":{"const":"GET"},"path":{"const":"/api/v1/fees/now"},"price":{"const":"0.001 USDC"},"network":{"type":"string"}},"required":["method","path","price","network"]}},"required":["fee_rates_sat_vb","mempool","potential_savings","paid_resource"]},"meta":{"type":"object","properties":{"snapshot_schema":{"const":"mempool-space-v1"},"snapshot_digest":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"source":{"const":"https://mempool.space"},"fetched_at":{"type":"string","format":"date-time"},"age_seconds":{"type":"number","minimum":0},"stale":{"type":"boolean"},"algorithm_version":{"const":"send-wait-v1"}},"required":["snapshot_schema","snapshot_digest","source","fetched_at","age_seconds","stale","algorithm_version"]}},"required":["data","meta"]},"FeeDecision":{"type":"object","properties":{"data":{"type":"object","properties":{"fee_rates_sat_vb":{"type":"object","properties":{"fastest":{"type":"number","minimum":0},"half_hour":{"type":"number","minimum":0},"hour":{"type":"number","minimum":0},"economy":{"type":"number","minimum":0},"minimum":{"type":"number","minimum":0}},"required":["fastest","half_hour","hour","economy","minimum"]},"mempool":{"type":"object","properties":{"vsize":{"type":"number","minimum":0},"transaction_count":{"type":"number","minimum":0},"projected_block_count":{"type":"number","minimum":0}},"required":["vsize","transaction_count","projected_block_count"]},"potential_savings":{"type":"object","properties":{"sat_vb":{"type":"number","minimum":0},"percent":{"type":"number","minimum":0},"at_140_vbytes_sat":{"type":"number","minimum":0}},"required":["sat_vb","percent","at_140_vbytes_sat"]},"decision":{"enum":["send","wait"]},"reason_codes":{"type":"array","minItems":1,"maxItems":2,"uniqueItems":true,"items":{"enum":["meaningful_fee_curve_savings","heavy_backlog","limited_wait_savings"]}}},"required":["fee_rates_sat_vb","mempool","potential_savings","decision","reason_codes"]},"meta":{"type":"object","properties":{"snapshot_schema":{"const":"mempool-space-v1"},"snapshot_digest":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"source":{"const":"https://mempool.space"},"fetched_at":{"type":"string","format":"date-time"},"age_seconds":{"type":"number","minimum":0},"stale":{"type":"boolean"},"algorithm_version":{"const":"send-wait-v1"},"schema_version":{"const":"2026-08-06"},"evidence":{"enum":["recorded","degraded"]},"payment":{"type":"object","properties":{"amount":{"const":"0.001"},"currency":{"const":"USDC"},"facilitator":{"const":"xpay"},"network":{"type":"string"},"transaction_hash":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}},"required":["amount","currency","facilitator","network","transaction_hash"]}},"required":["snapshot_schema","snapshot_digest","source","fetched_at","age_seconds","stale","algorithm_version","schema_version","evidence","payment"]},"limitations":{"type":"array","items":{"type":"string"}}},"required":["data","meta","limitations"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"retryable":{"type":"boolean"},"retry":{"type":"object","properties":{"instruction":{"const":"retry_exact_payment_payload"}},"required":["instruction"]}},"required":["code","message","request_id","retryable"]}},"required":["error"]},"PaymentRequired":{"type":"object","properties":{"x402Version":{"const":2},"resource":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"}},"required":["url"]},"accepts":{"type":"array","minItems":1,"items":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"asset":{"type":"string"},"amount":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer","minimum":1}},"required":["scheme","network","asset","amount","payTo","maxTimeoutSeconds"]}}},"required":["x402Version","resource","accepts"]}}},"paths":{"/api/v1/fees/now":{"get":{"description":"Returns a deterministic send-or-wait decision after confirmed settlement. Exact canonical HTTPS URL only; no query parameters. When paused, returns 503 with no payment challenge. On an uncertain settlement, follow the exact-payload retry instruction; do not automatically sign a second payment.","operationId":"getFeeTimingDecision","responses":{"200":{"description":"Confirmed paid decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeeDecision"}}},"headers":{"PAYMENT-RESPONSE":{"description":"Base64-encoded x402 settlement receipt","schema":{"type":"string"}}}},"400":{"description":"Invalid canonical request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"x402 v2 payment required or rejected; inspect PAYMENT-REQUIRED when present","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 v2 payment requirements","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PaymentRequired"},{"$ref":"#/components/schemas/Error"}]}}}},"429":{"description":"Edge rate limit reached; back off before retrying"},"502":{"description":"Settlement outcome uncertain; retry only the exact payment payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Resource paused or dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Get a Bitcoin fee timing decision","x-bitcoinsapi-x402":{"amount_atomic":"1000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","compatibility_checked_at":"2026-09-08T16:05:04.856Z","currency":"USDC","facilitator":"xpay","max_timeout_seconds":60,"method":"GET","mime_type":"application/json","network":"eip155:8453","path":"/api/v1/fees/now","price":"0.001","recipient":"0x8454A49215A78040c69525D57D05fb5d9B21F663","resource":"https://bitcoinsapi.com/api/v1/fees/now","scheme":"exact","state":"paused","x402_version":2}}},"/api/v1/fees/preview":{"get":{"description":"Free validated fee snapshot. Multiply a rate in sat/vB by your transaction's virtual size and round up for an illustrative fee in sats. Check fetched_at and stale before use. Fresh cache: up to 30 seconds; fallback: up to 120 seconds at origin, plus HTTP cache time. No authentication or payment is required.","operationId":"getFeePreview","responses":{"200":{"description":"Free preview","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeePreview"}}}},"503":{"description":"No validated snapshot available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Preview current fee conditions"}}}}