Operator API

Keep your listings accurate from your own system: status, live fees, hours and new machines.

Authentication

Create a key in your dashboard and send it as Authorization: Bearer km_live_…. Test keys (km_test_…) validate everything without writing.

The essentials

Use our id or your own externalId in URLs.
An hourly heartbeat keeps the listing “Confirmed minutes ago”. With no heartbeat for 30 days, the listing shows as Not confirmed.
Fees are all-in (charge plus spread) as a percent of cash.
Address changes are checked before they go live.
Limit: 600 requests a minute per key (2,000 for heartbeats).

Heartbeat: the machine is working, with live fees

curl -X POST https://bitcoinscouts.com/api/v1/machines/YOUR-ID/heartbeat \
  -H "Authorization: Bearer km_live_…" \
  -H "Content-Type: application/json" \
  -d '{"buyFeePct": 14.5, "sellFeePct": 7}'

Mark a machine temporarily closed

curl -X PATCH https://bitcoinscouts.com/api/v1/machines/YOUR-ID \
  -H "Authorization: Bearer km_live_…" \
  -H "Content-Type: application/json" \
  -d '{"status": "closed", "reopensOn": "2026-11-02"}'

Create or update many machines

curl -X POST https://bitcoinscouts.com/api/v1/machines/bulk \
  -H "Authorization: Bearer km_live_…" \
  -H "Content-Type: application/json" \
  -d '{"machines": [{"externalId": "BT400123", "name": "Newark Ave Corner Market",
       "street": "212 Newark Ave", "city": "Jersey City", "state": "NJ",
       "buy": true, "sell": true, "coins": ["BTC","LTC"], "buyFeePct": 15}]}'

List your machines

curl https://bitcoinscouts.com/api/v1/machines?limit=100 -H "Authorization: Bearer km_live_…"

OpenAPI 3.1 (openapi.json)