Source: https://cryptanio.com/docs.html
Contract / release / updated: v1 / 1.1.3 5 / 2026-11-17

# API documentation

Connect Cryptanio to your application.

Contract v1 / 1.1.3 5 / 2026-11-17

[Markdown](https://cryptanio.com/docs.md) [OpenAPI](https://cryptanio.com/openapi.json) [For AI agents](https://cryptanio.com/docs/llms.txt)

## 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](https://account.cryptanio.com/finance/services); Sandbox testing requires no paid service.
- Create an [API key](https://account.cryptanio.com/api-keys) with the minimum permissions and keep it on your server.
- Choose your task: [monitor an address](https://cryptanio.com/docs.html#quickstart), [create an invoice](https://cryptanio.com/docs.html#invoices) or [receive events](https://cryptanio.com/docs.html#webhooks).

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](https://cryptanio.com/docs.html#sandbox)

## 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.



### Agent instructions

```text
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

### Monitoring watches

[POST /v1/watches Create a Monitoring watch](https://cryptanio.com/docs/reference/create-watch/) [GET /v1/watches List Monitoring watches](https://cryptanio.com/docs/reference/list-watches/) [GET /v1/watches/{id} Get a Monitoring watch](https://cryptanio.com/docs/reference/get-watch/) [DELETE /v1/watches/{id} Delete a Monitoring watch](https://cryptanio.com/docs/reference/delete-watch/)

### Events

[GET /v1/events List events](https://cryptanio.com/docs/reference/list-events/)

### Payments

[GET /v1/payments List Payments events](https://cryptanio.com/docs/reference/list-payments/)

### Invoices

[POST /v1/invoices Create an invoice](https://cryptanio.com/docs/reference/create-invoice/) [GET /v1/invoices List invoices](https://cryptanio.com/docs/reference/list-invoices/) [GET /v1/invoices/{id} Get an invoice](https://cryptanio.com/docs/reference/get-invoice/) [POST /v1/invoices/{id}/cancel Cancel an invoice](https://cryptanio.com/docs/reference/cancel-invoice/)

### Webhook

[POST /v1/endpoints Create a webhook endpoint](https://cryptanio.com/docs/reference/create-endpoint/) [GET /v1/endpoints List webhook endpoints](https://cryptanio.com/docs/reference/list-endpoints/) [DELETE /v1/endpoints/{id} Delete a webhook endpoint](https://cryptanio.com/docs/reference/delete-endpoint/)

### SSE

[GET /v1/stream Stream events](https://cryptanio.com/docs/reference/stream-events/)

### API health

[GET /v1/health Get API health](https://cryptanio.com/docs/reference/get-health/)

### Networks

[GET /v1/chains List networks](https://cryptanio.com/docs/reference/list-chains/)

### Sandbox

[POST /v1/simulate Simulate a Sandbox payment](https://cryptanio.com/docs/reference/simulate/)

## Authentication

Send `Authorization: Bearer <API_KEY>` from your server. Create a Live or Sandbox key in [Account → API keys](https://account.cryptanio.com/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](https://cryptanio.com/docs.html#errors).

## 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](https://account.cryptanio.com/payments?environment=sandbox) 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.



### Shell / cURL

```bash
#!/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.

[GET /v1/events List events](https://cryptanio.com/docs/reference/list-events/) [POST /v1/invoices Create an invoice](https://cryptanio.com/docs/reference/create-invoice/) [GET /v1/invoices List invoices](https://cryptanio.com/docs/reference/list-invoices/) [POST /v1/endpoints Create a webhook endpoint](https://cryptanio.com/docs/reference/create-endpoint/) [GET /v1/endpoints List webhook endpoints](https://cryptanio.com/docs/reference/list-endpoints/) [POST /v1/simulate Simulate a Sandbox payment](https://cryptanio.com/docs/reference/simulate/)

## 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](https://cryptanio.com/files/sdk/node/cryptanio.mjs) |
| Python | Python 3.10+ | [cryptanio.py](https://cryptanio.com/files/sdk/python/cryptanio.py) |
| PHP | PHP 8.1+ / cURL | [Cryptanio.php](https://cryptanio.com/files/sdk/php/Cryptanio.php) |
| Go | Go 1.22+ | [cryptanio.go](https://cryptanio.com/files/sdk/go/cryptanio.go) |
| Rust | Rust 2021 / reqwest 0.12 / serde_json 1 | [cryptanio.rs](https://cryptanio.com/files/sdk/rust/cryptanio.rs) |

The files share release `1.1.3 5`. The [manifest](https://cryptanio.com/files/sdk/manifest.json) 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

```javascript
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

```javascript
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

```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

```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
<?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
<?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

```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

```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

```toml
[dependencies]
reqwest = { version = "=0.12.24", default-features = false, features = ["blocking", "json", "rustls-tls"] }
serde_json = "=1.0.145"
```



 

### Rust

```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

```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](https://cryptanio.com/docs.html#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](https://cryptanio.com/docs/reference/create-watch/) |
| `listWatches` | [GET /v1/watches](https://cryptanio.com/docs/reference/list-watches/) |
| `getWatch` | [GET /v1/watches/{id}](https://cryptanio.com/docs/reference/get-watch/) |
| `deleteWatch` | [DELETE /v1/watches/{id}](https://cryptanio.com/docs/reference/delete-watch/) |
| `listEvents` | [GET /v1/events](https://cryptanio.com/docs/reference/list-events/) |
| `listPayments` | [GET /v1/payments](https://cryptanio.com/docs/reference/list-payments/) |
| `createInvoice` | [POST /v1/invoices](https://cryptanio.com/docs/reference/create-invoice/) |
| `listInvoices` | [GET /v1/invoices](https://cryptanio.com/docs/reference/list-invoices/) |
| `getInvoice` | [GET /v1/invoices/{id}](https://cryptanio.com/docs/reference/get-invoice/) |
| `cancelInvoice` | [POST /v1/invoices/{id}/cancel](https://cryptanio.com/docs/reference/cancel-invoice/) |
| `createEndpoint` | [POST /v1/endpoints](https://cryptanio.com/docs/reference/create-endpoint/) |
| `listEndpoints` | [GET /v1/endpoints](https://cryptanio.com/docs/reference/list-endpoints/) |
| `deleteEndpoint` | [DELETE /v1/endpoints/{id}](https://cryptanio.com/docs/reference/delete-endpoint/) |
| `streamEvents` | [GET /v1/stream](https://cryptanio.com/docs/reference/stream-events/) |
| `getHealth` | [GET /v1/health](https://cryptanio.com/docs/reference/get-health/) |
| `listChains` | [GET /v1/chains](https://cryptanio.com/docs/reference/list-chains/) |
| `simulate` | [POST /v1/simulate](https://cryptanio.com/docs/reference/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](https://cryptanio.com/docs.html#stream).

## 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

```bash
#!/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](https://cryptanio.com/docs/reference/create-watch/).

## 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

```bash
#!/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.

[POST /v1/invoices Create an invoice](https://cryptanio.com/docs/reference/create-invoice/) [GET /v1/invoices List invoices](https://cryptanio.com/docs/reference/list-invoices/) [GET /v1/invoices/{id} Get an invoice](https://cryptanio.com/docs/reference/get-invoice/) [POST /v1/invoices/{id}/cancel Cancel an invoice](https://cryptanio.com/docs/reference/cancel-invoice/)

### `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.

[POST /v1/watches Create a Monitoring watch](https://cryptanio.com/docs/reference/create-watch/) [GET /v1/watches List Monitoring watches](https://cryptanio.com/docs/reference/list-watches/) [GET /v1/watches/{id} Get a Monitoring watch](https://cryptanio.com/docs/reference/get-watch/) [DELETE /v1/watches/{id} Delete a Monitoring watch](https://cryptanio.com/docs/reference/delete-watch/)

## 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.

[GET /v1/events List events](https://cryptanio.com/docs/reference/list-events/) [GET /v1/payments List Payments events](https://cryptanio.com/docs/reference/list-payments/)

### `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](https://cryptanio.com/openapi.json).

| 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.



### Webhook shape example (illustrative)

```json
{
  "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.



### Node.js

```javascript
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](https://cryptanio.com/files/examples/webhook-node.mjs)



### Go

```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](https://cryptanio.com/files/examples/webhook-go.go)

## 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.

[POST /v1/endpoints Create a webhook endpoint](https://cryptanio.com/docs/reference/create-endpoint/) [GET /v1/endpoints List webhook endpoints](https://cryptanio.com/docs/reference/list-endpoints/) [DELETE /v1/endpoints/{id} Delete a webhook endpoint](https://cryptanio.com/docs/reference/delete-endpoint/)

## 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.

[GET /v1/stream Stream events](https://cryptanio.com/docs/reference/stream-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



### application/json

```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.

| 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.

[Service pricing and quotas](https://cryptanio.com/pricing/)

[GET /v1/health Get API health](https://cryptanio.com/docs/reference/get-health/) [GET /v1/chains List networks](https://cryptanio.com/docs/reference/list-chains/)

## 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.

[Download OpenAPI 3.1](https://cryptanio.com/openapi.json)

## 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.
