> ## 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.

# Account Details

> Generate and retrieve bank account numbers, IBANs, and wallet addresses for receiving funds.

Account details are the banking coordinates Nuvion provisions for an account. Share them with payers to receive funds — routing number and account number for USD, IBAN and BIC for EUR, sort code and account number for GBP, and wallet addresses for stablecoins.

***

## The Account Details object

<ResponseField name="id" type="string">
  Unique identifier for this set of account details.
</ResponseField>

<ResponseField name="entity_id" type="string">
  The ID of the entity that owns the account.
</ResponseField>

<ResponseField name="account_id" type="string">
  The ID of the account these details belong to.
</ResponseField>

<ResponseField name="account_number" type="string">
  Bank account number or IBAN for fiat accounts. Wallet address for stablecoin accounts.
</ResponseField>

<ResponseField name="issuer" type="object">
  The institution or network that issued these details.

  <Expandable title="issuer fields">
    <ResponseField name="name" type="string">
      Institution name (e.g. `Lead Bank`) or network name (e.g. `Ethereum Mainnet`).
    </ResponseField>

    <ResponseField name="code" type="string">
      Routing number, BIC, sort code, or chain code depending on the currency and `asset_type`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="chain" type="string">
  The blockchain the wallet address is provisioned on. Stablecoin accounts only. One of `eth`, `base`, `matic`, or `sol`.
</ResponseField>

<ResponseField name="supported_assets" type="array">
  The stablecoin assets that can be received at this address. Stablecoin accounts only. Always `["USDC", "USDT"]`.
</ResponseField>

<ResponseField name="status" type="string">
  `active` — ready to receive funds. `pending` — being provisioned (stablecoin accounts only, while the wallet address is generated on-chain).
</ResponseField>

<ResponseField name="terminate_after" type="number">
  Number of days until these details expire and deactivate. Null if no expiry is set.
</ResponseField>

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

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

<CodeGroup>
  ```json USD theme={null}
  {
    "id": "01HXYZ9012IJKL",
    "entity_id": "01HXYZ1234ABCD",
    "account_id": "01HXYZ5678EFGH",
    "account_number": "4561237890",
    "issuer": {
      "name": "Lead Bank",
      "code": "021000021"
    },
    "status": "active",
    "terminate_after": null,
    "created": 1735725600000,
    "updated": 1735725600000
  }
  ```

  ```json Ethereum (stablecoin) theme={null}
  {
    "id": "01HXYZ9012MNOP",
    "entity_id": "01HXYZ1234ABCD",
    "account_id": "01HXYZ5678EFGH",
    "chain": "eth",
    "account_number": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "supported_assets": ["USDC", "USDT"],
    "issuer": {
      "name": "Ethereum Mainnet",
      "code": "ETH_MAINNET"
    },
    "status": "pending",
    "terminate_after": null,
    "created": 1735725600000,
    "updated": 1735725600000
  }
  ```
</CodeGroup>

***

## Create account details

Provision banking coordinates or a wallet address for an account. The type of details provisioned depends on currency.

<CodeGroup>
  ```bash Fiat theme={null}
  curl -X POST https://api.nuvion.dev/account-details \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "account_id": "01HXYZ5678EFGH",
    }'
  ```

  ```bash Stablecoin theme={null}
  curl -X POST https://api.nuvion.dev/account-details \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "account_id": "01HXYZ5678EFGH",
      "chain": "eth"
    }'
  ```
</CodeGroup>

### Request parameters

<ParamField body="account_id" type="string" required>
  The ID of the account to provision details for.
</ParamField>

<ParamField body="chain" type="string">
  The blockchain to provision the wallet on. One of `eth`, `base`, `matic`, or `sol`.
</ParamField>

<ParamField body="terminate_after" type="number">
  Number of days after which these details expire and deactivate automatically. Omit for permanent details.
</ParamField>

<ParamField body="provider_id" type="string">
  Fiat only. Override the default banking provider. Omit to use the Nuvion default for the account currency.
</ParamField>

### Response

Returns the created account details object. Fiat details are `active` immediately. Stablecoin details start as `pending`.

```json Response theme={null}
{
  "id": "01HXYZ9012IJKL",
  "entity_id": "01HXYZ1234ABCD",
  "account_id": "01HXYZ5678EFGH",
  "account_number": "4561237890",
  "issuer": {
    "name": "Lead Bank",
    "code": "021000021"
  },
  "status": "active",
  "terminate_after": null,
  "created": 1735725600000,
  "updated": 1735725600000
}
```

<Note>
  Stablecoin details are created with `status: "pending"` while the wallet address is provisioned on-chain. Listen for the `account_details.created` webhook to confirm the address is ready before sharing it with payers.
</Note>

<Tip>
  Account details are persistent. Create them once per account — you don't need to regenerate them for each transaction.
</Tip>

### Identifiers returned by currency

The fields populated in `account_number` and `issuer.code` depend on the account currency.

| Currency | Identifiers                                        |
| -------- | -------------------------------------------------- |
| USD      | Account number, routing number                     |
| EUR      | IBAN, BIC                                          |
| GBP      | Account number, sort code                          |
| CAD      | Account number, institution number, transit number |
| AED      | Account number, IBAN                               |
| NGN      | Account number                                     |
| ZAR      | Account number, branch code                        |

***

## List account details

Returns a paginated list of account details records.

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

### Request parameters

<ParamField query="account_id" type="string">
  Filter by account ID. Required when authenticating with an API key.
</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

```json Response theme={null}
{
  "data": [
    {
      "id": "01HXYZ9012IJKL",
      "entity_id": "01HXYZ1234ABCD",
      "account_id": "01HXYZ5678EFGH",
      "account_number": "4561237890",
      "issuer": {
        "name": "Lead Bank",
        "code": "021000021"
      },
      "status": "active",
      "terminate_after": null,
      "created": 1735725600000,
      "updated": 1735725600000
    }
  ],
  "meta": {
    "pagination": {
      "has_next": false,
      "has_previous": false,
      "next_cursor": null,
      "previous_cursor": null,
      "total_count": 1
    }
  }
}
```

***

## Get account details

Retrieves a single set of account details by ID.

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

### Request parameters

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

### Response

Returns the account details object.

```json Response theme={null}
{
  "id": "01HXYZ9012IJKL",
  "entity_id": "01HXYZ1234ABCD",
  "account_id": "01HXYZ5678EFGH",
  "account_number": "4561237890",
  "issuer": {
    "name": "Lead Bank",
    "code": "021000021"
  },
  "status": "active",
  "terminate_after": null,
  "created": 1735725600000,
  "updated": 1735725600000
}
```

***

## Expiring account details

Pass `terminate_after` on creation to set an expiry. Details deactivate automatically after that many days — no further action is needed. Expired details stop accepting inbound funds.

Use cases for expiring details include temporary collection accounts, one-off payout flows, and time-limited receiving addresses where you want to ensure funds aren't received outside a defined window.