API documentation

Connect Cryptanio to your application.

Contract v1 / 1.1.3 5 / 2026-11-17

Contents

Get started

The API is for your server. Configure Live services and address pools in Account, or select Sandbox for integration tests.

  1. Verify your account. For Live, activate the service you need in My services; Sandbox testing requires no paid service.
  2. Create an API key with the minimum permissions and keep it on your server.
  3. Choose your task: monitor an address, create an invoice or receive events.

Examples use the mode selected by your API key. Live writes may consume service quotas. Keys are never embedded in examples; they are read from environment variables.

Start with Sandbox without sending cryptocurrency

Instructions for your agent

Paste this instruction into your agent's chat or project rules. It helps the agent learn about the services, pricing and reference, then write an application integration using the REST API or SDK. The agent can answer in your language.

Integration instructions
Learn how to integrate a server-side application with Cryptanio's public REST API before proposing or writing integration code.

Start here:
- Website: https://cryptanio.com/
- Documentation index: https://cryptanio.com/llms.txt
- Product, services and pricing: https://cryptanio.com/cryptanio.md
- API integration index: https://cryptanio.com/docs/llms.txt
- API guide: https://cryptanio.com/docs.md
- Exact API v1 contract: https://cryptanio.com/openapi.json
- FAQ: https://cryptanio.com/faq/index.md
- SDK setup and examples: https://cryptanio.com/docs.html#sdk

Read the relevant method reference before using it. Live and Sandbox share https://api.cryptanio.com/v1. Check GET /v1/health for sandbox_v1 before using Sandbox. A ck_test_ key selects isolated test data; a ck_live_ key selects Live. Internal development hosts are not public integration endpoints.
Use HTTP requests or the documented SDK for the application's language. Match request fields, response schemas and errors to OpenAPI; do not invent endpoints or SDK methods.
Check the actual enabled networks, service, project and API key permissions. Product documentation is not evidence of a live payment, balance or deployment.
Keep API keys in the user's server environment or secret store. Never ask the user to paste a key into chat or put it in a URL, browser bundle or log.
Default to reading. Create, change or delete objects only when the user authorizes the specific task. Explain quota or billing consequences before a write.
Follow the documented confirmation, webhook verification, pagination and retry rules. Reuse an invoice's original Idempotency-Key and request when retrying.
Show the returned chain, asset, address, amount and expiry. Preserve payment_route.kind and its exact string value: destination_tag, memo, comment or reference is mandatory when present. The merchant order reference is a separate field.
For a Live payment QR use the returned payment_uri when present. Sandbox payment details must never be funded. A Solana Pay reference is not a wallet memo; do not rebuild its URI or replace it with a plain address. Offer the exact returned checkout_url only to the payer; never construct a checkout URL from an invoice ID. Neither a checkout redirect nor a QR scan confirms payment.
Distinguish pending, confirmed, rolled-back and simulated data. If a fact is unavailable, say so instead of guessing.
Answer the user's questions in their language. If a necessary product decision is not documented, ask instead of inventing it.

This block contains no keys or account data. Use an API key with the minimum permissions for your integration and keep it on your application server. Do not share the key in the agent's chat.

API reference

Methods: 17

Authentication

Send Authorization: Bearer <API_KEY> from your server. Create a Live or Sandbox key in Account → API keys, limited to the projects and operations you need. Use Sandbox mode for integration tests.

A key may allow read-only access, selected operations, one project or service, and selected IP/CIDR ranges. Expiry, pause and revocation also affect access. To rotate a key, create its replacement with appropriate restrictions, switch your integration, then revoke the old key. Never embed keys in browser code, mobile apps or URLs.

ScopePurpose
watchesMonitoring
eventsEvents and payments
invoicesPayments invoices
webhooksWebhook endpoints
streamSSE
simulationSimulate a Sandbox payment

Restrictions apply together, not instead of each other. 401 means the key was not accepted; 403 can mean insufficient permissions or a disallowed IP. An inaccessible resource may return 404. See errors and retries.

Sandbox

Live and Sandbox use the same API base URL and v1 contract. A test key selects isolated test data. The X-Cryptanio-Mode response header reports the mode. Check health.capabilities for sandbox_v1 first; the documentation version does not prove deployment.

Sandbox lets you test addresses, invoices, events, deliveries, notifications and API keys without a paid service or cryptocurrency transfer. Pay and subscriptions are excluded from this release.

  1. Open Sandbox in Account and choose a project. Open the current mode button on the right of the project bar to choose Live or Sandbox. On narrow screens, projects and controls stay on one line; scroll the projects or open the project list.
  2. In Addresses, add a test address. In Invoices, create a test invoice with a network and amount.
  3. Before simulating a payment, open Notifications and add a separate webhook or explicitly enable email or Telegram. Live recipients are not inherited. Test messages are sent to the real destinations you select.
  4. Select Simulate payment beside an address or invoice. In the same open dialog, apply Payment pending, then Confirm payment to continue that transaction. Choose New payment for a separate additional transfer. Then check Events and Deliveries.
  5. For your server integration, create a test key in API keys. Use ck_test_… with the same https://api.cryptanio.com/v1; replace invoice_id in the example below with your test invoice ID.

The 200 invoices per day are a creation budget, not a concurrency limit. For the same requested amount on one address, at most 20 open invoice slots are available. The returned amount may differ by the smallest units; use the exact amount from the response. Closing an invoice frees its slot; a different test address uses a separate pool.

