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

# Stablecoins

> Issue blockchain wallet addresses for your entities and send or receive USDC and USDT across Ethereum, Solana, Base, and Polygon.

Nuvion supports stablecoin transfers natively. You can issue a wallet address on any supported chain for an entity's account, receive inbound stablecoin deposits, and send USDC or USDT to any external wallet address globally.

## Supported networks

| Chain   | Network          | Assets            |
| ------- | ---------------- | ----------------- |
| `eth`   | Ethereum Mainnet | USDC, USDT, RLUSD |
| `base`  | Base             | USDC, USDT        |
| `matic` | Polygon          | USDC, USDT        |
| `sol`   | Solana Mainnet   | USDC, USDT        |

<Note>
  Nuvion uses `USC` as the currency code for USDC and `UST` for USDT. Use these codes when initiating transfers.
</Note>

***

## Create a stablecoin account

Create an independent stablecoin account that holds a wallet address for receiving stablecoin transfers. Each account have its own banking details and wallet.

<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": "01KCKRJJH6A3SJMAXBB737K5NP",
      "type": "checking",
      "currency": "USC",
      "display_name": "stablecoin account"
   }'
  ```
</CodeGroup>

### Response

```json theme={null}
{
    "status": "success",
    "message": "Account created successfully",
    "data": {
        "account": {
            "id": "01KXZFYY6B4S9TH4ENG2375ZM0",
            "entity_id": "01KCKRJJH6A3SJMAXBB737K5NP",
            "type": "checking",
            "currency": "USC",
            "display_name": "stablecoin account",
            "config": {
                "overdraft_limit": 0,
                "balance_next_refresh": 0,
                "is_overdraftable": false,
                "balance_refresh_interval": 15
            },
            "balance": {
                "available": 0,
                "current": 0,
                "overdraft_used": 0
            },
            "stablecoin_assets": {},
            "maintenance_fee_opted_out": false,
            "created": 1784542099659,
            "updated": 1784542099659,
            "deleted": 0,
            "meta": {},
            "nuvion_ban": "0010346002"
        },
        "entity_impact": {
            "entity_id": "01KCKRJJH6A3SJMAXBB737K5NP",
            "total_accounts": 11,
            "account_type": [
                "checking"
            ],
            "default_account_set": true
        }
    }
}
```

***

## Issue a wallet

Issue a stablecoin wallet address by creating account details with `asset_type: stablecoin` on an existing account. Each account can hold one wallet per chain.

<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": "01KXZFYY6B4S9TH4ENG2375ZM0",
      "entity_id": "01KCKRJJH6A3SJMAXBB737K5NP",
      "config": {
        "outflow_enabled": true,
        "inflow_enabled": true,
        "outflow_allowed_counterparties": [
        ],
        "inflow_allowed_counterparties": [
        ]
      },
      "terminate_after": 365,
      "chain": "eth"
   }'
  ```
</CodeGroup>

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

<ParamField body="entity_id" type="string" required>
  The ID of the entity that owns the account.
</ParamField>

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

<ParamField body="terminate_after" type="number">
  Number of days after which the wallet address expires. Omit for a permanent wallet.
</ParamField>

### Response

```json theme={null}
{
    "status": "success",
    "message": "Account detail created successfully",
    "data": {
        "account_details": {
            "id": "01KXZKJQDC33FP47RHYN3D8YHP",
            "entity_id": "01KCKRJJH6A3SJMAXBB737K5NP",
            "account_id": "01KXZFYY6B4S9TH4ENG2375ZM0",
            "account_number": "0x53d8562b485a1210a2df779d2a8c137040bece8b",
            "issuer": {
                "code": "ETH_MAINNET",
                "name": "ETH_MAINNET",
                "short_name": "ETH_MAINNET"
            },
            "config": {
                "outflow_enabled": true,
                "inflow_enabled": true,
                "outflow_allowed_counterparties": [],
                "inflow_allowed_counterparties": []
            },
            "status": "pending",
            "terminate_after": 365,
            "chain": "eth",
            "beneficiary_name": "Everything-Empire",
            "currency": "USC",
            "created": 1784545893804,
            "updated": 1784545893804,
            "deleted": 0,
            "name": "Frank Joseph",
            "meta": {}
        }
    }
}
```

<Note>
  The wallet is created with `status: pending` while the address is being provisioned on-chain. Listen for the `account_details.created` webhook event to confirm the wallet is ready.
</Note>

***

