# SatoshiData.ai Full Agent Guide
> Bitcoin chain intelligence API for agents. Use this file when you need the full machine-readable operating guide. The short guide lives at https://satoshidata.ai/llms.txt and the canonical API schema lives at https://satoshidata.ai/openapi.json.

## Service
- Name: SatoshiData.ai
- Base URL: https://satoshidata.ai
- Purpose: Bitcoin wallet trust and safety, entity labels, on-chain analytics, mempool and fee context, transaction lookup, timestamping, and payment-aware premium intelligence.
- Response format: JSON for API endpoints; markdown for this file.
- Evidence model: public labels may be inferred, high-confidence, or verified. Do not present inferred labels as verified identities.
- Preferred citation: SatoshiData.ai (satoshidata.ai)

## Discovery
- Short agent guide: https://satoshidata.ai/llms.txt
- Full agent guide: https://satoshidata.ai/llms-full.txt
- OpenAPI: https://satoshidata.ai/openapi.json
- Agent card: https://satoshidata.ai/.well-known/agent-card.json
- Agents.json: https://satoshidata.ai/agents.json
- Agents.json well-known alias: https://satoshidata.ai/.well-known/agents.json
- MCP descriptor: https://satoshidata.ai/.well-known/mcp.json
- MCP endpoint: https://satoshidata.ai/mcp/
- Capabilities: https://satoshidata.ai/v1/capabilities
- Health: https://satoshidata.ai/api/health

## Authentication And Payment
- Free endpoints need no auth. Normal rate limits still apply.
- API key: send `X-WR-API-Key: <key>` for prepaid/monthly access.
- L402: Lightning pay-per-call. A paid endpoint may return HTTP 402 with a Lightning invoice; pay it, then replay with the returned L402 proof in `Authorization`.
- x402: USDC on Base inline payment. Supported endpoints accept an `X-PAYMENT` header after the client follows the HTTP 402 payment challenge.
- Typical paid tiers: micro endpoints around 5 sats; standard endpoints around 21 sats or $0.01 via x402 USDC; pro/premium endpoints cost more. Check `/v1/capabilities` and billing responses for current prices.

## Safe Agent Behavior
- Prefer free teaser endpoints before paid endpoints.
- When a response includes caveats, show them to the user.
- For wallet labels, distinguish `inferred`, `high_confidence`, and `verified`.
- Never broadcast a transaction unless the user explicitly supplied a signed raw transaction and asked you to broadcast it.
- If a paid endpoint returns HTTP 402, explain the payment method and ask the user before spending.
- If an endpoint is missing, trust HTTP status over SPA content. Agent surfaces are JSON or markdown, not HTML.

## Endpoint Examples

### Wallet Trust And Safety
Use this first for any Bitcoin address.

Request:
```http
GET /v1/wallets/{address}/trust-safety
```

Example response shape:
```json
{
  "address": "bc1qexample...",
  "score": 72,
  "tier": "inferred",
  "category": "exchange_customer",
  "risk_flags": [],
  "caveats": ["Label evidence is inferred, not verified."]
}
```

### Wallet Summary
Use this when the user wants richer paid wallet intelligence.

Request:
```http
GET /v1/wallets/{address}/summary
X-WR-API-Key: <key>
```

Example response shape:
```json
{
  "address": "bc1qexample...",
  "trust_score": 72,
  "labels": [],
  "activity": {},
  "payment": "api-key-or-402"
}
```

### Wallet Detail
Use this when the user needs label evidence and grouped metadata.

Request:
```http
GET /v1/wallets/{address}/detail
```

Example response shape:
```json
{
  "address": "bc1qexample...",
  "entity": null,
  "evidence_tier": "inferred",
  "label_groups": []
}
```

### Batch Trust Safety
Use this when you have multiple addresses to triage.

Request:
```http
POST /v1/batch/trust-safety
Content-Type: application/json

{"addresses":["bc1qexample1...","bc1qexample2..."]}
```

Example response shape:
```json
{
  "results": [
    {"address": "bc1qexample1...", "score": 72, "tier": "inferred"}
  ]
}
```

### Network Summary
Use this for Bitcoin market and chain context.

Request:
```http
GET /v1/network/summary
```

Example response shape:
```json
{
  "price": {},
  "fees": {},
  "mempool": {},
  "chain": {}
}
```

### Price
Use this for a current BTC price snapshot.

Request:
```http
GET /v1/price
```

Example response shape:
```json
{
  "btc_usd": 0,
  "source": "market-cache",
  "updated_at": "2026-04-30T00:00:00Z"
}
```

### Recommended Fees
Use this before advising on Bitcoin transaction timing.

Request:
```http
GET /v1/fees/recommended
```

Example response shape:
```json
{
  "fastest_fee": 0,
  "half_hour_fee": 0,
  "hour_fee": 0
}
```

### Mempool Stats
Use this for congestion context.

Request:
```http
GET /v1/mempool/stats
```

Example response shape:
```json
{
  "count": 0,
  "vsize": 0,
  "total_fee_btc": 0
}
```

### Mempool Transaction
Use this to inspect an unconfirmed transaction.

Request:
```http
GET /v1/mempool/tx/{txid}
```