POST /v1/simulate requires a test write key, simulation scope and Idempotency-Key. Supply exactly one invoice_id or watch_id. Omit transaction_id for a new payment and retain the returned ID to confirm or roll back that transaction. A retry preserves its operation key and body; the next transition uses a new operation key.

Shell / cURL
#!/usr/bin/env bash
set -euo pipefail
: "${CRYPTANIO_API_KEY:?Set CRYPTANIO_API_KEY}"
: "${CRYPTANIO_OPERATION_ID:?Set CRYPTANIO_OPERATION_ID}"
response_file="$(mktemp)"
trap 'rm -f "$response_file"' EXIT
transfer_status=0
http_status="$(curl \
  --silent --show-error --max-time 30 --request POST \
  --header "Authorization: Bearer $CRYPTANIO_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $CRYPTANIO_OPERATION_ID" \
  --data-binary '{"invoice_id":"2001","event_type":"payment.pending","amount_raw":"1000000"}' \
  "https://api.cryptanio.com/v1/simulate" \
  --output "$response_file" --write-out '%{http_code}')" || transfer_status=$?
if [[ "$http_status" == 2?? ]]; then
  cat "$response_file"
  exit "$transfer_status"
fi
printf 'HTTP %s\n' "$http_status" >&2
cat "$response_file" >&2
exit 1

Use amount_raw for underpayment, additional payment or overpayment. A test transaction keeps its amount and asset. The expire and late actions affect only the selected invoice. Expiry creates no event or webhook; a late payment follows normal acceptance rules, so check invoice_status.

Webhooks use HTTPS delivery and the normal signature format with a separate Sandbox secret. Recipients are explicitly configured and never inherited from Live. Test email and Telegram are off by default. Delivery history and replay stay in Sandbox. Replaying a webhook does not create another payment.

Sandbox does not spend Live balances or quotas and does not request blockchain or exchange-rate data. Account limits: 2 requests/s with burst 4, 100 active addresses, 200 invoices and 500 events per UTC day, 200 physical delivery attempts per UTC day. Each delivery has at most 3 attempts and expires after 1 hour or the next UTC midnight, whichever comes first.

Demonstration addresses use normal address formats. Do not send real funds to them. Sandbox provides no wallet balance, payment QR or mainnet payment link.

Test invoice, event, delivery and scenario history is retained for 30 days and may be removed on the next Sandbox operation. Active test addresses remain until you remove them.

Each new delivery reserves all 3 attempts from the daily pool of 200. This allows at most 66 new deliveries per account per UTC day, even when the first attempt succeeds.

SDK: ready-to-use clients

Download the file for your language, save it on your application server and pass your key to its constructor. Each client covers all 17 methods in this reference. There is no npm, PyPI, Composer or crates.io package to install: the downloaded files are the SDK.

LanguageRequirementsFile
Node.jsNode.js 18+cryptanio.mjs
PythonPython 3.10+cryptanio.py
PHPPHP 8.1+ / cURLCryptanio.php
GoGo 1.22+cryptanio.go
RustRust 2021 / reqwest 0.12 / serde_json 1cryptanio.rs

The files share release 1.1.3 5. The manifest contains the version, contract and each file's SHA-256. Set CRYPTANIO_API_KEY and CRYPTANIO_PROJECT_ID in your environment first. These examples only read events, but access live account data.

Node.js

Save the example as a .mjs file next to cryptanio.mjs.

Node.js
import { Cryptanio } from './cryptanio.mjs';
const key = process.env.CRYPTANIO_API_KEY;
const project = process.env.CRYPTANIO_PROJECT_ID;
if (!key || !project) throw new Error('Set API key and project ID');
const api = new Cryptanio(key);
const page = await api.listEvents({ project, limit: 25 });
console.log(page);

To read an existing invoice's payment instructions, set its ID in CRYPTANIO_RESOURCE_ID. The next example preserves the required payment_route, returned payment_uri for the QR and exact checkout_url. Pass the result to the payer through your interface; keep it out of public logs. Amounts remain strings and absent fields are omitted.

Node.js
import { Cryptanio } from './cryptanio.mjs';
const key = process.env.CRYPTANIO_API_KEY;
const invoiceID = process.env.CRYPTANIO_RESOURCE_ID;
if (!key || !invoiceID) throw new Error('Set API key and invoice ID');
const api = new Cryptanio(key);
const invoice = await api.getInvoice(invoiceID);
const payment = {
  chain: invoice.chain, asset: invoice.asset, address: invoice.address,
  amount: invoice.amount, expires_at: invoice.expires_at,
  payment_route: invoice.payment_route,
  payment_uri: invoice.payment_uri, checkout_url: invoice.checkout_url,
};
console.log(JSON.stringify(payment, null, 2));
Python

Save the example as a .py file next to cryptanio.py.

Python
import os
from cryptanio import Cryptanio
api = Cryptanio(os.environ['CRYPTANIO_API_KEY'])
page = api.list_events({
    'project': os.environ['CRYPTANIO_PROJECT_ID'], 'limit': 25
})
print(page)

To read an existing invoice's payment instructions, set its ID in CRYPTANIO_RESOURCE_ID. The next example preserves the required payment_route, returned payment_uri for the QR and exact checkout_url. Pass the result to the payer through your interface; keep it out of public logs. Amounts remain strings and absent fields are omitted.