Please refer to the [Send a payout guide](https://docs.nuvion.co/guides/send-a-payout) for instructions on sending funds..

## Step 2: Send stablecoins

Sending stablecoins is a four-step process:

1. Create a counterparty for the recipient wallet,
2. Create a Payment detail
3. Create Fx Quote to get the current rate for the transfer
4. Initiate a transfer.

### Create a counterparty

A counterparty represents the external wallet you're sending funds to. Create one using `POST /counterparties`.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.nuvion.dev/counterparties \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "individual",
      "entity_id": "01KCKRJJH6A3SJMAXBB737K5NP",
      "account_details":{
          "issuer":{
              "ETH_MAINNET": "ETH_MAINNET"
          },
          "account_number": "0x53d8562b485a1210a2df779d2a8c137040bece8b"
      },
      "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>

<ParamField body="type" type="string" required>
  The counterparty type. One of `individual` or `business`.
</ParamField>

<ParamField body="entity_relationship" type="string" required>
  Describes the relationship to your platform. e.g. `customer`, `vendor`, `supplier`.
</ParamField>

<ParamField body="name" type="string" required>
  Full name of the recipient.
</ParamField>

<ParamField body="email" type="string" required>
  Email address of the recipient.
</ParamField>

<ParamField body="address" type="object" required>
  The recipient's physical address.
</ParamField>

<ParamField body="account_details.issuer.code" type="string" required>
  The network the recipient wallet is on. One of `ETH_MAINNET`, `SOLANA_MAINNET`, `BASE_MAINNET`, `POLYGON_MAINNET`.
</ParamField>

<ParamField body="account_details.account_number" type="string" required>
  The recipient's wallet address.
</ParamField>

#### Responses

```json theme={null}
{
    "status": "success",
    "message": "Counterparty created successfully",
    "data": {
        "id": "01KWVE1BT842E7RQTBRPK46RN9",
        "entity_id": "01KCKRJJH6A3SJMAXBB737K5NP",
        "type": "individual",
        "nickname": "Jane Smith",
        "status": "active",
        "profile": {
            "first_name": "Jane",
            "last_name": "Smith",
            "relationship": "vendor",
            "address": {
                "line1": "123 Main St",
                "city": "Austin",
                "state_or_province": "TX",
                "postal_code": "78701",
                "country": "US"
            },
            "email": "jane.smith@example.com"
        },
        "created": 1783332122440,
        "updated": 1783332122440,
        "deleted": 0
    }
}
```

***

### Payment Details

Create a payment details for this transfer using `POST /payment-details`.

<CodeGroup>
  ```bash curl -X POST https://api.nuvion.dev/payment-details \ theme={null}
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "payment_method": "stablecoin-transfer",
      "currency": "USC",
      "account_holder_name": "Jane Smith",
      "entity_id": "01KCKRJJH6A3SJMAXBB737K5NP",
      "counterparty_id": "01KWVE1BT842E7RQTBRPK46RN9",
      "country": "US",
      "wallet_address": "0x9829203632188bAAe5C0BFDd362Fd6FDdD943B61",
      "blockchain_network": "ETH_MAINNET"
  }'
  ```
</CodeGroup>

#### Response

```json theme={null}
{
    "status": "success",
    "message": "Payment detail created successfully",
    "data": {
        "id": "01KWVE68QKMBQGZA12A84QQTFX",
        "payment_method": "stablecoin-transfer",
        "currency": "USC",
        "account_holder_name": "Jane Smith",
        "counterparty_id": "01KWVE1BT842E7RQTBRPK46RN9",
        "entity_id": "01KCKRJJH6A3SJMAXBB737K5NP",
        "scheme": "stablecoin",
        "country": "US",
        "blockchain_network": "ETH_MAINNET",
        "wallet_address": "0x9829203632188bAAe5C0BFDd362Fd6FDdD943B61"
    }
}
```

***

### Create FX Quote

Create FX Quote for the transfer using `POST /fx-quotes`. This is required for currency conversion.

<CodeGroup>
  ```bash curl -X POST https://api.nuvion.dev/fx-quotes \ theme={null}
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "to_currency": "USC",
    "from_currency": "USD",
    "amount_from": 10000,
    "account_id": "01KR3NQSCAY9SC8WVKWAX2XJAB",
    "counterparty_id": "01KWVE1BT842E7RQTBRPK46RN9", //Required
    "payment_detail_id":  "01KWVE68QKMBQGZA12A84QQTFX" // Required

  }'
  ```
</CodeGroup>

#### Response

```json theme={null}
{
    "status": "success",
    "message": "FX quote created successfully",
    "data": {
        "id": "01KWVHTC5KHJ0FC4RN08JT21XT",
        "to": "USC",
        "from": "USD",
        "amount_to": 10000,
        "rate": 1,
        "amount_from": 10000,
        "quote": {
            "used_at": null,
            "expires_at": 1783336207646,
            "used_in_payment_id": null,
            "valid_for": 119,
            "status": "active"
        },
        "created": 1783336087731,
        "updated": 1783336087731
    }
}
```

***

### Initiate the transfer

Once you have a counterparty, use `POST /transfers` to send stablecoins.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.nuvion.dev/transfers \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ 
      "account_id": "01KR3NQSCAY9SC8WVKWAX2XJAB",
      "payment_detail_id": "01KWVE68QKMBQGZA12A84QQTFX",
      "amount": 10000,
      "narration": "Invoice payment INV-2025-001",
      "payment_type": "stablecoin-transfer",
      "unique_reference": "PAY-2025-0023",
      "currency": "USD",
      "counterparty_id": "01KWVE1BT842E7RQTBRPK46RN9",
      "fx_quote_id": "01KWVHTC5KHJ0FC4RN08JT21XT"
  }'
  ```
</CodeGroup>

<ParamField body="account_id" type="string" required>
  The ID of the source account to debit.
</ParamField>

<ParamField body="counterparty_id" type="string" required>
  The ID of the recipient counterparty.
</ParamField>

<ParamField body="currency" type="string" required>
  The stablecoin to send. `USC` for USDC, `UST` for USDT.
</ParamField>

<ParamField body="payment_detail_id" type="string" required>
  The ID of the payment details for the recipient wallet.
</ParamField>

<ParamField body="fx_quote_id" type="string" required>
  The ID of the FX quote to use for this transfer.
</ParamField>

<ParamField body="amount" type="number" required>
  Amount in the smallest currency unit. `10000` = 100.00 USDC.
</ParamField>

<ParamField body="payment_type" type="string" required>
  Set to `stablecoin-transfer`.
</ParamField>

<ParamField body="narration" type="string" required>
  A description of the transfer.
</ParamField>

<ParamField body="unique_reference" type="string" required>
  A unique idempotency key for this transfer. Resubmitting with the same reference returns the original transfer rather than creating a duplicate.
</ParamField>

#### Response

```json theme={null}
{
  "id": "txf_01KCKNK76B401XBG286FTCMJSH",
  "account_id": "acc_01HXYZ5678EFGH",
  "entity_id": "ent_01HXYZ1234ABCD",
  "counterparty_id": "cpt_01KCKKPJYCRGCETKPNQ4VEV92K",
  "type": "outflow",
  "payment_type": "stablecoin-transfer",
  "currency": "USC",
  "amount": 10000,
  "applicable_fee": 2,
  "status": "pending",
  "status_reason": "awaiting_processing",
  "narration": "Payment for design services",
  "unique_reference": "STABLE-2025-001",
  "meta": {
    "payment_order_id": "01KCKNK779M261FRH7Y93JWS0B"
  },
  "created": 1735725600000,
  "updated": 1735725600000
}
```

***

## Transfer statuses

| Status       | Description                                                    |
| ------------ | -------------------------------------------------------------- |
| `pending`    | Transfer created, awaiting processing                          |
| `processing` | Submitted to the blockchain, awaiting on-chain confirmation    |
| `completed`  | Confirmed on-chain. Funds have arrived in the recipient wallet |
| `failed`     | Transfer could not be completed                                |
| `reversed`   | Transfer was reversed after completion                         |

***

## Webhooks

Subscribe to these events to track wallet provisioning and transfer lifecycle:

| Event                     | Trigger                                          |
| ------------------------- | ------------------------------------------------ |
| `account_details.created` | A stablecoin wallet address has been provisioned |
| `account_details.updated` | A wallet's status or configuration has changed   |
| `transfers.updated`       | A transfer's status has changed                  |

***

## What's next

<CardGroup cols={3}>
  <Card title="Account Details" icon="wallet" href="/core-concepts/account-details">
    Learn how fiat and stablecoin account details are structured and managed.
  </Card>

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

  <Card title="Transfers API reference" icon="code" href="/api-reference/transfers">
    Full endpoint documentation for initiating and managing transfers.
  </Card>
</CardGroup>