# SatoshiData.ai
> Bitcoin chain-intelligence API for AI agents, developers, and applications.

## Current access state
- Product mode: public beta.
- Billing mode: beta_free.
- Auth mode: beta_public.
- During public beta, all documented API endpoints are callable without payment or API key.
- During beta, `X-WR-API-Key` is accepted as a forward-compatible no-op. It is shape-checked, acknowledged with `X-WR-API-Key-Mode: beta-noop`, and logged only as a non-secret hash; it does not gate access until post-beta premium enforcement.
- Native L402 live capabilities: none right now.
- x402 live capabilities: none right now.
- x402 prepared capabilities: wallet_summary, mempool_stress_history, chain_awakenings.

Always inspect the response `access` block and `_meta` block. They are the source of truth for current auth, freshness, pricing metadata, and docs URL.
Every `_meta` block includes `freshness_semantics`: `internal_refresh` means satoshidata.ai refreshed/generated an internal projection, `source_poll` means the timestamp reflects a source scan/poll/cache, and `claim_made` means the timestamp is tied to an observed label/report claim.
Every `_meta` block includes `warnings`; treat an empty list as the normal no-warning state. Non-empty warnings are non-fatal caveats such as known Bitcoin test/example addresses.
High-frequency GET endpoints may return `ETag` and `Cache-Control`; send `If-None-Match` on repeat polls and handle HTTP `304` as "unchanged".
If a response includes old compatibility fields, it will include `Deprecation: true` and `X-WR-Deprecated-Fields`. `Sunset` is intentionally absent until a post-beta removal date is chosen.

## Machine-readable specs
- Quickstart: https://satoshidata.ai/quickstart
- Changelog: https://satoshidata.ai/changelog
- Changelog RSS: https://satoshidata.ai/changelog.rss
- OpenAPI: https://satoshidata.ai/openapi.json
- Capabilities: https://satoshidata.ai/v1/capabilities
- Agent card: https://satoshidata.ai/.well-known/agent-card.json
- AI plugin manifest: https://satoshidata.ai/.well-known/ai-plugin.json
- MCP discovery: https://satoshidata.ai/.well-known/mcp.json
- MCP server: https://satoshidata.ai/mcp/

Authority: `/.well-known/agent-card.json` is the signed A2A card; its `x_satoshidata.legacy_capabilities` list mirrors the full public HTTP capability surface. `/.well-known/mcp.json` lists the MCP-exposed subset; `/v1/capabilities` is the live access, billing, beta, and x402 state; `/openapi.json` is the canonical request/response schema.

MCP batch tools use a single envelope: successful `batch_*` calls return batch items under `structuredContent.data.results[]`. Deprecated MCP aliases are not advertised after their stated expiry; use canonical snake_case tool names from `tools/list`.

## Reading wallet labels
`label.value` and `label.category` are asserted answers. They can be `null` even when satoshidata.ai has a useful lead.

When `label.value` is `null`, read these companion fields before deciding the wallet is unknown:
- `/v1/wallets/{address}/summary`: `likely_entity`, `likely_category`, and `short_explanation`.
- `/v1/wallets/{address}/trust-safety`: `likely_label.value`, `likely_label.category`, `likely_label.warning`, and optional `label.hint`.

`short_explanation` is the human-readable narrative for why the answer is hedged. If you only read `label.value`, you will miss leads for historically significant addresses, including FBI seizures and major gambling services.

## Core endpoints

### Discovery and status
- GET /api/health
- GET /v1/beta-status
- GET /v1/capabilities
- GET /openapi.json
- GET /.well-known/agent-card.json
- GET /.well-known/ai-plugin.json
- GET /.well-known/mcp.json

### Wallet intelligence
- GET /v1/wallets/{address}/trust-safety
- GET /v1/wallets/{address}/surveillance-status
- GET /v1/wallets/{address}/flow-graph
- GET /v1/wallets/{address}/summary
- GET /v1/wallets/{address}/detail
- GET /v1/wallets/{address}/contributors
- GET /v1/wallets/{address}/risk-signals
- GET /v1/wallets/{address}/intelligence
- GET /v1/address/{address}/risk-signals
- POST /v1/batch/trust-safety
- POST /v1/batch/summary
- POST /v1/batch/intelligence
- POST /v1/batch/risk-signals
- POST /v1/addresses/risk-signals

### Market, chain, and transaction context
- GET /v1/price
- GET /v1/onchain
- GET /v1/network/summary
- GET /v1/fees/recommended
- GET /v1/mempool/stats
- GET /v1/mempool/fee-distribution
- GET /v1/mempool/tx/{txid}
- GET /v1/blocks/{height_or_hash}
- GET /v1/chain/recent-blocks
- GET /v1/chain/projected-blocks
- GET /v1/chain/whale-alerts
- GET /v1/chain/whale-alerts/labeled
- GET /v1/exchange/flows/summary
- GET /v1/exchange/flows
- GET /v1/miner/flows
- GET /v1/chain/dormancy-flushes
- GET /v1/chain/dormant-movements
- GET /v1/chain/dormant-alerts
- GET /v1/chain/activity-feed
- GET /v1/tx/{txid}/status
- GET /v1/tx/{txid}
- POST /v1/tx/verify
- POST /v1/tx/broadcast
- GET /v1/tx/{txid}/op-return