Python
import json
import os
from cryptanio import Cryptanio
api = Cryptanio(os.environ['CRYPTANIO_API_KEY'])
invoice = api.get_invoice(os.environ['CRYPTANIO_RESOURCE_ID'])
payment = {field: invoice[field] for field in (
    'chain', 'asset', 'address', 'amount', 'expires_at',
    'payment_route', 'payment_uri', 'checkout_url'
) if field in invoice}
print(json.dumps(payment, ensure_ascii=False))
PHP

Save the example as a .php file next to Cryptanio.php; enable the cURL extension.

PHP
<?php
require __DIR__ . '/Cryptanio.php';
$key = getenv('CRYPTANIO_API_KEY');
$project = getenv('CRYPTANIO_PROJECT_ID');
if (!$key || !$project) throw new RuntimeException('Set API key and project ID');
$api = new Cryptanio($key);
$page = $api->listEvents(['project' => $project, 'limit' => 25]);
echo json_encode($page, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR);

To read an existing invoice's payment instructions, set its ID in CRYPTANIO_RESOURCE_ID. The next example preserves the required payment_route, returned payment_uri for the QR and exact checkout_url. Pass the result to the payer through your interface; keep it out of public logs. Amounts remain strings and absent fields are omitted.

PHP
<?php
require __DIR__ . '/Cryptanio.php';
$key = getenv('CRYPTANIO_API_KEY');
$invoiceID = getenv('CRYPTANIO_RESOURCE_ID');
if (!$key || !$invoiceID) throw new RuntimeException('Set API key and invoice ID');
$api = new Cryptanio($key);
$invoice = $api->getInvoice($invoiceID);
$payment = array_intersect_key($invoice, array_fill_keys([
    'chain', 'asset', 'address', 'amount', 'expires_at',
    'payment_route', 'payment_uri', 'checkout_url'
], true));
echo json_encode($payment, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR);
Go

Place the file in a cryptanio/ directory within your Go module. This example uses module example.local/myapp; replace the import path with your own module name. No external dependencies are needed.

Go
package main

import (
    "context"
    "fmt"
    "os"
    "example.local/myapp/cryptanio"
)

func main() {
    key, project := os.Getenv("CRYPTANIO_API_KEY"), os.Getenv("CRYPTANIO_PROJECT_ID")
    if key == "" || project == "" { panic("Set API key and project ID") }
    api, err := cryptanio.New(key, "", 0)
    if err != nil { panic(err) }
    page, err := api.ListEvents(context.Background(), map[string]any{
        "project": project, "limit": 25,
    })
    if err != nil { panic(err) }
    fmt.Println(page)
}

To read an existing invoice's payment instructions, set its ID in CRYPTANIO_RESOURCE_ID. The next example preserves the required payment_route, returned payment_uri for the QR and exact checkout_url. Pass the result to the payer through your interface; keep it out of public logs. Amounts remain strings and absent fields are omitted.

Go
package main

import (
    "context"
    "encoding/json"
    "os"
    "example.local/myapp/cryptanio"
)

func main() {
    key, invoiceID := os.Getenv("CRYPTANIO_API_KEY"), os.Getenv("CRYPTANIO_RESOURCE_ID")
    if key == "" || invoiceID == "" { panic("Set API key and invoice ID") }
    api, err := cryptanio.New(key, "", 0)
    if err != nil { panic(err) }
    invoice, err := api.GetInvoice(context.Background(), invoiceID)
    if err != nil { panic(err) }
    payment := make(map[string]any)
    for _, field := range []string{
        "chain", "asset", "address", "amount", "expires_at",
        "payment_route", "payment_uri", "checkout_url",
    } {
        if value, ok := invoice[field]; ok { payment[field] = value }
    }
    if err := json.NewEncoder(os.Stdout).Encode(payment); err != nil { panic(err) }
}
Rust

Save the file as src/cryptanio.rs and the example as src/main.rs. Add the dependencies below to Cargo.toml. This is a synchronous blocking client: do not run it directly on an async worker.

Cargo.toml
[dependencies]
reqwest = { version = "=0.12.24", default-features = false, features = ["blocking", "json", "rustls-tls"] }
serde_json = "=1.0.145"
Rust
mod cryptanio;
use cryptanio::Cryptanio;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api = Cryptanio::new(&std::env::var("CRYPTANIO_API_KEY")?)?;
    let project = std::env::var("CRYPTANIO_PROJECT_ID")?;
    let page = api.list_events(&[("project", &project), ("limit", "25")])?;
    println!("{page}");
    Ok(())
}

To read an existing invoice's payment instructions, set its ID in CRYPTANIO_RESOURCE_ID. The next example preserves the required payment_route, returned payment_uri for the QR and exact checkout_url. Pass the result to the payer through your interface; keep it out of public logs. Amounts remain strings and absent fields are omitted.

Rust
mod cryptanio;
use cryptanio::Cryptanio;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api = Cryptanio::new(&std::env::var("CRYPTANIO_API_KEY")?)?;
    let invoice = api.get_invoice(&std::env::var("CRYPTANIO_RESOURCE_ID")?)?;
    let mut payment = serde_json::Map::new();
    for field in ["chain", "asset", "address", "amount", "expires_at",
                  "payment_route", "payment_uri", "checkout_url"] {
        if let Some(value) = invoice.get(field) {
            payment.insert(field.to_owned(), value.clone());
        }
    }
    println!("{}", serde_json::Value::Object(payment));
    Ok(())
}

Calling methods

