Stablecoins

Nuvion covers the full stablecoin lifecycle for a stablecoin-focused business: receive USDC and USDT directly into a blockchain wallet, on-ramp a fiat balance into a stablecoin send to an external wallet, and off-ramp a stablecoin balance into a fiat payout.

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.

Receive stablecoins

Create a stablecoin account and issue it a wallet address to receive inbound USDC or USDT deposits directly.

Create a stablecoin account

Create an independent stablecoin account that holds a wallet address for receiving stablecoin transfers. Each account has 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 on an existing account. Each account holds one wallet. To receive on more than one chain, create a separate stablecoin account per chain. See Account Details for how account details are scoped, and Create account details for the full request and response field reference.

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",
    "chain": "eth"
 }'

Response

{
    "status": "success",
    "message": "Account detail created successfully",
    "data": {
        "account_details": {
            "id": "01KXZKJQDC33FP47RHYN3D8YHP",
            "entity_id": "01KCKRJJH6A3SJMAXBB737K5NP",
            "account_id": "01KXZFYY6B4S9TH4ENG2375ZM0",
            "account_number": "0x1111111111111111111111111111111111AAAAAA",
            "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",
            "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.

Convert between fiat and stablecoin

Nuvion converts between a fiat position and a stablecoin balance in both directions: request an FX quote for the currency pair, then pass its id as fx_quote_id on the transfer.

On-ramp: send stablecoins to an external wallet, funded from a fiat position. Request a quote with from_currency set to your fiat currency and to_currency set to the stablecoin, then debit a fiat account on the transfer.
Off-ramp: pay out a stablecoin balance to a bank account. Request a quote with from_currency set to the stablecoin and to_currency set to your fiat currency, then debit a stablecoin account on the transfer.

Create a counterparty and payment details for the recipient before requesting a quote. See Send a Payout for the counterparty step, and its payment details step for both the stablecoin wallet and bank account rails.

Create an FX quote

Request a quote for the pair using POST /fx-quotes, passing amount_from in the currency you’re converting from. See FX Quotes for the full request and response field reference.

curl -X POST https://api.nuvion.dev/fx-quotes \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_currency": "USD",
    "to_currency": "USC",
    "amount_from": 10000,
    "account_id": "01KR3NQSCAY9SC8WVKWAX2XJAB"
  }'

curl -X POST https://api.nuvion.dev/fx-quotes \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_currency": "USC",
    "to_currency": "USD",
    "amount_from": 250000000,
    "account_id": "01KXZFYY6B4S9TH4ENG2375ZM0"
  }'

Response

{
    "status": "success",
    "message": "FX quote created successfully",
    "data": {
        "id": "01KWVHTC5KHJ0FC4RN08JT21XT",
        "from": "USD",
        "to": "USC",
        "amount_from": 10000,
        "amount_to": 100000000,
        "rate": 1,
        "quote": {
            "status": "active",
            "expires_at": 1787289179000,
            "valid_for": 179,
            "used_at": null,
            "used_in_payment_id": null
        },
        "created": 1787289000000,
        "updated": 1787289000000
    }
}

{
    "status": "success",
    "message": "FX quote created successfully",
    "data": {
        "id": "01E6RHXQAQPDH4AFAXRHEM3E2M",
        "from": "USC",
        "to": "USD",
        "amount_from": 250000000,
        "amount_to": 25000,
        "rate": 1,
        "quote": {
            "status": "active",
            "expires_at": 1787290179000,
            "valid_for": 179,
            "used_at": null,
            "used_in_payment_id": null
        },
        "created": 1787290000000,
        "updated": 1787290000000
    }
}

Initiate the transfer

Use POST /transfers to move the funds, passing the FX quote’s id as fx_quote_id and debiting the account that holds the currency you’re converting from.

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

curl -X POST https://api.nuvion.dev/transfers \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "01KXZFYY6B4S9TH4ENG2375ZM0",
    "payment_detail_id": "01H9DN65R6PPG2X7R5JQC42EJ5",
    "counterparty_id": "0171HFE865V215DE1CTEWH0AVN",
    "amount": 250000000,
    "currency": "USC",
    "narration": "Stablecoin balance payout",
    "payment_type": "bank-transfer",
    "unique_reference": "PAYOUT-2025-0007",
    "fx_quote_id": "01E6RHXQAQPDH4AFAXRHEM3E2M"
  }'

See Create a stablecoin transfer for the on-ramp response schema and error codes, and Create a bank transfer for the off-ramp.

Transfer statuses

Status	Description
`pending`	Transfer created, awaiting processing
`processing`	Submitted to the blockchain or payment network, awaiting confirmation
`successful`	Confirmed. Funds have arrived at the recipient
`failed`	Transfer could not be completed
`reversed`	Transfer was reversed after completion

Webhooks

Subscribe to these events to track wallet provisioning and transfer lifecycle for both on-ramp sends and off-ramp payouts:

Event	Trigger
`account_details.created`	A stablecoin wallet address has been provisioned
`account_details.updated`	A wallet’s status or configuration has changed
`outflows.created`	A transfer has been created
`outflows.completed`	A transfer has completed successfully
`outflows.failed`	A transfer could not be completed
`outflows.cancelled`	A transfer was cancelled

Verify a transfer’s status with GET /transfers/{transfer_id} before treating an on-ramp send or off-ramp payout as complete, rather than relying on the webhook payload alone. See Verifying webhook signatures to confirm the event itself is genuine.

What’s next

Send a payout

The full set of payout rails and destination currencies available for off-ramping.

FX Quotes API reference

Full endpoint documentation for creating and retrieving FX quotes.

Transfers API reference

Full endpoint documentation for initiating and managing transfers.

Get Started

Core Concepts

Webhooks

Guides

Supported networks

Receive stablecoins

Create a stablecoin account

Response

Issue a wallet

Response

Convert between fiat and stablecoin

Create an FX quote

Response

Initiate the transfer

Transfer statuses

Webhooks

What’s next

Send a payout

FX Quotes API reference

Transfers API reference

​Supported networks

​Receive stablecoins

​Create a stablecoin account

​Response

​Issue a wallet

​Response

​Convert between fiat and stablecoin

​Create an FX quote

​Response

​Initiate the transfer

​Transfer statuses

​Webhooks

​What’s next

Send a payout

FX Quotes API reference

Transfers API reference

Supported networks

Receive stablecoins

Create a stablecoin account

Response

Issue a wallet

Response

Convert between fiat and stablecoin

Create an FX quote

Response

Initiate the transfer

Transfer statuses

Webhooks

What’s next