{
  "openapi": "3.0.3",
  "info": {
    "title": "FastPath Bitcoin API",
    "version": "1.0.0",
    "description": "Bitcoin RPC for EVM bots. FastPath provides Ethereum-style JSON-RPC translation, live Bitcoin fee ladders, mempool intelligence, Core v31 optimizer cache checks, and non-custodial RBF or CPFP bump planning through x402-paid endpoints.",
    "termsOfService": "https://api.nativebtc.org/",
    "contact": {
      "name": "FastPath",
      "url": "https://api.nativebtc.org/",
      "email": "emiliano.arlington@gmail.com"
    }
  },
  "servers": [
    {
      "url": "https://api.nativebtc.org"
    }
  ],
  "tags": [
    { "name": "Bitcoin Reads", "description": "Basic Bitcoin block, fee, address, UTXO, and transaction data." },
    { "name": "JSON-RPC", "description": "Ethereum-style JSON-RPC translated into Bitcoin-backed answers." },
    { "name": "Mempool Intelligence", "description": "Live mempool fees, congestion, RBF, and transaction state." },
    { "name": "Template Intelligence", "description": "Core v31 optimizer cache checks, fee ladders, and bump plans." },
    { "name": "Discovery", "description": "Public capability and health endpoints." }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Service health",
        "operationId": "getHealth",
        "security": [],
        "responses": {
          "200": {
            "description": "Service health response.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GenericJson" }
              }
            }
          }
        }
      }
    },
    "/v1/template/capabilities": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Template intelligence capabilities",
        "operationId": "getTemplateCapabilities",
        "security": [],
        "responses": {
          "200": {
            "description": "Public capability report for optimizer cache and template intelligence.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GenericJson" }
              }
            }
          }
        }
      }
    },
    "/v1/rpc": {
      "post": {
        "tags": ["JSON-RPC"],
        "summary": "Ethereum-style JSON-RPC translated into Bitcoin data",
        "operationId": "postBitcoinJsonRpc",
        "description": "Use familiar Web3 JSON-RPC methods such as eth_blockNumber, eth_gasPrice, eth_getBalance, eth_getTransactionByHash, plus FastPath methods such as fastpath_feeLadder and fastpath_bitcoinInsight.",
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.001" }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/JsonRpcRequest" },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "fastpath_feeLadder",
                "params": [{ "targetBlocks": 6 }]
              }
            }
          }
        },
        "responses": {
          "200": { "$ref": "#/components/responses/JsonSuccess" },
          "402": { "$ref": "#/components/responses/X402PaymentRequired" }
        }
      }
    },
    "/v1/block-height": {
      "get": {
        "tags": ["Bitcoin Reads"],
        "summary": "Get current Bitcoin block height",
        "operationId": "getBlockHeight",
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.001" }
        },
        "responses": {
          "200": {
            "description": "Current Bitcoin block height.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BlockHeightResponse" },
                "example": { "success": true, "height": 957400, "hex": "0xe9bb8" }
              }
            }
          },
          "402": { "$ref": "#/components/responses/X402PaymentRequired" }
        }
      }
    },
    "/v1/fee-estimate": {
      "get": {
        "tags": ["Bitcoin Reads"],
        "summary": "Estimate Bitcoin fee rate",
        "operationId": "getFeeEstimate",
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.001" }
        },
        "parameters": [
          {
            "name": "blocks",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "default": 6 },
            "description": "Target confirmation window in blocks."
          }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/JsonSuccess" },
          "402": { "$ref": "#/components/responses/X402PaymentRequired" }
        }
      }
    },
    "/v1/balance/{address}": {
      "get": {
        "tags": ["Bitcoin Reads"],
        "summary": "Get Bitcoin address balance",
        "operationId": "getBitcoinBalance",
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.001" }
        },
        "parameters": [{ "$ref": "#/components/parameters/BitcoinAddress" }],
        "responses": {
          "200": { "$ref": "#/components/responses/JsonSuccess" },
          "402": { "$ref": "#/components/responses/X402PaymentRequired" }
        }
      }
    },
    "/v1/utxos/{address}": {
      "get": {
        "tags": ["Bitcoin Reads"],
        "summary": "Get Bitcoin UTXOs for address",
        "operationId": "getBitcoinUtxos",
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.002" }
        },
        "parameters": [{ "$ref": "#/components/parameters/BitcoinAddress" }],
        "responses": {
          "200": { "$ref": "#/components/responses/JsonSuccess" },
          "402": { "$ref": "#/components/responses/X402PaymentRequired" }
        }
      }
    },
    "/v1/tx/{txid}": {
      "get": {
        "tags": ["Bitcoin Reads"],
        "summary": "Get decoded Bitcoin transaction",
        "operationId": "getBitcoinTransaction",
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.001" }
        },
        "parameters": [{ "$ref": "#/components/parameters/Txid" }],
        "responses": {
          "200": { "$ref": "#/components/responses/JsonSuccess" },
          "402": { "$ref": "#/components/responses/X402PaymentRequired" }
        }
      }
    },
    "/v1/mempool/stats": {
      "get": {
        "tags": ["Mempool Intelligence"],
        "summary": "Get mempool statistics",
        "operationId": "getMempoolStats",
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.001" }
        },
        "responses": {
          "200": { "$ref": "#/components/responses/JsonSuccess" },
          "402": { "$ref": "#/components/responses/X402PaymentRequired" }
        }
      }
    },
    "/v1/mempool/fees": {
      "get": {
        "tags": ["Mempool Intelligence"],
        "summary": "Get fee histogram and target recommendation",
        "operationId": "getMempoolFees",
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.001" }
        },
        "parameters": [
          {
            "name": "target",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "default": 10 },
            "description": "Target confirmation window in blocks."
          }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/JsonSuccess" },
          "402": { "$ref": "#/components/responses/X402PaymentRequired" }
        }
      }
    },
    "/v1/mempool/tx/{txid}": {
      "get": {
        "tags": ["Mempool Intelligence"],
        "summary": "Get detailed mempool entry",
        "operationId": "getMempoolTransaction",
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.001" }
        },
        "parameters": [{ "$ref": "#/components/parameters/Txid" }],
        "responses": {
          "200": { "$ref": "#/components/responses/JsonSuccess" },
          "402": { "$ref": "#/components/responses/X402PaymentRequired" }
        }
      }
    },
    "/v1/mempool/tx/{txid}/replacements": {
      "get": {
        "tags": ["Mempool Intelligence"],
        "summary": "Track RBF replacements",
        "operationId": "getMempoolTransactionReplacements",
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.001" }
        },
        "parameters": [{ "$ref": "#/components/parameters/Txid" }],
        "responses": {
          "200": { "$ref": "#/components/responses/JsonSuccess" },
          "402": { "$ref": "#/components/responses/X402PaymentRequired" }
        }
      }
    },
    "/v1/mempool/stream-ticket": {
      "get": {
        "tags": ["Mempool Intelligence"],
        "summary": "Buy short-lived mempool stream ticket",
        "operationId": "getMempoolStreamTicket",
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.005" }
        },
        "responses": {
          "200": { "$ref": "#/components/responses/JsonSuccess" },
          "402": { "$ref": "#/components/responses/X402PaymentRequired" }
        }
      }
    },
    "/v1/template/check": {
      "post": {
        "tags": ["Template Intelligence"],
        "summary": "Check a txid against the live cached optimizer template signal",
        "operationId": "postTemplateCheck",
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TxidRequest" },
              "example": {
                "txid": "81c97a6c5b98a1019095de132727cda868694fb5d92534ebb07e475619e38325",
                "targetBlocks": 6
              }
            }
          }
        },
        "responses": {
          "200": { "$ref": "#/components/responses/JsonSuccess" },
          "402": { "$ref": "#/components/responses/X402PaymentRequired" }
        }
      }
    },
    "/v1/template/batch-check": {
      "post": {
        "tags": ["Template Intelligence"],
        "summary": "Check up to 10 txids against optimizer template signals",
        "operationId": "postTemplateBatchCheck",
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.05" }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/BatchTxidRequest" }
            }
          }
        },
        "responses": {
          "200": { "$ref": "#/components/responses/JsonSuccess" },
          "402": { "$ref": "#/components/responses/X402PaymentRequired" }
        }
      }
    },
    "/v1/template/fee-ladder": {
      "post": {
        "tags": ["Template Intelligence"],
        "summary": "Get urgent, normal, and cheap fee bands",
        "operationId": "postTemplateFeeLadder",
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TargetBlocksRequest" },
              "example": { "targetBlocks": 6 }
            }
          }
        },
        "responses": {
          "200": { "$ref": "#/components/responses/JsonSuccess" },
          "402": { "$ref": "#/components/responses/X402PaymentRequired" }
        }
      }
    },
    "/v1/template/bump-plan": {
      "post": {
        "tags": ["Template Intelligence"],
        "summary": "Get non-custodial RBF or CPFP bump plan",
        "operationId": "postTemplateBumpPlan",
        "description": "FastPath plans and can relay user-signed replacements only. It never signs transactions or holds funds.",
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TxidRequest" },
              "example": {
                "txid": "81c97a6c5b98a1019095de132727cda868694fb5d92534ebb07e475619e38325",
                "targetBlocks": 1
              }
            }
          }
        },
        "responses": {
          "200": { "$ref": "#/components/responses/JsonSuccess" },
          "402": { "$ref": "#/components/responses/X402PaymentRequired" }
        }
      }
    },
    "/v1/bitcoin/insight": {
      "post": {
        "tags": ["Template Intelligence", "Mempool Intelligence"],
        "summary": "Unified Bitcoin transaction analysis",
        "operationId": "postBitcoinInsight",
        "description": "Returns fee verdict, mempool state, RBF/CPFP bump plan, and Core v31 optimizer cache context for a Bitcoin transaction.",
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/BitcoinInsightRequest" },
              "example": {
                "txid": "81c97a6c5b98a1019095de132727cda868694fb5d92534ebb07e475619e38325",
                "targetBlocks": 6,
                "action": "analyze"
              }
            }
          }
        },
        "responses": {
          "200": { "$ref": "#/components/responses/JsonSuccess" },
          "402": { "$ref": "#/components/responses/X402PaymentRequired" }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "BitcoinAddress": {
        "name": "address",
        "in": "path",
        "required": true,
        "schema": { "type": "string" },
        "description": "Bitcoin address such as bc1q..., bc1p..., 1..., or 3...."
      },
      "Txid": {
        "name": "txid",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{64}$"
        },
        "description": "Bitcoin transaction ID."
      }
    },
    "schemas": {
      "GenericJson": {
        "type": "object",
        "additionalProperties": true
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": { "type": "string", "example": "2.0" },
          "id": { "description": "Client-selected JSON-RPC request id.", "nullable": true },
          "method": { "type": "string", "example": "fastpath_feeLadder" },
          "params": { "type": "array", "items": {}, "default": [] }
        }
      },
      "BlockHeightResponse": {
        "type": "object",
        "required": ["success", "height"],
        "properties": {
          "success": { "type": "boolean" },
          "height": { "type": "integer" },
          "hex": { "type": "string" }
        }
      },
      "TargetBlocksRequest": {
        "type": "object",
        "properties": {
          "targetBlocks": { "type": "integer", "minimum": 1, "default": 6 }
        }
      },
      "TxidRequest": {
        "allOf": [
          { "$ref": "#/components/schemas/TargetBlocksRequest" },
          {
            "type": "object",
            "required": ["txid"],
            "properties": {
              "txid": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" }
            }
          }
        ]
      },
      "BatchTxidRequest": {
        "allOf": [
          { "$ref": "#/components/schemas/TargetBlocksRequest" },
          {
            "type": "object",
            "required": ["txids"],
            "properties": {
              "txids": {
                "type": "array",
                "minItems": 1,
                "maxItems": 10,
                "items": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" }
              }
            }
          }
        ]
      },
      "BitcoinInsightRequest": {
        "allOf": [
          { "$ref": "#/components/schemas/TxidRequest" },
          {
            "type": "object",
            "properties": {
              "address": { "type": "string" },
              "action": {
                "type": "string",
                "enum": ["analyze", "broadcast_signed_replacement"],
                "default": "analyze"
              },
              "signedReplacementHex": {
                "type": "string",
                "description": "User-signed raw Bitcoin replacement transaction hex. FastPath relays only."
              }
            }
          }
        ]
      },
      "X402PaymentChallenge": {
        "type": "object",
        "required": ["x402Version", "accepts"],
        "properties": {
          "x402Version": { "type": "integer", "example": 2 },
          "error": { "type": "string", "example": "Payment required" },
          "accepts": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["scheme", "network", "amount", "asset", "payTo"],
              "properties": {
                "scheme": { "type": "string", "example": "exact" },
                "network": { "type": "string", "example": "eip155:8453" },
                "amount": { "type": "string", "example": "1000" },
                "asset": { "type": "string", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
                "payTo": { "type": "string", "example": "0x0300E73759B357ceeE5A248d1801eCb8abf7A1d4" }
              }
            }
          }
        }
      }
    },
    "responses": {
      "JsonSuccess": {
        "description": "Successful JSON response.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/GenericJson" }
          }
        }
      },
      "X402PaymentRequired": {
        "description": "x402 Payment Required challenge. The same challenge is also sent in the Payment-Required response header.",
        "headers": {
          "Payment-Required": {
            "description": "Base64-encoded x402 payment challenge.",
            "schema": { "type": "string" }
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/X402PaymentChallenge" }
          }
        }
      }
    }
  }
}