Node.js and PHP use listEvents, Python and Rust use list_events, Go uses ListEvents. Each method maps to one request in the reference. Filters are an object/map, or a list of pairs in Rust. Go methods always take context.Context first. Unknown filters are rejected before sending a request.

Node.js / PHP methodHTTP
createWatchPOST /v1/watches
listWatchesGET /v1/watches
getWatchGET /v1/watches/{id}
deleteWatchDELETE /v1/watches/{id}
listEventsGET /v1/events
listPaymentsGET /v1/payments
createInvoicePOST /v1/invoices
listInvoicesGET /v1/invoices
getInvoiceGET /v1/invoices/{id}
cancelInvoicePOST /v1/invoices/{id}/cancel
createEndpointPOST /v1/endpoints
listEndpointsGET /v1/endpoints
deleteEndpointDELETE /v1/endpoints/{id}
streamEventsGET /v1/stream
getHealthGET /v1/health
listChainsGET /v1/chains
simulatePOST /v1/simulate

Watch and webhook creation take a request body. Single-resource methods take its string ID. createInvoice(body, idempotencyKey) requires a 16–80-character key using ASCII letters, digits, hyphens or underscores. Reuse the same key and body for a retry; the SDK does not generate a new key or retry automatically. See each method page for bodies, errors and permissions.

Responses, errors and streaming

JSON responses retain their field names; IDs, amounts and cursors remain strings. Pagination is manual, as documented per method. Errors expose HTTP status, code, message and Retry-After. With no HTTP response, status is 0 (Rust uses None). Redirects are not followed. Regular JSON responses are limited to 8 MiB. The default timeout is 30 seconds, configurable up to 300 seconds. In Python this applies to a network operation; in the other clients it covers the whole request, including streaming. A timeout does not prove a write was not executed.

Language / errorFields
Node.js / Python: ApiErrorstatus, code, message, retry_after
PHP: CryptanioErrorstatus, apiCode, getMessage(), retryAfter
Go: *APIErrorStatus, Code, Message, RetryAfter
Rust: ApiErrorstatus: Option<u16>, code, message, retry_after

streamEvents exposes raw SSE bytes without reconnection or event parsing: a Node.js ReadableStream, a closable Python HTTP response, Go io.ReadCloser, or Rust blocking::Response. Release the stream when no longer needed. PHP passes chunks to a callback; return false to stop. Streaming is not a webhook replacement and does not guarantee history replay; see the SSE rules.

Your first watch

In Account, create a project with an active Monitoring service and a key with watches and events permissions. Complete account verification when required. Copy the project ID from its settings; only add an address you actually want to monitor.

Set CRYPTANIO_API_KEY and CRYPTANIO_PROJECT_ID in your server environment. Replace the example address with your own. This request attaches a real watch; it does not simulate a transaction.

