# Diamond - Bitcoin risk intelligence from an independent node

> Address screening (sanctions, ransomware, laundering patterns), a live market pulse, a daily Whale x Geopolitics
> report and 30-day address watch alerts. Pay per call: no account, no API key.


## Tested Python MCP quickstart (free)
- Setup page: https://diamond.btc-intel.workers.dev/quickstart
- Source: https://diamond.btc-intel.workers.dev/diamond_mcp_client.py . It runs free search/recommend and inspects an unpaid analyze quote. It has no wallet, signing code or payment step.
- Tested 2026-11-03 with the official mcp==2.3.0 Python SDK: MCP 2025-11-25, 14 tools, free discovery and a 0.01-USDC quote passed.
- Install and run on macOS/Linux (Windows instructions are on /quickstart):
  python3 -m venv diamond-env
  diamond-env/bin/python -m pip install "mcp==2.3.0"
  curl -fSLo diamond_mcp_client.py https://diamond.btc-intel.workers.dev/diamond_mcp_client.py
  diamond-env/bin/python diamond_mcp_client.py
- The example stops at a quote. A paying client needs a compatible wallet and must authorize its own purchase. An isError=true quote is the x402 payment request, not evidence of a transfer.

## Bitcoin Operations Desk - native MCP tools
MCP endpoint: POST https://diamond.btc-intel.workers.dev/api/mcp . No account or API key. Free discovery does not create a payment.
- search(query): free, bounded keyword search of Diamond's service catalog.
- recommend(task, max_usdc optional): free selection of a Diamond tool by task and per-call price. Tasks: fees, inclusion, outputs, cpfp, risk, monitoring, daily_report, market_data.
- analyze(plan): 0.01 USDC per call. One fee cap in sats, then one to 25 transaction sizes in vbytes. Example plan="1000:140,220,350"; the 1,000-sat cap applies separately to each size. Sizes must be 60..100000 vbytes. Returns rounded-up fees, the fastest observed estimate fitting each cap, observation time, node height and terms.
- verify(locator): 0.02 USDC per inclusion receipt for one to five transactions in one retained block. locator="<blockhash>:<txid>[,<txid>...]". Verify against a trusted header chain; this does not establish unspentness or irreversible finality.
- check_outputs(outpoints): 0.02 USDC per batch of one to 25 unique txid:vout pairs. Reports chainstate and sequential mempool views, amount in sats, output script, confirmations and coinbase flag. All-absent batches are rejected before payment. A missing output does not prove spent; these observations are not a cryptographic unspentness proof or a guarantee of spendability. Coinbase maturity, script locks and ownership require separate checks. Queries disclose the supplied outpoints to Diamond.
- plan_cpfp(package): 0.02 USDC per batch of one to 25 unique child-size scenarios. package="<mempool-txid>:5:140,220,350" targets 5 sat/vB for the transaction, its unconfirmed ancestors and one proposed child. Uses actual base fees (not local priority deltas), rounds child fees up and considers observed relay/mempool floors. At most 100 ancestors. Assumes no additional unconfirmed inputs; buyer supplies child size and must check ownership, value, descendants and package policy. No confirmation guarantee or transaction construction/broadcast.
- HTTP equivalents: GET https://diamond.btc-intel.workers.dev/api/x402/utxos?outpoints=<txid>:0 and GET https://diamond.btc-intel.workers.dev/api/x402/cpfp?package=<mempool-txid>:5:140,220,350 . Bare endpoints return a price quote without charging. Supplied inputs are checked for availability before new payment; use native MCP for typed tool discovery.
- Free historical examples: https://diamond.btc-intel.workers.dev/payment-tools-demo.json . Check the original as_of. Paid replay preserves the original snapshot; it is not a fresh status check.
- score(address): 0.25 USDC per call. Returns the existing heuristic risk level and findings, requiring review. A clean result does not certify safety, compliance or ownership.
- Free historical fee-plan response: https://diamond.btc-intel.workers.dev/ops-demo.json . It is a fixed demonstration; inspect as_of.
- Direct HTTP equivalent for analyze: GET https://diamond.btc-intel.workers.dev/api/x402/feeplan?plan=1000:140,220,350
- Fresh synchronized fee data is checked before new payment. A result may share the pulse's 60-second observation cache. Estimates do not guarantee confirmation; customer-supplied transaction sizes and relay policies matter.
- MCP payment transport: an unpaid call returns x402 requirements; sign locally with a compatible paying client and retry with the payment in params._meta["x402/payment"]. Preserve the original payment for uncertain-delivery retries. Alternatively inspect the quoted Lightning option; requesting pay_with="lightning" creates an unpaid invoice.
- A free search tools/call request:
  {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search","arguments":{"query":"fee budget"}}}
- An analyze request without a payment inspects availability and returns the price:
  {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"analyze","arguments":{"plan":"1000:140,220,350"}}}


