Transactions API

API endpoints

Transactions API

Transaction endpoints create outgoing withdrawals and expose ledger-backed deposit, withdrawal, internal-transfer, and adjustment records.

Operations

MethodPathScopeDescription
POST/api/v1/transactionswithdrawals:createCreate an outgoing transaction
GET/api/v1/transactionstransactions:readList transactions
GET/api/v1/transactions/{id}transactions:readRead transaction detail

Create a withdrawal

POST /api/v1/transactions

Required headers include X-Idempotency-Key and X-Api-Body-Hash.

json
{
  "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, or ADJUSTMENT;
  • status: PENDING, CONFIRMED, FAILED, or FAILED_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.