Skip to main content
Endpoints related to distribution accounts (the Stellar accounts a tenant sends funds from). A tenant starts with a single account, created when the tenant is provisioned, which is marked as the default. Tenants using the DISTRIBUTION_ACCOUNT.STELLAR.DB_VAULT account type can hold up to 20, and Owners can add more at any time. Access to an account is granted per user and is separate from the user’s role: both are required to act on an account. API keys need the read:distribution_wallets or write:distribution_wallets permission, and the Owner-only operations additionally require that the key was created by an Owner, so permissions alone are not sufficient. Accounts are archived rather than deleted, so past disbursements and payments keep pointing at the account that sent them.

List Distribution Accounts

Lists the distribution accounts the caller has access to. Owners see every account in the tenant. Archived accounts are included so historical records stay resolvable.

Create Distribution Account

Creates and provisions a new distribution account. The account is generated, funded, and given its own signing key, isolated from the tenant's other accounts. Owner only. Available only to tenants using the `DISTRIBUTION_ACCOUNT.STELLAR.DB_VAULT` account type, up to a maximum of 20 accounts.

Get Total Balance

Returns the combined live balances of every distribution account the caller has access to, summed per asset. This is the Total Balance shown on the dashboard.

Get Distribution Account

Retrieves a single distribution account. Owner only.

Get Account Balance

Returns one distribution account's live on-chain balances. An account the caller has no access to is indistinguishable from one that does not exist; both return 404.

Get Account Capabilities

Reports what the caller may do on one distribution account, combining their tenant-wide role with the role they hold on that account. Owners can also ask what a third party could do, by passing `user_id`. Add `role` alongside it to ask hypothetically what that user could do if granted that role. `role` cannot be sent on its own and returns 400 without `user_id`. This backs the dashboard's access-granting picker, which warns when a grant would be inert because the user's tenant-wide role already excludes the action.

List Account Access

Lists the users who have access to a distribution account, and the role each holds. Owner only.

Grant Account Access

Grants a user a role on a distribution account. Owner only. The Owner role cannot be granted here, since it is always tenant-wide. An archived account takes no new grants.

Revoke Account Access

Revokes a user's access to a distribution account. Owner only. The grant history is preserved in the account's audit trail.

Get Account Access History

Returns the grants and revokes recorded against a distribution account, newest first, from an append-only audit table. Owner only. Archived accounts remain queryable. Capped at the 100 most recent entries, with no pagination, so older entries are not returned.

Archive Distribution Account

Archives a distribution account. Owner only. Archived accounts accept no new disbursements but keep serving reads, so past records stay resolvable. Two accounts cannot be archived and return 400: the tenant's default, which requires promoting another account first, and the last remaining active account.

Promote Account To Default

Makes this the tenant's default distribution account. Owner only. The previous default becomes an ordinary active account. Only an active account can be promoted; archived or still-provisioning accounts return 400.