> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuvion.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Accounts

> Create and retrieve currency-denominated balance containers for your entities.

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

<ResponseField name="id" type="string">
  Unique account identifier.
</ResponseField>

<ResponseField name="entity_id" type="string">
  The ID of the entity this account belongs to.
</ResponseField>

<ResponseField name="type" type="string">
  Account type. One of `checking`, `debit`, `operational`, or `safeguard`.
</ResponseField>

<ResponseField name="currency" type="string">
  ISO 4217 currency code.
  Fiat account: `USD`, `GBP`, `EUR`
  Stablecoin account: `USC`, `RLD`, `UST`
</ResponseField>

<ResponseField name="display_name" type="string">
  Human-readable label for the account.
</ResponseField>

<ResponseField name="nuvion_ban" type="string">
  Nuvion internal bank account number used for routing. Treat this as read-only.
</ResponseField>

<ResponseField name="balance" type="object">
  Current balance state of the account. All amounts are in the smallest currency unit (e.g. cents for USD).

  <Expandable title="balance fields">
    <ResponseField name="available" type="number">
      Spendable funds — excludes amounts pending settlement. Use this value when checking whether an entity has sufficient funds.
    </ResponseField>

    <ResponseField name="current" type="number">
      Total balance including amounts pending settlement.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Set of key-value pairs for storing additional platform-defined data.
</ResponseField>

<ResponseField name="created" type="number">
  Unix timestamp in milliseconds when the account was created.
</ResponseField>

<ResponseField name="updated" type="number">
  Unix timestamp in milliseconds when the account was last updated.
</ResponseField>

```json Example theme={null}
{
  "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
}
```

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

***

## Create an account

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

<CodeGroup>
  ```bash curl theme={null}
  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"
    }'
  ```
</CodeGroup>

<Tip>
  To create a stablecoin account, pass one of `USC`, `UST`, `RLD` as your currency.
</Tip>

### Request parameters

<ParamField body="entity_id" type="string" required>
  The ID of the entity to open this account for. The entity must have `status: "approved"`.
</ParamField>

<ParamField body="type" type="string" required>
  Account type. One of `checking`, `debit`, `operational`, or `safeguard`.
</ParamField>

<ResponseField name="currency" type="string">
  ISO 4217 currency code.
  Fiat account: `USD`, `GBP`, `EUR`
  Stablecoin account: `USC`, `RLD`, `UST`
</ResponseField>

<ParamField body="display_name" type="string" required>
  Human-readable label for the account. Maximum 100 characters.
</ParamField>

<ParamField body="meta" type="object">
  Key-value metadata to attach to the account. Values must be strings.
</ParamField>

### Response

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

```json Response theme={null}
{
  "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
}
```

<Tip>
  The first account created for an entity automatically becomes their default account.
</Tip>

***

## List accounts

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

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.nuvion.dev/accounts?entity_id=01HXYZ1234ABCD&limit=20" \
    -H "Authorization: Bearer $NUVION_API_KEY"
  ```
</CodeGroup>

### Request parameters

<ParamField query="entity_id" type="string">
  Filter accounts by entity ID. Required when authenticating with an API key.
</ParamField>

<ParamField query="currency" type="string">
  Filter by ISO 4217 currency code (e.g. `USD`).
</ParamField>

<ParamField query="type" type="string">
  Filter by account type. One of `checking`, `debit`, `operational`, or `safeguard`.
</ParamField>

<ParamField query="limit" type="integer">
  Number of results to return. Between 1 and 100. Defaults to `20`.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from a previous response. Omit for the first page.
</ParamField>

### Response

Returns a paginated list of account objects.

```json Response theme={null}
{
  "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.

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.nuvion.dev/accounts/01HXYZ5678EFGH" \
    -H "Authorization: Bearer $NUVION_API_KEY"
  ```
</CodeGroup>

### Request parameters

<ParamField path="account_id" type="string" required>
  The ID of the account to retrieve.
</ParamField>

<ParamField query="entity_id" type="string">
  The ID of the entity that owns the account. Required when authenticating with an API key.
</ParamField>

### Response

Returns the account object.

```json Response theme={null}
{
  "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
}
```