Shell / cURL
#!/usr/bin/env bash
set -euo pipefail
: "${CRYPTANIO_API_KEY:?Set CRYPTANIO_API_KEY}"
: "${CRYPTANIO_PROJECT_ID:?Set CRYPTANIO_PROJECT_ID}"
json_string() {
  local text="$1" char code index output='"'
  for ((index=0; index<${#text}; index++)); do
    char="${text:index:1}"
    case "$char" in
      '"'|'\') output+="\\$char" ;;
      *) printf -v code '%d' "'$char"
         if ((code < 32)); then printf -v char '\\u%04x' "$code"; fi
         output+="$char" ;;
    esac
  done
  printf '%s"' "$output"
}
response_file="$(mktemp)"
trap 'rm -f "$response_file"' EXIT
transfer_status=0
http_status="$(curl \
  --silent --show-error --max-time 30 --request POST \
  --header "Authorization: Bearer $CRYPTANIO_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-binary '{"project":'"$(json_string "$CRYPTANIO_PROJECT_ID")"',"chain":"ethereum","address":"0x52908400098527886E0F7030069857D2E4169EE7","asset":"native","label":"Treasury"}' \
  "https://api.cryptanio.com/v1/watches" \
  --output "$response_file" --write-out '%{http_code}')" || transfer_status=$?
if [[ "$http_status" == 2?? ]]; then
  cat "$response_file"
  exit "$transfer_status"
fi
printf 'HTTP %s\n' "$http_status" >&2
cat "$response_file" >&2
exit 1

A successful response contains id: save it. GET /v1/watches/{id} returns the watch and settings, not payments. To see detected activity, request GET /v1/events filtered by watch_id. An empty list before a transaction is detected is normal. Response, errors and examples in other languages.

Payments invoices

Activate Payments for your project and add supported addresses to its pool in Account. Explicitly send project rather than depending on default project selection. amount is a string in crypto-asset units; invoice_currency/invoice_amount separately describe your order quote.

Set CRYPTANIO_PROJECT_ID to your Payments project and CRYPTANIO_API_KEY to a key with invoices permission. CRYPTANIO_OPERATION_ID must be unique for a new order; reuse it when retrying the same operation. The invoice is created in live data.

Shell / cURL
#!/usr/bin/env bash
set -euo pipefail
: "${CRYPTANIO_API_KEY:?Set CRYPTANIO_API_KEY}"
: "${CRYPTANIO_OPERATION_ID:?Set CRYPTANIO_OPERATION_ID}"
: "${CRYPTANIO_PROJECT_ID:?Set CRYPTANIO_PROJECT_ID}"
json_string() {
  local text="$1" char code index output='"'
  for ((index=0; index<${#text}; index++)); do
    char="${text:index:1}"
    case "$char" in
      '"'|'\') output+="\\$char" ;;
      *) printf -v code '%d' "'$char"
         if ((code < 32)); then printf -v char '\\u%04x' "$code"; fi
         output+="$char" ;;
    esac
  done
  printf '%s"' "$output"
}
response_file="$(mktemp)"
trap 'rm -f "$response_file"' EXIT
transfer_status=0
http_status="$(curl \
  --silent --show-error --max-time 30 --request POST \
  --header "Authorization: Bearer $CRYPTANIO_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $CRYPTANIO_OPERATION_ID" \
  --data-binary '{"project":'"$(json_string "$CRYPTANIO_PROJECT_ID")"',"invoice_currency":"USD","invoice_amount":"12.50","reference":"order-42"}' \
  "https://api.cryptanio.com/v1/invoices" \
  --output "$response_file" --write-out '%{http_code}')" || transfer_status=$?
if [[ "$http_status" == 2?? ]]; then
  cat "$response_file"
  exit "$transfer_status"
fi
printf 'HTTP %s\n' "$http_status" >&2
cat "$response_file" >&2
exit 1

Your key must allow invoices and Payments; the Monitoring example key may be restricted to another service. Idempotency-Key contains 16-80 ASCII letters, digits, - and _. Repeating the same normalized request with the same key returns the existing invoice with 201; changed content returns 409 conflict. Operation keys are account-wide. reference is not a substitute.

Show the buyer the returned network, asset, address, amount and expiry. When payment_route is present, also pass its kind and exact string value: destination_tag, memo, comment or reference is required to attribute the payment to this invoice. The order's reference field is separate.

Use the returned payment_uri for the payment QR when present. A Solana Pay reference is not a wallet memo: do not replace the URI with a plain address or rebuild it. If the wallet cannot include the required discriminator, offer the payer checkout_url or a compatible wallet.

checkout_url is the hosted payment page for newly issued invoices. Share only the exact returned URL with the payer; do not construct it from the ID. The link exposes payment details and status, so keep it out of public logs. If absent, show the full payment instructions. A browser redirect does not confirm payment: check the API or a verified webhook.

asked may differ from amount to distinguish orders. Reconcile using amount_raw as an arbitrary-precision integer. Default TTL is 60 minutes; maximum is 10080 minutes. Invoice lists accept before but do not return next_before: continue with the last item's ID and stop on an empty page.

Customer

FieldTypeRequiredDescription
idstringYesCustomer identifier in your system.
maxLength: 120
Product

FieldTypeRequiredDescription
idstringNoProduct identifier in your system.
maxLength: 120
namestringNoProduct name.
maxLength: 200
quantityintegerNoQuantity.
minimum: 1; maximum: 1000000
Payer

FieldTypeRequiredDescription
commentstringYesPayer comment.
maxLength: 500
InvoiceMetadata

Up to 20 pairs, at most 8192 JSON bytes. Do not include secrets.

object Up to 20 pairs, at most 8192 JSON bytes. Do not include secrets.

Monitoring watches

A watch belongs to one Monitoring project. The same address can be used in multiple projects with independent direction and asset rules. Connect address-book lists and Address Sources in Account; this REST API does not expose their management commands.

The list is ordered by descending ID. If next_before is present, pass it as before in your next request, keeping the project and filters unchanged. limit defaults to 50 and is capped at 200. Store IDs as strings. Removed watches leave the active list; removal here does not delete the address from other projects or the address book.

Events and history

/v1/events returns events available to the key across services; /v1/payments is restricted to Payments. Filter by project, address, chain, type, watch_id and tx_id. before is an ID cursor, not a date; there is no from/to filter. next_before lets you fetch the next page.

Detected event history is available for up to 30 days. This is not an archive of every delivered message: notice and webhook.test messages are not guaranteed to be recoverable through it. REST Event has its own schema, separate from webhooks; additional fields may be added within v1.

Event

FieldTypeRequiredDescription
event_idstringYesOpaque identifier; keep it as a string.
minLength: 1
event_typestringYesEvent type; new types may be added.
chainstringYesNetwork code.
servicestringNoService, when known.
watch_idstringNoProject watch ID, when linked to a watch.
minLength: 1
occurred_atstringYesUTC date and time in RFC 3339.
date-time
reverted_atstringNoUTC time when a chain reorganization reverted the contract event.
date-time
paymentobject | nullYesPayment document, or null for a non-payment event. GET /events does not return contract/notice payloads.
sandboxbooleanNoTest event; omission means false.
EventPayment

REST/SSE payment document. Fields depend on the event and network; not the normalized webhook v1 shape.

FieldTypeRequiredDescription
tx_idstringNoTransaction identifier.
indexintegerNoTransfer index within the transaction.
minimum: 0
heightintegerNoBlock height, when known.
minimum: 0
addressstringNoObserved address.
assetstringNoREST/SSE asset: string identifier, not the webhook asset object.
amount_rawstringNoInteger smallest-unit amount as a string.
pattern: ^[0-9]+$
amountstringNoExact decimal amount as a string; do not use floating point.
pattern: ^[0-9]+(?:\.[0-9]+)?$
decimalsintegerNoDecimal places.
minimum: 0
confirmationsintegerNoConfirmations.
minimum: 0
revisionintegerNoTransfer state revision.
minimum: 0
directionstringNoDirection relative to the observed address.
in, out
simulatedbooleanNoSimulated event.
latebooleanNoLate detected transfer.
block_hashstringNoBlock hash.
match_keystringNoMatch identifier when used by the network.
metaobjectNo
invoiceobjectNo
customerobjectNo
productobjectNo
payerobjectNo
metadataobjectNo

Webhook events

Delivery is at least once: an event can arrive more than once. After verifying the signature, deduplicate by event_id within your integration. Persist processing and your business change in one database transaction. A tx_id/address/asset key does not replace event_id: it merges different transitions, directions and projects.

Read event_type and event_id from the signed body. X-Event-Type/X-Event-Id headers are not included in the HMAC; compare them with the body if you use them. Account for project_id, direction and payment.revision when updating a payment. Do not assume delivery order; safely ignore unknown types while retaining them for diagnosis.

FamilyBody
payment.pending / confirmed / rolled_backIncoming payment
debit.pending / confirmed / rolled_backOutgoing payment
contract.approval / owner_added / owner_removed / threshold_changed / permissions_changedcontract
contract.rolled_backcontract
asset.unexpectedcontract; the asset is not credited as accepted payment
account.notice / account.notification / treasury.alarm / subscription.noticenotice.subject, notice.text
webhook.testControl event without a payment

schema_version: v1 carries payment, contract or notice according to event type; webhook.test has none. IDs and amounts are strings. amount_raw contains minimal units; amount is a decimal representation. Check networks and assets through chains. Full object schemas are available in OpenAPI.

HeaderMeaning
X-TimestampUnix seconds at signing time
X-Signaturehex HMAC-SHA256(timestamp + '.' + raw body)
X-Event-Id / X-Event-TypeCompare with the signed body
X-AttemptAttempt number starting at 1

Return 2xx after durably accepting the event. Attempt timeout is 10 seconds. Network failures, 408, 425, 429 and 5xx retry for up to 24 hours, with delays from 2 seconds to 15 minutes and jitter; Retry-After is respected. Redirects are not followed. Other 3xx/4xx end the delivery; 410 retires the destination and its backlog.

Webhook shape example (illustrative)
{
  "schema_version": "v1",
  "event_id": "2300",
  "event_type": "payment.confirmed",
  "occurred_at": "2026-10-06T10:00:00Z",
  "project_id": "1002",
  "service": "monitoring",
  "mode": "test",
  "sandbox": true,
  "payment": {
    "chain": "ethereum",
    "direction": "in",
    "asset": {
      "symbol": "ETH"
    },
    "address": "0x52908400098527886E0F7030069857D2E4169EE7",
    "tx_id": "simulated_2300",
    "index": 0,
    "amount": "1.000000000000000000",
    "amount_raw": "1000000000000000000",
    "decimals": 18,
    "confirmations": 0,
    "revision": 1,
    "simulated": true
  }
}
Webhook

Public signed webhook v1 body. payment.* and debit.* contain payment; contract.* and asset.unexpected contain contract; webhook.test has no business payload; account.notice, account.notification, treasury.alarm, and subscription.notice contain notice. Deduplicate delivery retries by event_id.

FieldTypeRequiredDescription
schema_versionstringYesWebhook payload version.
v1
event_idstringYesEvent ID: unchanged for delivery retries. Different states can have different event_id values.
minLength: 1
event_typestringYesType in the signed body; use it after verifying the signature. New types may be added.
occurred_atstringYesUTC date and time in RFC 3339.
date-time
project_idstringYesOpaque identifier; keep it as a string.
minLength: 1
servicestringNoProject service, where applicable.
modestringYesEvent mode.
live, test
sandboxbooleanYesExplicit simulation flag.
paymentobjectNo
contractobjectNo
invoiceobjectNo
customerobjectNo
productobjectNo
payerobjectNo
metadataobjectNo
noticeobjectNo
WebhookPayment

FieldTypeRequiredDescription
chainstringYesNetwork code.
directionstringYesIncoming payment: in; outgoing debit: out.
in, out
assetobjectYes
addressstringYesObserved address.
tx_idstringYesTransaction ID.
indexintegerYesTransfer index; do not assume 0 for any network.
minimum: 0
heightintegerNoBlock height if known.
minimum: 0
block_hashstringNoBlock hash if known.
match_keystringNoNetwork match identifier, when applicable.
amountstringYesExact decimal amount as a string; do not use floating point.
pattern: ^[0-9]+(?:\.[0-9]+)?$
amount_rawstringYesInteger smallest-unit amount as a string.
pattern: ^[0-9]+$
decimalsintegerYesDecimal places.
minimum: 0
confirmationsintegerYesConfirmations.
minimum: 0
revisionintegerYesTransfer state revision. Do not collapse distinct event_id values by transaction identity.
minimum: 0
latebooleanNoLate detected transfer; not the same as invoice status late.
simulatedbooleanNoSimulated transfer.
valuationobjectNo
WebhookAsset

FieldTypeRequiredDescription
symbolstringNoSymbol if known; not sufficient to establish token identity.
standardstringNoToken standard if known.
contractstringNoToken contract in its network, where applicable.
identifierstringNoOther network-specific token identifier.
WebhookContract

FieldTypeRequiredDescription
chainstringYesNetwork code.
addressstringYesObserved address or contract.
tx_idstringYesTransaction ID.
indexintegerYesEvent index.
minimum: 0
heightintegerNoBlock height.
minimum: 0
block_hashstringNoBlock hash.
kindstringNoChange kind.
original_event_idstringNoPublic identifier of the original event reverted by contract.rolled_back.
minLength: 1
assetstringNoAffected asset identifier, if known.
detailobjectNo
simulatedbooleanNoSimulated event.
WebhookInvoice

FieldTypeRequiredDescription
idstringYesOpaque identifier; keep it as a string.
minLength: 1
referencestringNoOrder reference.
statusstringNopending awaits payment; seen detected; partial partially paid; paid settled; underpaid/overpaid/late need a decision; expired deadline passed; canceled voided.
pending, seen, paid, underpaid, partial, overpaid, expired, late, canceled
currencystringNoOrder quote currency.
amountstringNoExact decimal amount as a string; do not use floating point.
pattern: ^[0-9]+(?:\.[0-9]+)?$
Notice

FieldTypeRequiredDescription
subjectstringYesNotice subject.
textstringYesNotice text.
Valuation

FieldTypeRequiredDescription
currencystringYesValuation currency, such as USD.
amountstringYesExact decimal amount as a string; do not use floating point.
pattern: ^[0-9]+(?:\.[0-9]+)?$
ratestringYesAsset exchange rate as a decimal string.
pattern: ^[0-9]+(?:\.[0-9]+)?$
rate_atstringYesUTC date and time in RFC 3339.
date-time
providerstringNoQuote source name, if known.

Verifying signatures

Verify the HMAC over the original body bytes before JSON parsing, including whitespace and newlines. Freshness checking limits replay but does not replace persistent event_id deduplication. The examples accept only 64-character hex signatures and timestamps within 300 seconds of server time. Use the secret for the specific webhook destination.

Node.js
import { createHmac, timingSafeEqual } from "node:crypto";
import { TextDecoder } from "node:util";

// rawBody is the original HTTP request Buffer, before JSON.parse or serialization.
export function verifyWebhook(secret, timestamp, rawBody, signature, nowSeconds = Math.floor(Date.now() / 1000)) {
  if (typeof secret !== "string" || secret.length === 0 || !Buffer.isBuffer(rawBody) || rawBody.length === 0 ||
      typeof timestamp !== "string" || !/^(0|[1-9][0-9]*)$/.test(timestamp) ||
      typeof signature !== "string" || !/^[0-9a-f]{64}$/i.test(signature) ||
      !Number.isSafeInteger(nowSeconds) || nowSeconds < 0) return false;

  const signedAt = Number(timestamp);
  if (!Number.isSafeInteger(signedAt) || Math.abs(nowSeconds - signedAt) > 300) return false;

  const expected = createHmac("sha256", secret).update(timestamp).update(".").update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(signature, "hex"));
}

// headers is Node.js request.headers (lowercase names). Optional X-Event-Id/Type
// headers are not signed separately; compare them with the verified body.
export function readSignedWebhook(secret, timestamp, rawBody, signature, headers = {}, nowSeconds) {
  if (!verifyWebhook(secret, timestamp, rawBody, signature, nowSeconds) ||
      headers === null || typeof headers !== "object" || Array.isArray(headers)) return null;

  let event;
  try {
    event = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(rawBody));
  } catch {
    return null;
  }
  if (event === null || typeof event !== "object" || Array.isArray(event) || event.schema_version !== "v1" ||
      typeof event.event_id !== "string" || event.event_id.length === 0 ||
      typeof event.event_type !== "string" || event.event_type.length === 0) return null;

  for (const [header, field] of [["x-event-id", "event_id"], ["x-event-type", "event_type"]]) {
    if (headers[header] !== undefined && headers[header] !== event[field]) return null;
  }
  return event;
}

