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

# Quickstart

> Make your first Nuvion API calls. You'll create an entity, open an account, generate account details, and transfer — in under 10 minutes.

<Note>
  You'll need a Nuvion sandbox API key to follow this guide. [Create an account](https://dashboard.nuvion.co/signup) to get yours.
</Note>

## Before you begin

Every request to the Nuvion API requires these headers:

| Header          | Value                   |
| --------------- | ----------------------- |
| `Authorization` | `Bearer NUVION_API_KEY` |
| `Content-Type`  | `application/json`      |

Set your API key as an environment variable so you don't repeat yourself:

```bash theme={null}
export NUVION_API_KEY=nuvion_api_key
```

***

## Step 1: Create an entity

An entity represents a person or business on your platform. All accounts and transactions belong to an entity.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.nuvion.dev/entities \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "individual",
      "first_name": "Alex",
      "last_name": "Johnson",
      "email": "alex.johnson@example.com",
      "country": "US"
    }'
  ```
</CodeGroup>

A successful response returns an entity object. Save the `id` — you'll need it in the next step.

```json theme={null}
{
  "id": "ent_01HXYZ1234ABCD",
  "object": "entity",
  "type": "individual",
  "first_name": "Alex",
  "last_name": "Johnson",
  "email": "alex.johnson@example.com",
  "country": "US",
  "status": "active",
  "created_at": "2026-01-01T10:00:00Z"
}
```

***

## Step 2: Create an account

Accounts hold balances. Each account is denominated in a single currency. An entity can have multiple accounts across different currencies.

<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 '{
      "type": "checking",
      "currency": "USD",
      "display_name": "Main USD Account"
    }'
  ```
</CodeGroup>

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

***

## Step 3: Register a counterparty

A counterparty represents a payout recipient — a person or business you send funds to. Counterparties hold identity information. Payment routing details (bank account numbers, wallet addresses) are stored separately as payment details attached to the counterparty.

<CodeGroup>
  ```bash curl -X POST https://api.nuvion.dev/counterparties \ theme={null}
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "individual",
      "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
      "profile": {
        "first_name": "Jane",
        "last_name": "Smith",
        "relationship": "vendor",
        "email": "jane.smith@example.com",
        "address": {
          "line1": "123 Main St",
          "city": "Austin",
          "state_or_province": "TX",
          "postal_code": "78701",
          "country": "US"
        }
      }
    }'
  ```
</CodeGroup>

***

## Step 4: Create account details

Account details generate the banking coordinates for an account — routing numbers, IBANs, sort codes, and other identifiers depending on the currency and supported rails. These are what your entity shares with counterparties to receive funds.

<CodeGroup>
  ```bash curl 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",
      "asset_type": "fiat"
    }'
  ```
</CodeGroup>

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

<Tip>
  Account details are persistent — you only need to create them once per account per rail. Store the returned details and reuse them.
</Tip>

***

## Step 4: Initiate Transfer

In sandbox, use the `/transfers` endpoint to simulate transfers. The sandbox environment lets you test transfers, payouts, accept payments and other flows without using real funds.

<CodeGroup>
  ```bash curl -X POST https://api.nuvion.dev/transfers \ theme={null}
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \   
  -d '{
      "currency": "USD",
      "amount": 10000,
      "account_id": "01KCKRJJH6A3SJMAXBB737K5NP",
      "narration": "Payment for services rendered",
      "payment_detail_id": "01KQHBQQW1GR5PBH16BY0T56PP",
      "payment_type": "bank-transfer",
      "counterparty_id": "01KQESEEKSRKEKMACFX5HN0Q58",
      "unique_reference": "INV-12345"
  }'
  ```
</CodeGroup>

<Note>
  All amounts in the Nuvion API are in the **smallest currency unit**. `10000` is \$100.00 USD.
</Note>

***

## Step 5: Retrieve account

Retrieve the account to confirm account data.

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

```json theme={null}
{
      "entity_id": "01KCKRJJH6A3SJMAXBB737K5NP",
      "type": "checking",
      "currency": "USD",
      "display_name": "USD Test2 account",
      "config": {
          "overdraft_limit": 0,
          "is_overdraftable": false
      },
      "nuvion_ban": "0000629000",
      "balance": {
          "current": 30000000,
          "available": 30000000,
          "overdraft_used": 0
      },
      "created": 1778239923594,
      "updated": 1779101523841,
      "id": "01KR3NQSCAY9SC8WVKWAX2XJAB",
      "status": "active"
},
```

Your entity now has an account with banking coordinates. You're ready to start building.

***

## What's next

<CardGroup cols={2}>
  <Card title="Accept a payment" icon="arrow-down-to-line" href="/guides/accept-a-payment">
    Receive funds from a bank transfer or card into a Nuvion account.
  </Card>

  <Card title="Send a payout" icon="arrow-up-from-line" href="/guides/send-a-payout">
    Send funds from an account to any bank account globally.
  </Card>
</CardGroup>