Wallets API

API endpoints

Wallets API

Wallet endpoints create and retrieve organization-scoped blockchain addresses. A wallet belongs to one ledger account and one chain.

Operations

MethodPathScopeDescription
POST/api/v1/walletswallets:createCreate a wallet address
GET/api/v1/walletswallets:readList organization wallets
GET/api/v1/wallets/{walletId}wallets:readRead one wallet

Create a wallet

POST /api/v1/wallets

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

json
{
  "chain": "tron:nile",
  "accountId": "ledger-account-id"
}

The current schema lists tron:mainnet and tron:nile as allowed chain values. Confirm current support through GET /api/v1/assets rather than assuming that every documented enum is enabled for your organization.

The 201 response contains:

  • id
  • chain
  • accountId and accountName
  • address
  • status: ACTIVE, DISABLED, or ARCHIVED
  • createdAt and updatedAt

List wallets

GET /api/v1/wallets supports:

  • cursor pagination: cursor, limit;
  • status and network filters: status, chain;
  • address search: addressContains;
  • time filters: createdFrom, createdTo;
  • account filter: accountId;
  • ordering: sortBy, sortOrder.

Safe retries

Retry the same logical create operation with the same X-Idempotency-Key and identical body. A reused key with a different request produces an idempotency conflict.

Errors

Wallet creation may return IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_INVALID, IDEMPOTENCY_CONFLICT, RESOURCE_NOT_FOUND, UNSUPPORTED_CHAIN, PLAN_LIMIT_REACHED, or UPSTREAM_UNAVAILABLE.