API documentation

Authentication

Every request carries your API key in the Authorization header. You get two keys: ck_test_… (sandbox — simulated transactions, free) and ck_live_… (production).

$ curl https://api.cryptanio.com/v1/watches \
  -H "Authorization: Bearer ck_live_4t9G…R1SC"

Quickstart

One request starts the watching. The next transaction on that address triggers your first alert — typically within seconds of the transaction entering a block.

$ curl -X POST https://api.cryptanio.com/v1/watches \
  -H "Authorization: Bearer ck_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "chain":   "ethereum",
    "address": "0x7c3A1d4E8b2f6C9a0D5e8F1b4C7a2E5d8B1f9eF2",
    "asset":   "USDC",
    "notify":  ["webhook", "telegram"],
    "meta":    { "invoice_id": "inv_8817" }
  }'

{
  "id":      "wch_01J5WQ4T9GZ3MH8B",
  "status":  "active",
  "chain":   "ethereum",
  "address": "0x7c3A…9eF2",
  "asset":   "USDC"
}

Set your webhook endpoint and Telegram chat in the dashboard, or per-request via notify_url. Test everything against the sandbox first: watches created with a ck_test_ key can be triggered manually with POST /v1/simulate.

Watches API

A watch is one address plus one asset on one chain. It's the unit your plan counts. All endpoints live under https://api.cryptanio.com/v1.

Request fields

Webhooks

Each state change is one HTTP POST to your endpoint. Delivery is at-least-once: duplicates are possible and expected — deduplicate on (chain, tx_id, index, address, asset), or simply on event_id.

Payload

{
  "event_id":    "01J5WQ4T9GZ3MH8B2E7KD6R1SC",
  "event_type":  "payment.confirmed",
  "chain":       "ethereum",
  "occurred_at": "2026-08-16T13:52:01Z",
  "watch_id":    "wch_01J5WQ4T9GZ3MH8B",
  "meta":        { "invoice_id": "inv_8817" },
  "payment": {
    "tx_id":         "0x9b41f2…c77d",
    "index":         2,
    "height":        20731442,
    "address":       "0x7c3A…9eF2",
    "asset":         "USDC",
    "contract":      "0xA0b8…eB48",
    "amount_raw":    "250000000",
    "decimals":      6,
    "amount":        "250.00",
    "confirmations": 12
  }
}

• amount_raw is a string in the asset's minimal units. JSON numbers lose precision above 2⁵³ and can't hold an Ethereum uint256 — parse with a big-integer type. amount is a convenience decimal string, safe for display.
• index separates several credits inside one transaction: a Bitcoin output index, an Ethereum log index, zero on Solana.
• meta echoes whatever you attached to the watch — route events without a database lookup.

Retries

• Timeout per attempt: 10 s. Any non-2xx response, or none, schedules a retry.
• Exponential backoff from 2 s up to 15 min, for 24 hours.
• Missed something anyway? GET /v1/events re-serves the last 30 days.

Verifying signatures

The signature is a hex HMAC-SHA256 over the string <timestamp>.<raw body>, keyed with your webhook secret (dashboard → Webhooks). Verify in constant time and reject stale timestamps to close replays.

const crypto = require("node:crypto");

function verify(secret, timestamp, rawBody, signature) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signature));
}

// reject if |now − timestamp| > 300 s, then verify

func verify(secret, ts string, body []byte, sig string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(ts))
    mac.Write([]byte("."))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(sig))
}

Payment lifecycle

Every payment moves through an explicit state machine, and every transition is exactly one event per channel.

A payment reversed by a reorganisation and later re-mined produces a new pending → confirmed sequence with a new revision — your event log stays complete and ordered.

Limits & billing

Plans differ only in volume — features are identical everywhere except SLA and support level. Full pricing on the main page.

• A watch = one address + one asset. Active watches count; deleted or expired ones free the slot immediately.
• An alert = one state change on one channel. Retries of the same event are free.
• Over the limit? Alerts keep flowing for 48 hours while we email you — no surprise charges, nothing silently dropped.
• API rate limit: 10 requests/s (Free), 50 requests/s (paid plans). 429 with Retry-After beyond that.