The Citadel API is your backend’s door to custody. Keys never leave your side: Citadel builds, routes, broadcasts, and indexes transactions, while your own policy engine and signer decide what gets signed. Base URL: https://api.citadel.example/api/v1. JSON in, JSON out.

Two doors for moving money

Transactions — the direct door

POST /transactions with actions[]: one on-chain transaction, exactly as you describe it.

Events — the workflow door

POST /events/{name} with a network and inputs: the workflows you drew in the console for that network decide the rest.

The surface

The lists run newest first and page with a cursor: see Lists and pagination.

Amounts

Every amount is an integer string in the asset’s smallest unit: "50000000" is 50 USDT on TRON (6 decimals). GET /assets lists the decimals of every asset Citadel credits, and GET /wallets/{reference}/balance returns them next to each balance.

Networks

A wallet lives on one network: mainnet or testnet. One organization works on every network your installation serves. There is no default network: every request about data that lives on a network names it. GET /networks lists the networks your installation serves; it takes no network. Neither do GET /vaults (a vault holds wallets on every network), GET /me, GET /policy and the policy drafts (one document rules every network; see Address book), GET /billing/balance (one balance for the organization), and /webhook_endpoints and /webhook_deliveries (an endpoint hears every network). A list never spans networks: there is no “all networks”, so a merchant on two networks reads each one. GET /balances is no exception: each network keeps its own books. A reference names a wallet within a network. When a request names a wallet by its id, the wallet must live on the network the request names. Citadel checks network before it creates, reserves or asks a chain node anything, so a refused request leaves nothing behind: POST /events/{name} starts only the workflows of the network it names. A workflow on another network never hears the event. The wallet and asset inputs are checked on the same network. GET /transactions/{id}, POST /transactions/{id}/cancel, POST /transactions/{id}/speedup, GET /runs/{id}, POST /runs/{id}/cancel and GET /reports/{id} take no network: the id is enough. Their responses carry the network the transaction, the run or the report is on; a report’s file is fetched by the same id. The webhook delivery log and its retries take none either: a webhook endpoint hears every network.

Chains

chain is a family: tron, evm, solana or ton. A wallet has one, and on EVM one address serves every L1/L2 of its network. Where money actually landed is the chain instance: a transfer carries it as instance, and GET /networks lists the instances of each network.