API endpoints
Transactions API
Transaction endpoints create outgoing withdrawals and expose ledger-backed deposit, withdrawal, internal-transfer, and adjustment records.
Operations
| Method | Path | Scope | Description |
|---|---|---|---|
POST | /api/v1/transactions | withdrawals:create | Create an outgoing transaction |
GET | /api/v1/transactions | transactions:read | List transactions |
GET | /api/v1/transactions/{id} | transactions:read | Read transaction detail |
Create a withdrawal
POST /api/v1/transactions
Required headers include X-Idempotency-Key and X-Api-Body-Hash.
{
"clientReference": "withdrawal-4821",
"walletId": "wallet-id",
"asset": "USDT",
"toAddress": "destination-address",
"amountAtomic": "1000000"
}walletId, asset, toAddress, and amountAtomic are required. clientReference is optional and accepts 1–128 characters. chainParams may carry chain-specific parameters defined by the current schema.
Always send amountAtomic as a base-10 string in the asset's smallest unit. Do not send a display decimal in this field.
Transaction detail
Responses identify:
- account and wallet;
type:DEPOSIT,WITHDRAWAL,INTERNAL_TRANSFER, orADJUSTMENT;status:PENDING,CONFIRMED,FAILED, orFAILED_ON_CHAIN;- atomic, display, signed amount, and direction;
balanceEffects;- nullable
onChainDetails; networkFeeSummary;- client and billing references;
- creation and update timestamps.
List filters
GET /api/v1/transactions accepts cursor, limit, accountId, walletId, clientReference, chain, asset, status, type, createdFrom, and createdTo.
Safe retries and conflicts
Retry an unknown outcome with the same idempotency key and identical request. A changed request with the same key returns 409 IDEMPOTENCY_CONFLICT. A duplicate clientReference may return 409 CLIENT_REFERENCE_CONFLICT.
Domain errors
Validation and domain failures include UNSUPPORTED_CHAIN, UNSUPPORTED_ASSET, INVALID_ADDRESS, INVALID_FEE_LIMIT, INSUFFICIENT_AVAILABLE_BALANCE, and WITHDRAWALS_BLOCKED.