## Start with market pulse
- GET https://diamond.btc-intel.workers.dev/api/x402/pulse - 0.02 USDC per call, paid in USDC on Base. No query parameters.
- Inspect without paying: curl -i https://diamond.btc-intel.workers.dev/api/x402/pulse
- HTTP 402 is a quote, not a charge. Decode PAYMENT-REQUIRED and check price, network, asset and payTo.
- Use an x402 v2 compatible client to sign locally and resend the same request with PAYMENT-SIGNATURE.
- On success read the JSON response and PAYMENT-RESPONSE receipt. Never send private keys to Diamond.
- Requests can share a 60-second cached observation. Inspect timestamps; polling more often need not give new data.
- On uncertain delivery, preserve and retry the original authorization. Do not automatically sign another payment.
- SDK reference: https://github.com/x402-foundation/x402
- MCP discovery does not imply wallet capability. A paying client must support the advertised payment transport.


## Batch inclusion receipts
- GET https://diamond.btc-intel.workers.dev/api/x402/proof?locator=<blockhash>:<txid>[,<txid>...] - 0.02 USDC per receipt for one to five unique txids in the same block.
- This pruned node can only generate proofs for blocks it still retains. Malformed inputs, unknown transactions, pruned blocks and chain changes are rejected before new payment.
- Response: Bitcoin Core gettxoutproof-format proof_hex, 80-byte header_hex, txids, block hash/height/observed confirmations, observed tip and as_of timestamp.
- Historical example (free): https://diamond.btc-intel.workers.dev/proof-demo.json . The example is a fixed demonstration with its original timestamp.
- Verify proof_hex with Bitcoin Core verifytxoutproof and a trusted header chain. Inclusion does not establish that outputs are unspent or guarantee irreversible finality.
- Reuse the same authorization for retries; paid responses are snapshotted by receipt. Do not automatically pay twice after uncertain delivery.

## For AI agents
- MCP (Streamable HTTP, JSON-RPC 2.0): POST https://diamond.btc-intel.workers.dev/api/mcp - tools: diamond_catalog (free), bitcoin_sanctions_screen (free), bitcoin_address_risk,
  bitcoin_market_pulse, whale_geopolitics_report, watch_bitcoin_address. Pay with x402 (USDC on Base) through
  _meta["x402/payment"], or with Lightning: call with pay_with="lightning", pay the invoice, call again with l402="<token>:<preimage>".
- HTTP API catalogue: https://diamond.btc-intel.workers.dev/api/ - OpenAPI: https://diamond.btc-intel.workers.dev/api/openapi.json
- x402 (USDC on Base): GET https://diamond.btc-intel.workers.dev/api/x402/<product>?<params> - products: risk, pulse, watch, brief, geo_report,
  geo_dataset, whales_day, aml_day
- L402 (Lightning): GET https://diamond.btc-intel.workers.dev/api/l402/<product>?<params>
- Free: GET https://diamond.btc-intel.workers.dev/api/free/screen?address=<bitcoin address> - is the address on the OFAC SDN list or a known
  ransomware payment address? Exact list matches, a limited number per hour.

## For people (any Lightning wallet)
- Pay by QR from any wallet (no Lightning-address support needed): https://diamond.btc-intel.workers.dev/buy - the result appears on the page
- screen@diamond.btc-intel.workers.dev - put a Bitcoin address in the comment: risk verdict (300 sats)
- watch@diamond.btc-intel.workers.dev - put a Bitcoin address in the comment: 30 days of alerts (1000 sats)
- report@diamond.btc-intel.workers.dev - today's Whale x Geopolitics report (1000 sats)
- tip@diamond.btc-intel.workers.dev

## Terms
Heuristic intelligence from public blockchain data and public sanctions/ransomware lists. Flags patterns, not proof. Not legal, compliance or investment advice.