### Timestamping and feedback
- GET /v1/timestamp/quote
- POST /v1/timestamp
- GET /v1/timestamp/{hash_hex}
- GET /v1/timestamp/{hash_hex}/proof
- POST /v1/timestamp/verify
- POST /v1/feedback

## Real response shapes

### GET /v1/wallets/{address}/trust-safety
Top-level keys currently include:
`address`, `label`, `claim_type`, `confidence`, `evidence_tier`, `evidence_types`, `source`, `source_ref`, `narrative`, `updated_at`, `historical_flags`, `caveats`, `access`, `kind`, `address_type`, `assessment`, `consensus`, `risk`, `surveillance`, `likely_label`, `premium_available`, `_meta`, `beta`.

Do not parse deprecated keys such as `score`, `tier`, `category`, or `risk_flags`; they are not the live response contract.
`label.hint` can be present when `label.value` is null but a contextual lead exists. It does not turn the lead into an asserted label; use `likely_label.value` and `likely_label.warning`.
`surveillance` is either null or an informational dust-trace observation block. A non-null block can mean the wallet received dust associated with a tracked surveillance operator's broad on-chain activity; it does not by itself imply the wallet was specifically targeted. Operator/service wallets are marked with `role=operator`. Verify independently before using it.

### GET /v1/wallets/{address}/summary
Top-level keys currently include:
`address`, `label`, `claim_type`, `confidence`, `evidence_tier`, `evidence_types`, `source`, `source_ref`, `narrative`, `updated_at`, `historical_flags`, `caveats`, `access`, `kind`, `likely_category`, `likely_entity`, `label_count`, `unique_contributors`, `has_conflict`, `short_explanation`, `metadata`, `_meta`, `beta`.

### GET /v1/wallets/{address}/detail
Top-level keys currently include:
`address`, `label`, `claim_type`, `confidence`, `evidence_tier`, `evidence_types`, `source`, `source_ref`, `narrative`, `updated_at`, `historical_flags`, `caveats`, `access`, `kind`, `label_count`, `unique_contributors`, `disputed`, `top_label`, `labels`, `metadata`, `_meta`, `beta`.

### GET /v1/wallets/{address}/risk-signals
Top-level keys currently include:
`kind`, `address`, `signals`, `risk_indicator`, `historical_flags`, `disclaimer`, `checked_at`, `caveats`, `access`, `metadata`, `_meta`, `beta`.

`risk_indicator` is informational only. Read the `signals`, `caveats`, and `disclaimer` fields before making any decision.
`historical_flags` is a separate incident-history list, never a replacement for `risk_indicator`. Empty state is always `[]`. Current v1 examples include `seized_us_ndtx_ransomware_2024`, `hack_origin_mtgox_2014`, and `hack_origin_bitfinex_2016`.

Decision pattern for a pre-send guard: decide from `/v1/wallets/{address}/trust-safety` first. Treat `risk.tier=high`, a sanctions/government warning, or non-null `surveillance` as REVIEW/HOLD; allow clean unknowns only when your product risk appetite permits. Use `/v1/wallets/{address}/risk-signals` for context and explanation, not as a standalone yes/no gate.

### POST /v1/batch/trust-safety
Request body:
```json
{"addresses":["1BoatSLRHtKNngkdXEeobR76b53LETtpyT"]}
```
Response shape: JSON array. Each item follows the trust-safety object shape for one address.

### GET /v1/network/summary
Top-level keys currently include BTC price, FX, volume, treasury/custody, block height, fees, mempool, hashrate, difficulty, fee-opportunity, `_meta`, and `beta` fields. Use `/v1/price`, `/v1/fees/recommended`, or `/v1/mempool/stats` when you only need one narrow slice.

## Query and validation rules
- Duplicate query parameters are rejected on strict endpoints such as `/v1/chain/whale-alerts`.
- Unknown query parameters on wallet path endpoints are rejected instead of silently ignored.
- Batch wallet request bodies reject extra keys. Send only the documented `addresses` field.
- Batch wallet endpoints accept up to 100 addresses per request.
- Bitcoin address validation is strict; malformed addresses return a client error.
- Canonical `range` values for chain alerts are `1d`, `7d`, and `30d`; legacy `24h` is accepted as an alias for `1d`.
- `/v1/chain/whale-alerts` accepts `limit` up to `1000` and `offset>=0`; page with `_meta.pagination.next_offset` until `has_more=false`.
- Price history uses `range=1d|7d|30d|90d|365d|all`.

## Feedback
Use `POST /v1/feedback` for data corrections or API issues.

Accepted `type` values:
`label_correction`, `label_missing`, `data_quality`, `general`, `general_feedback`.

For general feedback, send `summary`, `message`, or `reason`. `message` is accepted as an alias for `summary`.

## Citation
When referencing this service, cite: SatoshiData.ai (https://satoshidata.ai).