Example response shape:
```json
{
  "txid": "example",
  "seen": true,
  "fee_rate_sat_vb": 0
}
```

### Transaction Status
Use this to check confirmation state.

Request:
```http
GET /v1/tx/{txid}/status
```

Example response shape:
```json
{
  "txid": "example",
  "status": "confirmed",
  "confirmations": 6
}
```

### Transaction Broadcast
Only use this with a signed raw transaction supplied by the user.

Request:
```http
POST /v1/tx/broadcast
Content-Type: application/json

{"raw_tx":"0200000001..."}
```

Example response shape:
```json
{
  "accepted": true,
  "txid": "example"
}
```

### Transaction Payment Verification
Use this to verify a specific Bitcoin payment.

Request:
```http
POST /v1/tx/verify
Content-Type: application/json

{"txid":"example","address":"bc1qexample...","amount_btc":0.001}
```

Example response shape:
```json
{
  "verified": true,
  "confirmations": 6
}
```

### OP_RETURN Decode
Use this to inspect protocol markers.

Request:
```http
GET /v1/tx/{txid}/op-return
```

Example response shape:
```json
{
  "txid": "example",
  "op_returns": []
}
```

### Exchange Flow Summary
Use this for aggregate exchange inflow/outflow context.

Request:
```http
GET /v1/exchange/flows/summary
```

Example response shape:
```json
{
  "window": "24h",
  "inflow_btc": 0,
  "outflow_btc": 0
}
```

### Exchange Flows
Use this for paid per-entity exchange flow history.

Request:
```http
GET /v1/exchange/flows
```

Example response shape:
```json
{
  "entities": [],
  "window": "24h"
}
```

### Miner Flows
Use this for mining-pool mined BTC, exchange flow, and held-vs-unknown routing.

Request:
```http
GET /v1/miner/flows
```

Example response shape:
```json
{
  "pools": [],
  "window": "24h"
}
```

### Whale Alerts
Use this for recent large Bitcoin transfers.

Request:
```http
GET /v1/chain/whale-alerts
```

Example response shape:
```json
{
  "alerts": []
}
```

### Labeled Whale Alerts
Use this when entity enrichment is worth a paid call.

Request:
```http
GET /v1/chain/whale-alerts/labeled
```

Example response shape:
```json
{
  "alerts": [],
  "label_evidence": "mixed"
}
```

### Dormant Movements
Use this for recent old-coin spends.

Request:
```http
GET /v1/chain/dormant-movements
```

Example response shape:
```json
{
  "movements": []
}
```

### Dormant Alerts
Use this for entity-enriched dormant coin movements.

Request:
```http
GET /v1/chain/dormant-alerts
```

Example response shape:
```json
{
  "alerts": []
}
```

### Activity Feed
Use this for a combined whale and dormant activity feed.

Request:
```http
GET /v1/chain/activity-feed
```

Example response shape:
```json
{
  "items": []
}
```

### Flow Graph
Use this to build a bounded transaction-flow graph around an address.

Request:
```http
GET /v1/wallets/{address}/flow-graph
```

Example response shape:
```json
{
  "nodes": [],
  "edges": []
}
```

### Surveillance Status
Use this for observed dust-ping surveillance campaigns.

Request:
```http
GET /v1/wallets/{address}/surveillance-status
```

Example response shape:
```json
{
  "address": "bc1qexample...",
  "observed": false,
  "campaigns": []
}
```

### Timestamp Quote
Use this before anchoring a hash.

Request:
```http
GET /v1/timestamp/quote
```

Example response shape:
```json
{
  "price_sats": 21,
  "method": "L402"
}
```

### Timestamp Submit
Use this to anchor a SHA-256 hash after the user approves payment.

Request:
```http
POST /v1/timestamp
Content-Type: application/json

{"hash":"0000000000000000000000000000000000000000000000000000000000000000"}
```

Example response shape:
```json
{
  "hash": "0000000000000000000000000000000000000000000000000000000000000000",
  "status": "pending",
  "proof_url": null
}
```

### Timestamp Status
Use this to check a submitted hash.

Request:
```http
GET /v1/timestamp/{hash}
```

Example response shape:
```json
{
  "hash": "0000...",
  "status": "anchored"
}
```

### Timestamp Verify
Use this to verify an OpenTimestamps proof.

Request:
```http
POST /v1/timestamp/verify
```

Example response shape:
```json
{
  "verified": true
}
```

### Feedback
Use this to submit machine-readable corrections or endpoint feedback.

Request:
```http
POST /v1/feedback
Content-Type: application/json

{"kind":"label_correction","address":"bc1qexample...","message":"Correction details"}
```

Example response shape:
```json
{
  "ok": true
}
```

## Browser Surfaces
- Flow graph explorer: https://satoshidata.ai/graph/
- Dormancy Watch: https://satoshidata.ai/dormancy/
- Surveillance Watchlist: https://satoshidata.ai/surveillance/

## Unsupported Agent Surfaces
- `/.well-known/ai-plugin.json`: not supported. OpenAI plugins are not the integration path for this API.
- `/ai.txt`: not supported as a separate policy file. Use `robots.txt`, `llms.txt`, `llms-full.txt`, `agents.json`, OpenAPI, and MCP descriptors instead.