# FastPath Bitcoin API - Full Agent Context

FastPath exposes Bitcoin data in the language that Web3 agents already understand. The core endpoint is `https://api.nativebtc.org/v1/rpc`, where clients can call familiar Ethereum JSON-RPC methods and receive Bitcoin-backed answers. The service also exposes paid REST endpoints for mempool intelligence, fee ladders, transaction screening, Core v31 optimizer cache checks, and non-custodial RBF/CPFP bump planning.

## Base URL

`https://api.nativebtc.org`

## Best First Request

Use `POST /v1/rpc` when the caller already has an ethers.js, viem, or web3.js stack. Use the REST endpoints when the caller wants one explicit Bitcoin insight.

Example JSON-RPC body:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "fastpath_feeLadder",
  "params": [{ "targetBlocks": 6 }]
}
```

## x402 Payment Behavior

Paid endpoints return HTTP 402 when no payment is attached. The response body and `Payment-Required` header contain an x402 challenge with `x402Version` and `accepts`. A bot should choose one accepted network, sign the USDC payment authorization, and repeat the same request with the x402 payment header generated by its client library.

Supported payment networks:

- Base: `eip155:8453`
- Polygon: `eip155:137`
- Arbitrum: `eip155:42161`
- World Chain: `eip155:480`

## Pricing

- `$0.001`: basic reads such as block height, fee estimate, balance, UTXOs, transaction lookup, and JSON-RPC translation.
- `$0.005`: short-lived mempool WebSocket stream ticket.
- `$0.01`: Bitcoin insight, template check, fee ladder, and bump plan.
- `$0.05`: batch template check up to 10 txids.

## Main Capabilities

- Translate `eth_blockNumber` to Bitcoin block height.
- Translate `eth_gasPrice` to Bitcoin fee rate context.
- Translate `eth_getBalance` to Bitcoin address balance in satoshis when the address is Bitcoin-compatible or mapped.
- Return decoded Bitcoin transactions from txids.
- Return UTXOs for spendability checks.
- Analyze mempool state, fee rate, RBF flag, age, ancestors, descendants, and confirmation target health.
- Compare transaction presence against the live cached Core v31 optimizer and baseline template sets when available.
- Produce RBF or CPFP bump plans without signing or custodying funds.
- Issue short-lived WebSocket tickets for live mempool telemetry.

## Safety Model

FastPath is read-mostly and non-custodial. It can relay a user-signed raw Bitcoin transaction, but it does not create signatures, hold private keys, custody funds, or spend coins for users. A bump plan is only a plan unless the caller supplies a valid signed replacement transaction.

## Recommended Agent Flow

1. Call the desired endpoint without payment.
2. Parse the HTTP 402 x402 challenge.
3. Select the cheapest supported network available to the bot.
4. Pay with USDC through an x402-compatible client.
5. Retry the exact same request.
6. Use the returned Bitcoin data directly in the bot's strategy, wallet UX, compliance check, or payment release decision.

## High-Value Endpoints

- `POST /v1/bitcoin/insight`: one-call transaction analysis for bots.
- `POST /v1/template/check`: check whether a txid appears in FastPath's optimized template cache.
- `POST /v1/template/fee-ladder`: get urgent, normal, and cheap sat/vB targets.
- `POST /v1/template/bump-plan`: get a non-custodial RBF/CPFP plan.
- `GET /v1/mempool/stats`: mempool size, congestion, and fee landscape.
- `GET /v1/mempool/stream-ticket`: obtain a paid stream ticket for real-time mempool data.

## Public Pages

- Developer docs: `https://api.nativebtc.org/`
- x402 section: `https://api.nativebtc.org/#x402`
- OpenAPI spec: `https://api.nativebtc.org/openapi.json`
- Dashboard: `https://api.nativebtc.org/dashboard`
- Capabilities: `https://api.nativebtc.org/v1/template/capabilities`
- Health: `https://api.nativebtc.org/health`