Accounts - Nuvion

Accounts hold balances for an entity. Each account is denominated in a single currency. An entity must have approved status before accounts can be created for them.

The Account object

string

Unique account identifier.

string

The ID of the entity this account belongs to.

string

Account type. One of checking, debit, operational, or safeguard.

string

ISO 4217 currency code. Fiat account: USD, GBP, EUR Stablecoin account: USC, RLD, UST

string

Human-readable label for the account.

string

Nuvion internal bank account number used for routing. Treat this as read-only.

object

Current balance state of the account. All amounts are in the smallest currency unit (e.g. cents for USD).

Show balance fields

number

Spendable funds — excludes amounts pending settlement. Use this value when checking whether an entity has sufficient funds.

number

Total balance including amounts pending settlement.

object

Set of key-value pairs for storing additional platform-defined data.

number

Unix timestamp in milliseconds when the account was created.

number

Unix timestamp in milliseconds when the account was last updated.

Example

{
  "id": "acc_01HXYZ5678EFGH",
  "entity_id": "ent_01HXYZ1234ABCD",
  "type": "checking",
  "currency": "USD",
  "display_name": "Main USD Account",
  "nuvion_ban": "NVN0000012345",
  "balance": {
    "available": 150000,
    "current": 150000
  },
  "meta": {},
  "created": 1735725600000,
  "updated": 1735725600000
}

Always use balance.available when checking if an entity has sufficient funds. balance.current includes amounts pending settlement that are not yet spendable.

Create an account

Creates a new account for an approved entity. The entity must have status: "approved" before accounts can be opened.

curl -X POST https://api.nuvion.dev/accounts \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "01HXYZ1234ABCD",
    "type": "checking",
    "currency": "USD",
    "display_name": "Main USD Account"
  }'

To create a stablecoin account, pass one of USC, UST, RLD as your currency.

Request parameters

string

required

The ID of the entity to open this account for. The entity must have status: "approved".

string

required

Account type. One of checking, debit, operational, or safeguard.

string

ISO 4217 currency code. Fiat account: USD, GBP, EUR Stablecoin account: USC, RLD, UST

string

required

Human-readable label for the account. Maximum 100 characters.

object

Key-value metadata to attach to the account. Values must be strings.

Response

Returns the created account object. The balance is 0 for both available and current at creation.

Response

{
  "id": "01HXYZ5678EFGH",
  "entity_id": "01HXYZ1234ABCD",
  "type": "checking",
  "currency": "USD",
  "display_name": "Main USD Account",
  "nuvion_ban": "NVN0000012345",
  "balance": {
    "available": 0,
    "current": 0
  },
  "meta": {},
  "created": 1735725600000,
  "updated": 1735725600000
}

The first account created for an entity automatically becomes their default account.

List accounts

Returns a paginated list of accounts. Filter by entity, currency, or account type.

curl "https://api.nuvion.dev/accounts?entity_id=01HXYZ1234ABCD&limit=20" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Request parameters

string

Filter accounts by entity ID. Required when authenticating with an API key.

string

Filter by ISO 4217 currency code (e.g. USD).

string

Filter by account type. One of checking, debit, operational, or safeguard.

integer

Number of results to return. Between 1 and 100. Defaults to 20.

string

Pagination cursor from a previous response. Omit for the first page.

Response

Returns a paginated list of account objects.

Response

{
  "data": [
    {
      "id": "01HXYZ5678EFGH",
      "entity_id": "01HXYZ1234ABCD",
      "type": "checking",
      "currency": "USD",
      "display_name": "Main USD Account",
      "nuvion_ban": "NVN0000012345",
      "balance": {
        "available": 150000,
        "current": 150000
      },
      "meta": {},
      "created": 1735725600000,
      "updated": 1735725600000
    }
  ],
  "meta": {
    "pagination": {
      "has_next": true,
      "has_previous": false,
      "next_cursor": "cursor_abc123",
      "previous_cursor": null,
      "total_count": 42
    }
  }
}

Get an account

Retrieves an existing account by ID.

curl "https://api.nuvion.dev/accounts/01HXYZ5678EFGH" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Request parameters

string

required

The ID of the account to retrieve.

string

The ID of the entity that owns the account. Required when authenticating with an API key.

Response

Returns the account object.

Response

{
  "id": "01HXYZ5678EFGH",
  "entity_id": "01HXYZ1234ABCD",
  "type": "checking",
  "currency": "USD",
  "display_name": "Main USD Account",
  "nuvion_ban": "NVN0000012345",
  "balance": {
    "available": 150000,
    "current": 162500
  },
  "meta": {},
  "created": 1735725600000,
  "updated": 1735812000000
}

​The Account object

​Create an account

​Request parameters

​Response

​List accounts

​Request parameters

​Response

​Get an account

​Request parameters

​Response

The Account object

Create an account

Request parameters

Response

List accounts

Request parameters

Response

Get an account

Request parameters

Response