Create virtual bank accounts for your end users in multiple currencies (NGN, USD, EUR, MXN, BRL) with automatic cryptocurrency conversion capabilities.
Create Virtual Account
POST /v1/virtual-account/:currency
Create a virtual bank account for a user in the specified currency. The account will be linked to their cryptocurrency wallet for automatic conversion.
curl -X POST "https://api.useonion.xyz/v1/virtual-account/ngn" \
-H "Content-Type: application/json" \
-H "x-api-key: sk_live_…" \
-d '{
"userId": "user_456",
"destinationAsset": "USDC",
"destinationNetwork": "BASE",
"address": "0x1234567890abcdef1234567890abcdef12345678"
}'
- x-api-key (header): Active API key for authentication
Path Parameters
- currency (path): Currency code - one of:
NGN, USD, EUR, MXN, BRL
Body Parameters
| field | type | required | description |
|---|
| userId | string | yes | User identifier |
| destinationAsset | string | no | Target cryptocurrency: USDC, USDT, or DAI |
| destinationNetwork | string | no | Target blockchain: ETHEREUM, POLYGON, BASE, ARBITRUM, OPTIMISM |
| address | string | no | Destination wallet address (0x…) |
Response for NGN Virtual Account
Response: 200 OK
{
"id": "va_abc123",
"userId": "user_456",
"currency": "NGN",
"accountName": "ONION FINANCE/USER 456",
"accountNumber": "1001234567",
"bankName": "Providus Bank",
"bankCode": "101",
"createdAt": "2025-05-05T14:10:00Z",
"destinationAsset": "USDC",
"destinationNetwork": "BASE",
"destinationAddress": "0x1234567890abcdef1234567890abcdef12345678"
}
Response for USD/EUR/MXN/BRL Virtual Account
curl -X POST "https://api.useonion.xyz/v1/virtual-account/usd" \
-H "Content-Type: application/json" \
-H "x-api-key: sk_live_…" \
-d '{
"userId": "user_456",
"destinationAsset": "USDC",
"destinationNetwork": "BASE",
"address": "0x1234567890abcdef1234567890abcdef12345678"
}'
Response: 200 OK
{
"id": "va_def456",
"userId": "user_456",
"currency": "USD",
"bankName": "Evolve Bank & Trust",
"accountNumber": "1234567890",
"routingNumber": "084106768",
"accountHolderName": "John Doe",
"accountHolderType": "individual",
"bankAddress": "6070 Poplar Ave, Memphis, TN 38119",
"createdAt": "2025-05-05T14:10:00Z",
"destinationAsset": "USDC",
"destinationNetwork": "BASE",
"destinationAddress": "0x1234567890abcdef1234567890abcdef12345678"
}
Supported Currencies
| Currency | Provider | Features |
|---|
| NGN | Paystack | Nigerian Naira virtual accounts |
| USD | Bridge | US Dollar virtual accounts |
| EUR | Bridge | Euro virtual accounts |
| MXN | Bridge | Mexican Peso virtual accounts |
| BRL | Bridge | Brazilian Real virtual accounts |
Error Responses
Response: 400 Bad Request
{
"error": "Invalid currency. Supported currencies: NGN, USD, EUR, MXN, BRL"
}
Response: 500 Internal Server Error
{
"error": "Failed to create NGN virtual account",
"details": "Unable to connect to payment provider"
}
Virtual accounts are automatically linked to the user’s cryptocurrency wallet. When fiat is received, it’s instantly converted to the specified cryptocurrency and sent to the destination address.
