# FastPath Bitcoin API Agent Instructions

## Purpose

Use FastPath when an agent needs Bitcoin data through Web3-style requests or wants to pay per call with x402 instead of managing API keys.

## Installation

No server installation is required to consume FastPath. For JavaScript agents, install an x402 client and a signer library:

```bash
npm i @x402/fetch @x402/evm viem
```

## Canonical URLs

- Base URL: `https://api.nativebtc.org`
- Human/docs page: `https://api.nativebtc.org/`
- x402 docs section: `https://api.nativebtc.org/#x402`
- OpenAPI spec: `https://api.nativebtc.org/openapi.json`
- OpenAPI alternate location: `https://api.nativebtc.org/.well-known/openapi.json`
- Live dashboard: `https://api.nativebtc.org/dashboard`
- LLM summary: `https://api.nativebtc.org/llms.txt`
- Glossary: `https://api.nativebtc.org/glossary.md`

## Configuration

Paid endpoints use x402. First request the endpoint normally. If the response is HTTP 402, parse the JSON body or `Payment-Required` header. The challenge includes `x402Version` and an `accepts` array. Pay with USDC on one accepted network, then retry the same request with the payment header produced by your x402 client.

Accepted networks are Base `eip155:8453`, Polygon `eip155:137`, Arbitrum `eip155:42161`, and World Chain `eip155:480`.

Set `EVM_PRIVATE_KEY` in the calling bot's environment. The key must control USDC on at least one accepted network. FastPath does not receive this key.

```bash
export EVM_PRIVATE_KEY=0x...
```

## Usage

Preferred bot entry points:

- `POST /v1/rpc` for Ethereum JSON-RPC compatible callers.
- `POST /v1/bitcoin/insight` for one-call tx analysis.
- `POST /v1/template/check` for Core v31 optimizer cache checks.
- `POST /v1/template/fee-ladder` for fee bands.
- `POST /v1/template/bump-plan` for non-custodial RBF/CPFP planning.
- `GET /v1/mempool/stream-ticket` for a paid WebSocket ticket.

## Examples

JSON-RPC fee ladder request body:

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

Bitcoin insight request body:

```json
{
  "txid": "81c97a6c5b98a1019095de132727cda868694fb5d92534ebb07e475619e38325",
  "targetBlocks": 6,
  "action": "analyze"
}
```

## Non-Custodial Rule

FastPath never signs transactions, holds private keys, or custodies funds. If an endpoint returns a bump plan, the caller must sign any replacement transaction with its own wallet before broadcast.

## Response Expectations

All paid API responses are JSON. Bitcoin amounts are usually returned in satoshis or sat/vB unless explicitly labeled otherwise. Template signals are best interpreted as live cached intelligence from the latest optimizer cycle, not a guarantee of mining by any external miner.

## Crawl Guidance

Agents may crawl `https://api.nativebtc.org/`, `https://api.nativebtc.org/openapi.json`, `https://api.nativebtc.org/.well-known/openapi.json`, `https://api.nativebtc.org/llms.txt`, `https://api.nativebtc.org/llms-full.txt`, `https://api.nativebtc.org/AGENTS.md`, `https://api.nativebtc.org/sitemap.xml`, `https://api.nativebtc.org/sitemap.md`, and `https://api.nativebtc.org/glossary.md`. Avoid repeated unpaid polling of paid endpoints; use x402 for production calls.