Ledger accounts API

API endpoints

Ledger accounts API

Ledger accounts group wallets and accounting activity under a client-defined business identity such as a customer, merchant, treasury, or settlement account.

Operations

MethodPathScopeDescription
GET/api/v1/ledger/accountsaccounts:readList accounts with cursor pagination
POST/api/v1/ledger/accountswallets:createCreate an account
GET/api/v1/ledger/accounts/{accountId}accounts:readRead one account
GET/api/v1/ledger/accounts/{accountId}/walletswallets:readList wallets assigned to the account
GET/api/v1/ledger/accounts/{accountId}/balanceswallets:readList account balance projections
GET/api/v1/ledger/accounts/{accountId}/transactionstransactions:readList account transactions

Create an account

POST /api/v1/ledger/accounts

json
{
  "name": "Treasury",
  "externalId": "customer-4821",
  "metadata": {
"region": "EU"
  }
}

name is required. externalId is optional, must contain 1–128 characters when present, and should map the account to your own stable identifier. metadata is optional and accepts an object.

This operation requires X-Api-Body-Hash, but the current Swagger does not require X-Idempotency-Key or provide fingerprint replay handling. Use a unique externalId when you need a business-level duplicate guard.

List and search accounts

GET /api/v1/ledger/accounts accepts cursor, limit, search, and externalId. The response contains items and nextCursor.

Account detail

Account responses include id, orgId, name, nullable externalId, nullable metadata, createdAt, and updatedAt. The detail endpoint also returns account-level information defined by the current schema.

Conflicts and limits

  • 409 ACCOUNT_EXTERNAL_ID_CONFLICT — the external identifier already exists.
  • 422 ACCOUNT_METADATA_TOO_LARGE — metadata exceeds 16 KiB.
  • 404 RESOURCE_NOT_FOUND — the requested account is unavailable to the organization.