Download Node.js example

Go
package webhook

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"errors"
	"strconv"
	"time"
	"unicode/utf8"
)

// VerifyWebhook checks the original HTTP body bytes before parsing JSON.
// Optional nowSeconds is used only for deterministic tests.
func VerifyWebhook(secret, timestamp string, rawBody []byte, signature string, nowSeconds ...int64) bool {
	if secret == "" || len(rawBody) == 0 || len(signature) != 64 || len(nowSeconds) > 1 {
		return false
	}
	signedAt, err := strconv.ParseInt(timestamp, 10, 64)
	if err != nil || signedAt < 0 || strconv.FormatInt(signedAt, 10) != timestamp {
		return false
	}
	now := time.Now().Unix()
	if len(nowSeconds) == 1 {
		now = nowSeconds[0]
	}
	if now < 0 || now-signedAt < -300 || now-signedAt > 300 {
		return false
	}
	provided, err := hex.DecodeString(signature)
	if err != nil || len(provided) != sha256.Size {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(timestamp))
	mac.Write([]byte("."))
	mac.Write(rawBody)
	return hmac.Equal(mac.Sum(nil), provided)
}

// WebhookEvent contains only routing fields. Parse other fields from rawBody
// after ReadSignedWebhook succeeds; unknown fields are allowed.
type WebhookEvent struct {
	SchemaVersion string `json:"schema_version"`
	EventID       string `json:"event_id"`
	EventType     string `json:"event_type"`
}

