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.
- Verify your account. For Live, activate the service you need in My services; Sandbox testing requires no paid service.
- Create an API key with the minimum permissions and keep it on your server.
- 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.
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.
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
Monitoring watches
Events
Invoices
Webhook
API health
Networks
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.
| Scope | Purpose |
|---|---|
watches | Monitoring |
events | Events and payments |
invoices | Payments invoices |
webhooks | Webhook endpoints |
stream | SSE |
simulation | Simulate 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.
- 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.
- In Addresses, add a test address. In Invoices, create a test invoice with a network and amount.
- 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.
- 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.
- 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.
#!/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.
| Language | Requirements | File |
|---|---|---|
| Node.js | Node.js 18+ | cryptanio.mjs |
| Python | Python 3.10+ | cryptanio.py |
| PHP | PHP 8.1+ / cURL | Cryptanio.php |
| Go | Go 1.22+ | cryptanio.go |
| Rust | Rust 2021 / reqwest 0.12 / serde_json 1 | cryptanio.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.
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.
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.
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.
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
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
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.
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.
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.
[dependencies]
reqwest = { version = "=0.12.24", default-features = false, features = ["blocking", "json", "rustls-tls"] }
serde_json = "=1.0.145"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.
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 method | HTTP |
|---|---|
createWatch | POST /v1/watches |
listWatches | GET /v1/watches |
getWatch | GET /v1/watches/{id} |
deleteWatch | DELETE /v1/watches/{id} |
listEvents | GET /v1/events |
listPayments | GET /v1/payments |
createInvoice | POST /v1/invoices |
listInvoices | GET /v1/invoices |
getInvoice | GET /v1/invoices/{id} |
cancelInvoice | POST /v1/invoices/{id}/cancel |
createEndpoint | POST /v1/endpoints |
listEndpoints | GET /v1/endpoints |
deleteEndpoint | DELETE /v1/endpoints/{id} |
streamEvents | GET /v1/stream |
getHealth | GET /v1/health |
listChains | GET /v1/chains |
simulate | POST /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 / error | Fields |
|---|---|
| Node.js / Python: ApiError | status, code, message, retry_after |
| PHP: CryptanioError | status, apiCode, getMessage(), retryAfter |
| Go: *APIError | Status, Code, Message, RetryAfter |
| Rust: ApiError | status: 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.
#!/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.
#!/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
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Customer identifier in your system. maxLength: 120 |
Product
| Field | Type | Required | Description |
|---|---|---|---|
id | string | No | Product identifier in your system. maxLength: 120 |
name | string | No | Product name. maxLength: 200 |
quantity | integer | No | Quantity. minimum: 1; maximum: 1000000 |
Payer
| Field | Type | Required | Description |
|---|---|---|---|
comment | string | Yes | Payer 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
| Field | Type | Required | Description |
|---|---|---|---|
event_id | string | Yes | Opaque identifier; keep it as a string. minLength: 1 |
event_type | string | Yes | Event type; new types may be added. |
chain | string | Yes | Network code. |
service | string | No | Service, when known. |
watch_id | string | No | Project watch ID, when linked to a watch. minLength: 1 |
occurred_at | string | Yes | UTC date and time in RFC 3339.date-time |
reverted_at | string | No | UTC time when a chain reorganization reverted the contract event.date-time |
payment | object | null | Yes | Payment document, or null for a non-payment event. GET /events does not return contract/notice payloads. |
sandbox | boolean | No | Test event; omission means false. |
EventPayment
REST/SSE payment document. Fields depend on the event and network; not the normalized webhook v1 shape.
| Field | Type | Required | Description |
|---|---|---|---|
tx_id | string | No | Transaction identifier. |
index | integer | No | Transfer index within the transaction. minimum: 0 |
height | integer | No | Block height, when known. minimum: 0 |
address | string | No | Observed address. |
asset | string | No | REST/SSE asset: string identifier, not the webhook asset object. |
amount_raw | string | No | Integer smallest-unit amount as a string. pattern: ^[0-9]+$ |
amount | string | No | Exact decimal amount as a string; do not use floating point. pattern: ^[0-9]+(?:\.[0-9]+)?$ |
decimals | integer | No | Decimal places. minimum: 0 |
confirmations | integer | No | Confirmations. minimum: 0 |
revision | integer | No | Transfer state revision. minimum: 0 |
direction | string | No | Direction relative to the observed address.in, out |
simulated | boolean | No | Simulated event. |
late | boolean | No | Late detected transfer. |
block_hash | string | No | Block hash. |
match_key | string | No | Match identifier when used by the network. |
meta | object | No | |
invoice | object | No | |
customer | object | No | |
product | object | No | |
payer | object | No | |
metadata | object | No |
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.
| Family | Body |
|---|---|
| payment.pending / confirmed / rolled_back | Incoming payment |
| debit.pending / confirmed / rolled_back | Outgoing payment |
| contract.approval / owner_added / owner_removed / threshold_changed / permissions_changed | contract |
| contract.rolled_back | contract |
| asset.unexpected | contract; the asset is not credited as accepted payment |
| account.notice / account.notification / treasury.alarm / subscription.notice | notice.subject, notice.text |
| webhook.test | Control 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.
| Header | Meaning |
|---|---|
| X-Timestamp | Unix seconds at signing time |
| X-Signature | hex HMAC-SHA256(timestamp + '.' + raw body) |
| X-Event-Id / X-Event-Type | Compare with the signed body |
| X-Attempt | Attempt 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.
{
"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.
| Field | Type | Required | Description |
|---|---|---|---|
schema_version | string | Yes | Webhook payload version.v1 |
event_id | string | Yes | Event ID: unchanged for delivery retries. Different states can have different event_id values. minLength: 1 |
event_type | string | Yes | Type in the signed body; use it after verifying the signature. New types may be added. |
occurred_at | string | Yes | UTC date and time in RFC 3339.date-time |
project_id | string | Yes | Opaque identifier; keep it as a string. minLength: 1 |
service | string | No | Project service, where applicable. |
mode | string | Yes | Event mode.live, test |
sandbox | boolean | Yes | Explicit simulation flag. |
payment | object | No | |
contract | object | No | |
invoice | object | No | |
customer | object | No | |
product | object | No | |
payer | object | No | |
metadata | object | No | |
notice | object | No |
WebhookPayment
| Field | Type | Required | Description |
|---|---|---|---|
chain | string | Yes | Network code. |
direction | string | Yes | Incoming payment: in; outgoing debit: out.in, out |
asset | object | Yes | |
address | string | Yes | Observed address. |
tx_id | string | Yes | Transaction ID. |
index | integer | Yes | Transfer index; do not assume 0 for any network. minimum: 0 |
height | integer | No | Block height if known. minimum: 0 |
block_hash | string | No | Block hash if known. |
match_key | string | No | Network match identifier, when applicable. |
amount | string | Yes | Exact decimal amount as a string; do not use floating point. pattern: ^[0-9]+(?:\.[0-9]+)?$ |
amount_raw | string | Yes | Integer smallest-unit amount as a string. pattern: ^[0-9]+$ |
decimals | integer | Yes | Decimal places. minimum: 0 |
confirmations | integer | Yes | Confirmations. minimum: 0 |
revision | integer | Yes | Transfer state revision. Do not collapse distinct event_id values by transaction identity. minimum: 0 |
late | boolean | No | Late detected transfer; not the same as invoice status late. |
simulated | boolean | No | Simulated transfer. |
valuation | object | No |
WebhookAsset
| Field | Type | Required | Description |
|---|---|---|---|
symbol | string | No | Symbol if known; not sufficient to establish token identity. |
standard | string | No | Token standard if known. |
contract | string | No | Token contract in its network, where applicable. |
identifier | string | No | Other network-specific token identifier. |
WebhookContract
| Field | Type | Required | Description |
|---|---|---|---|
chain | string | Yes | Network code. |
address | string | Yes | Observed address or contract. |
tx_id | string | Yes | Transaction ID. |
index | integer | Yes | Event index. minimum: 0 |
height | integer | No | Block height. minimum: 0 |
block_hash | string | No | Block hash. |
kind | string | No | Change kind. |
original_event_id | string | No | Public identifier of the original event reverted by contract.rolled_back. minLength: 1 |
asset | string | No | Affected asset identifier, if known. |
detail | object | No | |
simulated | boolean | No | Simulated event. |
WebhookInvoice
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Opaque identifier; keep it as a string. minLength: 1 |
reference | string | No | Order reference. |
status | string | No | pending 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 |
currency | string | No | Order quote currency. |
amount | string | No | Exact decimal amount as a string; do not use floating point. pattern: ^[0-9]+(?:\.[0-9]+)?$ |
Notice
| Field | Type | Required | Description |
|---|---|---|---|
subject | string | Yes | Notice subject. |
text | string | Yes | Notice text. |
Valuation
| Field | Type | Required | Description |
|---|---|---|---|
currency | string | Yes | Valuation currency, such as USD. |
amount | string | Yes | Exact decimal amount as a string; do not use floating point. pattern: ^[0-9]+(?:\.[0-9]+)?$ |
rate | string | Yes | Asset exchange rate as a decimal string. pattern: ^[0-9]+(?:\.[0-9]+)?$ |
rate_at | string | Yes | UTC date and time in RFC 3339.date-time |
provider | string | No | Quote 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.
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;
}
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
}
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.
| Field | Type | Required | Description |
|---|---|---|---|
event_id | string | Yes | Opaque identifier; keep it as a string. minLength: 1 |
event_type | string | Yes | Event type; new types may be added. |
chain | string | Yes | Network code. |
service | string | No | Service, when known. |
watch_id | string | No | Project watch ID, when linked to a watch. minLength: 1 |
occurred_at | string | Yes | UTC date and time in RFC 3339.date-time |
payment | object | null | No | Payment document, or null for a non-payment event. GET /events does not return contract/notice payloads. |
sandbox | boolean | No | Test event; omission means false. |
project_id | string | No | Opaque identifier; keep it as a string. minLength: 1 |
project_name | string | No | Project name. |
url | string | No | Link to the Account event.uri |
contract | object | No | |
mode | string | No | live 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.
| Invoice | Meaning |
|---|---|
| pending | Awaiting payment |
| partial | Part received; governed by the project's partial-payment policy |
| paid | Payment accepted |
| underpaid | Underpayment needs a decision |
| overpaid | Overpayment needs a decision under the applicable policy |
| late | Payment after expiry needs a decision |
| expired | Payment window expired |
| canceled | Invoice 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
{"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.
| HTTP | Action |
|---|---|
| 400 | Correct JSON, formats and parameters; do not retry unchanged |
| 401 | Check key, expiry, pause and revocation |
| 403 | Check scopes, read/write, project, service, IP and account verification |
| 404 | Check ID, key mode and access; restrictions may hide the resource |
| 402 | Monitoring watch limit; check your plan |
| 409 | Conflict, inactive service, occupied pool or limit; inspect code |
| 429 | Respect Retry-After; reduce the account's combined request rate |
| 500 / 503 | Retry 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.
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 API | Contract |
|---|---|
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.
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.