Stablecoins

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

Nuvion uses USC as the currency code for USDC and UST for USDT. Use these codes when initiating transfers.

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.

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"
 }'

Response

{
    "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.

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"
 }'

string

required

The ID of the account to issue the wallet for.

string

required

The ID of the entity that owns the account.

string

required

The blockchain to provision the wallet address on. One of eth, base, matic, sol.

number

Number of days after which the wallet address expires. Omit for a permanent wallet.

Response

{
    "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": {}
        }
    }
}

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.

Please refer to the Send a payout guide for instructions on sending funds..

Step 2: Send stablecoins

Sending stablecoins is a four-step process:

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

Create a counterparty

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

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"
      }
    }
  }'

string

required

The counterparty type. One of individual or business.

string

required

Describes the relationship to your platform. e.g. customer, vendor, supplier.

string

required

Full name of the recipient.

string

required

Email address of the recipient.

object

required

The recipient’s physical address.

string

required

The network the recipient wallet is on. One of ETH_MAINNET, SOLANA_MAINNET, BASE_MAINNET, POLYGON_MAINNET.

string

required

The recipient’s wallet address.

Responses

{
    "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.

  -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"
}'

Response

{
    "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.

  -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

}'

Response

{
    "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.

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"
}'

string

required

The ID of the source account to debit.

string

required

The ID of the recipient counterparty.

string

required

The stablecoin to send. USC for USDC, UST for USDT.

string

required

The ID of the payment details for the recipient wallet.

string

required

The ID of the FX quote to use for this transfer.

number

required

Amount in the smallest currency unit. 10000 = 100.00 USDC.

string

required

Set to stablecoin-transfer.

string

required

A description of the transfer.

string

required

A unique idempotency key for this transfer. Resubmitting with the same reference returns the original transfer rather than creating a duplicate.

Response

{
  "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

Account Details

Learn how fiat and stablecoin account details are structured and managed.

Send a payout

Send fiat funds from an account to any bank account globally.

Transfers API reference

Full endpoint documentation for initiating and managing transfers.

Get Started

Core Concepts

Webhooks

Guides

Supported networks

Create a stablecoin account

Response

Issue a wallet

Response

Step 2: Send stablecoins

Create a counterparty

Responses

Payment Details

Response

Create FX Quote

Response

Initiate the transfer

Response

Transfer statuses

Webhooks

What’s next

Account Details

Send a payout

Transfers API reference

​Supported networks

​Create a stablecoin account

​Response

​Issue a wallet

​Response

​Step 2: Send stablecoins

​Create a counterparty

​Responses

​Payment Details

​Response

​Create FX Quote

​Response

​Initiate the transfer

​Response

​Transfer statuses

​Webhooks

​What’s next

Account Details

Send a payout

Transfers API reference

Supported networks

Create a stablecoin account

Response

Issue a wallet

Response

Step 2: Send stablecoins

Create a counterparty

Responses

Payment Details

Response

Create FX Quote

Response

Initiate the transfer

Response

Transfer statuses

Webhooks

What’s next