// ReadSignedWebhook extracts event_id/type only from the verified body.
// X-Event-Id/Type are not signed separately; nonempty values must match the body.
func ReadSignedWebhook(secret, timestamp string, rawBody []byte, signature, eventIDHeader, eventTypeHeader string,
	nowSeconds ...int64) (*WebhookEvent, error) {
	if !VerifyWebhook(secret, timestamp, rawBody, signature, nowSeconds...) {
		return nil, errors.New("invalid webhook signature or timestamp")
	}
	var event WebhookEvent
	if !utf8.Valid(rawBody) || json.Unmarshal(rawBody, &event) != nil || event.SchemaVersion != "v1" ||
		event.EventID == "" || event.EventType == "" {
		return nil, errors.New("invalid webhook body")
	}
	if eventIDHeader != "" && eventIDHeader != event.EventID || eventTypeHeader != "" && eventTypeHeader != event.EventType {
		return nil, errors.New("webhook headers do not match the signed body")
	}
	return &event, nil
}

Download Go example

Webhook endpoints

Add a public HTTPS URL on port 443 for a specific project. URL credentials, fragments, redirects and non-public destinations are not allowed. Up to 20 endpoints are allowed per account. Each has a separate secret, returned only on first creation; store it on your server.

Creating the same URL for the same project and mode again returns 200 and the existing endpoint without its secret. A new endpoint returns 201. DELETE returns 200 with id and deleted: true, including a safe repeat. A key sees only its mode and allowed projects; delivery follows project settings.

