{ "openapi": "3.1.0", "info": { "title": "OBOL \u2014 Bitcoin agent data marketplace (x402)", "version": "2.0.0", "description": "Auction-house density: many real pay-per-call Bitcoin fee/mempool/anomaly + multi-asset spot SKUs on Base USDC x402. Free: /catalog, /pulse/preview, /llms.txt. Agents: browse /catalog then pay any path.", "x-guidance": "1) GET /catalog (free) for full SKU list. 2) GET /pulse/preview (free) for next-block fee taste. 3) Pay GET /pulse, /prices, /v1/* , or /signal/{height}. x402 exact USDC on Base; $0.002 default (bundle $0.006)." }, "servers": [ { "url": "https://obol-x402.fly.dev" } ], "paths": { "/signal/{height}": { "get": { "operationId": "getBlockSignal", "summary": "Validated Bitcoin anomaly signals for one block height", "description": "Returns armed Curiosity Engine detector findings for one Bitcoin block. Payment: exact scheme x402 USDC on Base.", "tags": [ "Bitcoin", "x402", "on-chain-data" ], "parameters": [ { "name": "height", "in": "path", "required": true, "description": "Bitcoin block height (e.g. 840000)", "schema": { "type": "integer", "minimum": 0, "example": 840000 } } ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Validated anomaly signals for the block", "content": { "application/json": { "schema": { "type": "object", "properties": { "height": { "type": "integer" }, "available": { "type": "boolean" }, "signals": { "type": "array", "items": { "type": "object" } }, "signal_count": { "type": "integer" } } } } } }, "402": { "description": "Payment Required (x402 v2 PAYMENT-REQUIRED header)" } } } }, "/pulse": { "get": { "operationId": "getBitcoinPulse", "summary": "Live Bitcoin market + mempool + fee pulse (no params)", "description": "One call returns the current Bitcoin picture a trading/timing agent needs each cycle: spot USD price, mempool backlog, next-block & tiered fee rates (sat/vB), tip height, plus derived congestion and fee-spike flags. No path param \u2014 session-repeat friendly. Payment: exact scheme x402 USDC on Base.", "tags": [ "Bitcoin", "x402", "market-data", "mempool", "fees" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Live Bitcoin pulse", "content": { "application/json": { "schema": { "type": "object", "properties": { "as_of": { "type": "integer" }, "price_usd": { "type": "number" }, "tip_height": { "type": "integer" }, "mempool": { "type": "object" }, "fees_sat_vb": { "type": "object" }, "flags": { "type": "object" } } } } } }, "402": { "description": "Payment Required (x402 v2 PAYMENT-REQUIRED header)" } } } }, "/prices": { "get": { "operationId": "getCryptoPrices", "summary": "Live multi-asset crypto spot prices (BTC/ETH/SOL/USDC/USDT)", "description": "Cross-checked USD spot prices from two independent sources (Coinbase + Kraken) with a per-asset divergence flag for stale/oracle-risk detection. No path param. Payment: exact scheme x402 USDC on Base.", "tags": [ "crypto", "x402", "market-data", "prices" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Live cross-checked spot prices", "content": { "application/json": { "schema": { "type": "object", "properties": { "as_of": { "type": "integer" }, "quote": { "type": "string" }, "prices": { "type": "object" }, "available": { "type": "boolean" } } } } } }, "402": { "description": "Payment Required (x402 v2 PAYMENT-REQUIRED header)" } } } }, "/catalog": { "get": { "operationId": "getCatalog", "summary": "Free: product, price, armed detectors", "security": [], "responses": { "200": { "description": "Catalog" } } } }, "/examples": { "get": { "operationId": "getExamples", "summary": "Free: known high-signal block heights", "security": [], "responses": { "200": { "description": "Example heights to pay-query" } } } }, "/health": { "get": { "operationId": "getHealth", "summary": "Free: liveness + rail/network", "security": [], "responses": { "200": { "description": "OK" } } } }, "/llms.txt": { "get": { "operationId": "getLlmsTxt", "summary": "Free: agent instructions", "security": [], "responses": { "200": { "description": "plain text" } } } }, "/pulse/preview": { "get": { "operationId": "getPulsePreview", "summary": "Free: next-block fee sat/vB + congestion teaser", "security": [], "responses": { "200": { "description": "Free fee teaser" } } } }, "/v1/btc/fee/next-block": { "get": { "operationId": "get_btc_fee_next_block_sat_vb", "summary": "btc-fee-next-block-sat-vb", "description": "Bitcoin next-block fee only in sat/vB \u2014 fastest single-number fee estimate for agents building BTC transactions. next-block fee estimate sat/vB.", "tags": [ "fee-estimate", "next-block", "sat-vb", "bitcoin", "BTC", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } }, "/v1/btc/fee/tiers": { "get": { "operationId": "get_btc_fee_tiers_sat_vb", "summary": "btc-fee-tiers-sat-vb", "description": "Bitcoin recommended fee rates sat/vB: next-block, 30-min, 1-hour, economy, minimum. Fee estimation tiers for AI agents and fee estimation UIs.", "tags": [ "fee-estimate", "sat-vb", "tiers", "bitcoin", "economy", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } }, "/v1/btc/mempool": { "get": { "operationId": "get_btc_mempool_backlog", "summary": "btc-mempool-backlog", "description": "Bitcoin mempool backlog stats: pending tx count, backlog vsize, estimated blocks. Mempool congestion telemetry for timing agents.", "tags": [ "mempool", "backlog", "bitcoin", "congestion", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } }, "/v1/btc/congestion": { "get": { "operationId": "get_btc_congestion_broadcast_advice", "summary": "btc-congestion-broadcast-advice", "description": "Bitcoin mempool congestion tier + fee-spike flag + broadcast advice (ok_to_broadcast / wait_or_pay_up). Should I broadcast BTC now?", "tags": [ "congestion", "broadcast", "fee-spike", "bitcoin", "mempool", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } }, "/v1/btc/tip": { "get": { "operationId": "get_btc_chain_tip_height", "summary": "btc-chain-tip-height", "description": "Current Bitcoin chain tip height (latest block number) for agents syncing height.", "tags": [ "tip", "height", "bitcoin", "block", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } }, "/v1/btc/spot": { "get": { "operationId": "get_btc_usd_spot_price", "summary": "btc-usd-spot-price", "description": "Bitcoin BTC USD spot price only \u2014 single-asset price for trading agents.", "tags": [ "BTC", "spot-price", "USD", "bitcoin", "price", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } }, "/v1/price/BTC": { "get": { "operationId": "get_spot_price_btc_usd", "summary": "spot-price-btc-usd", "description": "Bitcoin BTC USD spot price Coinbase Kraken cross-check with divergence flag. Single-asset BTC/USD for AI agents.", "tags": [ "spot-price", "BTC", "USD", "cross-exchange", "trading", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } }, "/v1/price/ETH": { "get": { "operationId": "get_spot_price_eth_usd", "summary": "spot-price-eth-usd", "description": "Ethereum ETH USD spot price Coinbase Kraken cross-check with divergence flag. Single-asset ETH/USD for AI agents.", "tags": [ "spot-price", "ETH", "USD", "cross-exchange", "trading", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } }, "/v1/price/SOL": { "get": { "operationId": "get_spot_price_sol_usd", "summary": "spot-price-sol-usd", "description": "Solana SOL USD spot price Coinbase Kraken cross-check with divergence flag. Single-asset SOL/USD for AI agents.", "tags": [ "spot-price", "SOL", "USD", "cross-exchange", "trading", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } }, "/v1/price/USDC": { "get": { "operationId": "get_spot_price_usdc_usd", "summary": "spot-price-usdc-usd", "description": "USDC USD spot price stablecoin quote Coinbase Kraken with divergence flag. Single-asset USDC/USD for AI agents.", "tags": [ "spot-price", "USDC", "USD", "cross-exchange", "trading", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } }, "/v1/price/USDT": { "get": { "operationId": "get_spot_price_usdt_usd", "summary": "spot-price-usdt-usd", "description": "USDT USD spot price stablecoin quote Coinbase Kraken with divergence flag. Single-asset USDT/USD for AI agents.", "tags": [ "spot-price", "USDT", "USD", "cross-exchange", "trading", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } }, "/v1/btc/anomaly/latest": { "get": { "operationId": "get_bitcoin_block_anomaly_latest", "summary": "bitcoin-block-anomaly-latest", "description": "Validation-gated Bitcoin block anomaly detector on the current tip height. fee-exceeds-subsidy, empty block, difficulty retarget, timestamp inversion, long block gap, coinbase message \u2014 latest block scan for agents.", "tags": [ "anomaly", "bitcoin", "detector", "latest", "tip", "on-chain", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } }, "/v1/btc/anomaly/fee-exceeds-subsidy/latest": { "get": { "operationId": "get_btc_anomaly_fee_exceeds_subsidy", "summary": "btc-anomaly-fee-exceeds-subsidy", "description": "Bitcoin fees exceed subsidy anomaly check on chain tip. Validation-gated detector fee_exceeds_subsidy for forensic and monitoring agents.", "tags": [ "anomaly", "bitcoin", "fee-exceeds-subsidy", "detector", "forensics", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } }, "/v1/btc/anomaly/empty-block/latest": { "get": { "operationId": "get_btc_anomaly_empty_block", "summary": "btc-anomaly-empty-block", "description": "Bitcoin empty bitcoin block anomaly check on chain tip. Validation-gated detector empty_block for forensic and monitoring agents.", "tags": [ "anomaly", "bitcoin", "empty-block", "detector", "forensics", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } }, "/v1/btc/anomaly/difficulty-retarget/latest": { "get": { "operationId": "get_btc_anomaly_difficulty_retarget", "summary": "btc-anomaly-difficulty-retarget", "description": "Bitcoin difficulty retarget anomaly check on chain tip. Validation-gated detector difficulty_retarget for forensic and monitoring agents.", "tags": [ "anomaly", "bitcoin", "difficulty-retarget", "detector", "forensics", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } }, "/v1/btc/anomaly/timestamp-inversion/latest": { "get": { "operationId": "get_btc_anomaly_timestamp_inversion", "summary": "btc-anomaly-timestamp-inversion", "description": "Bitcoin timestamp inversion anomaly check on chain tip. Validation-gated detector timestamp_inversion for forensic and monitoring agents.", "tags": [ "anomaly", "bitcoin", "timestamp-inversion", "detector", "forensics", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } }, "/v1/btc/anomaly/long-block-gap/latest": { "get": { "operationId": "get_btc_anomaly_long_block_gap", "summary": "btc-anomaly-long-block-gap", "description": "Bitcoin long block gap anomaly check on chain tip. Validation-gated detector long_block_gap for forensic and monitoring agents.", "tags": [ "anomaly", "bitcoin", "long-block-gap", "detector", "forensics", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } }, "/v1/btc/anomaly/coinbase-message/latest": { "get": { "operationId": "get_btc_anomaly_coinbase_message", "summary": "btc-anomaly-coinbase-message", "description": "Bitcoin coinbase message anomaly check on chain tip. Validation-gated detector coinbase_message for forensic and monitoring agents.", "tags": [ "anomaly", "bitcoin", "coinbase-message", "detector", "forensics", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } }, "/v1/btc/coinbase-messages": { "get": { "operationId": "get_btc_coinbase_message_archaeology", "summary": "btc-coinbase-message-archaeology", "description": "Bitcoin coinbase scriptSig cultural archaeology \u2014 Matrix campaign, Munger quote, carbon-negative miner statements and verified on-chain miner prose. Unique TIMECHAIN dig. Free teaser: GET /v1/btc/coinbase-messages/teaser.", "tags": [ "bitcoin", "coinbase", "archaeology", "miner-messages", "history", "forensics", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "2000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } }, "/v1/bundle/trader": { "get": { "operationId": "get_obol_trader_bundle", "summary": "obol-trader-bundle", "description": "Trader bundle: full Bitcoin pulse (fees mempool congestion) PLUS multi-asset USD spot prices BTC ETH SOL USDC USDT with divergence \u2014 one payment for research and timing agents.", "tags": [ "bundle", "trading", "pulse", "spot-price", "bitcoin", "portfolio", "x402", "obol" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.006000" }, "protocols": [ { "x402": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USD Coin", "amountAtomic": "6000", "payTo": "0x215f0C5e62735A54185f253B6245A630b744a7Ce", "scheme": "exact" } } ] }, "responses": { "200": { "description": "Paid JSON payload" }, "402": { "description": "Payment Required (x402 v2)" } } } } } }