SSE stream

SSE is for server-side integration and live display; it does not guarantee delivery or replay missed events. Use a server-side HTTP client with the Bearer header. Standard browser EventSource cannot send this header; do not put your API key in browser code or a query string.

Messages use event: payment and their own StreamEvent shape, not webhook v1 or REST Event. Comments begin with a colon; heartbeats arrive approximately every 20 seconds. retry: 5000 is a reconnection hint. After disconnecting, fetch available blockchain event history through events.

StreamEvent

JSON in SSE data; differs from webhook v1. Non-payment events omit payment and may include contract.

FieldTypeRequiredDescription
event_idstringYesOpaque identifier; keep it as a string.
minLength: 1
event_typestringYesEvent type; new types may be added.
chainstringYesNetwork code.
servicestringNoService, when known.
watch_idstringNoProject watch ID, when linked to a watch.
minLength: 1
occurred_atstringYesUTC date and time in RFC 3339.
date-time
paymentobject | nullNoPayment document, or null for a non-payment event. GET /events does not return contract/notice payloads.
sandboxbooleanNoTest event; omission means false.
project_idstringNoOpaque identifier; keep it as a string.
minLength: 1
project_namestringNoProject name.
urlstringNoLink to the Account event.
uri
contractobjectNo
modestringNolive or test.
live, test

Payment and invoice states

Blockchain payment state and order state are different. payment.pending is detection before sufficient confirmation; payment.confirmed means the network/project confirmation rule was reached; payment.rolled_back reports a reversal. Do not fulfill an order on pending, outgoing debit or simulated events.

InvoiceMeaning
pendingAwaiting payment
partialPart received; governed by the project's partial-payment policy
paidPayment accepted
underpaidUnderpayment needs a decision
overpaidOverpayment needs a decision under the applicable policy
latePayment after expiry needs a decision
expiredPayment window expired
canceledInvoice canceled; the record remains readable

needs_decision is present for underpaid, overpaid and late. Resolve these in Account. A reorg and re-inclusion can produce new transitions and a new payment.revision; confirmed is not an unconditional guarantee against future changes.

Errors and safe retries

application/json
{"error":{"code":"forbidden","message":"this API key is read-only"}}

Use HTTP status and error.code for logic, and message for diagnosis. Successful lists have data; a single object is returned directly. Health uses its own status/version schema, including on 503. Do not depend on exact message wording.

HTTPAction
400Correct JSON, formats and parameters; do not retry unchanged
401Check key, expiry, pause and revocation
403Check scopes, read/write, project, service, IP and account verification
404Check ID, key mode and access; restrictions may hide the resource
402Monitoring watch limit; check your plan
409Conflict, inactive service, occupied pool or limit; inspect code
429Respect Retry-After; reduce the account's combined request rate
500 / 503Retry with bounded backoff; invoice creation only with the original Idempotency-Key

A timeout does not mean the operation failed to execute. Do not change an invoice's operation key on retry. For methods without duplicate protection, read the state first; do not assume every POST is idempotent.

Networks and limits

Use chains on your selected API host for its network, asset, capability and confirmation catalog. Being listed in the general catalog does not guarantee a network is enabled in that environment or supports every operation. Check service quotas and budget in Account; prices are on the Pricing page.

The account's authenticated REST quota is 10 requests/s without a paid service, 50 requests/s with a paid service; short burst capacity is 20/100. Live keys share this quota. Sandbox has a separate quota of 2 requests/s with burst capacity 4. Exceeding it returns 429 with Retry-After. Service quotas and API rate limits are separate restrictions.

Service pricing and quotas

API versions

This reference describes v1 in release 1.1.3 5; updated 2026-11-17. Before using new capabilities, check the deployed release through GET /v1/health. The documentation version does not confirm deployment.

Public APIContract
https://api.cryptanio.com/v1

Use /v1 for stable integrations. An unversioned path selects the environment's current stable contract; an unknown /vN returns 404. X-API-Version identifies the contract; X-Server-Version and health.version identify the product release, not a different API contract.

Download OpenAPI 3.1

API changes

Release 1.1.3 5 adds Sandbox v1 for addresses, Invoice API, events, webhooks and notifications. Verify sandbox_v1 in health before use. Pay and subscriptions are not included in Sandbox.

Within v1, clients should tolerate additional response fields. Accepting an unknown event type does not mean fulfilling an order or crediting a payment. Check change availability against the selected environment's version before use.