Skip to main content
This guide walks through the full onramp flow: deposit fiat into your account, convert it to a stablecoin, and pay it out to a blockchain wallet.

​
Prerequisites

  • An active account with a fiat balance (funded via bank transfer to your account’s funding method)
  • A crypto beneficiary registered for the destination wallet

​
Flow overview

Fiat deposit → Quote → Execute trade → Crypto payout
  1. Fiat lands in your account (e.g., a wire transfer credits your USD balance)
  2. Create a quote to convert USD to USDC
  3. Execute the quote — balances update atomically
  4. Pay out the USDC to a crypto beneficiary

​
Step 1: Check your balance

Verify that fiat funds have arrived by fetching the account: 
curl https://api.sandbox.nxos.io/v1/accounts/acct_a1b2c3d4... \
  -H "Authorization: Bearer nxos_sk_test_..."

{
  "object": "account",
  "accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "balances": [
    { "object": "balance", "asset": "USD", "amount": "10000.00" }
  ]
}

​
Step 2: Register a crypto beneficiary

If you haven’t already, create a crypto beneficiary for the destination wallet: 
curl -X POST https://api.sandbox.nxos.io/v1/beneficiaries/crypto \
  -H "Authorization: Bearer nxos_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "nickname": "Treasury Wallet",
    "chainName": "ethereum",
    "address": "0x1234567890abcdef1234567890abcdef12345678"
  }'

{
  "object": "beneficiary",
  "beneficiaryId": "bene_f1e2d3c4b5a6f1e2d3c4b5a6f1e2d3c4",
  "type": "CRYPTO",
  "nickname": "Treasury Wallet",
  "status": "ACTIVE",
  "crypto": {
    "chainName": "ethereum",
    "chainDisplayName": null,
    "platform": null,
    "address": "0x1234567890abcdef1234567890abcdef12345678"
  },
  "bank": null
}
chainDisplayName and platform are null on create responses. They are populated when you fetch the beneficiary later.

​
Step 3: Create a quote

Request a quote to convert USD to USDC. You can specify either fromAmount (how much to sell) or toAmount (how much to receive): 
curl -X POST https://api.sandbox.nxos.io/v1/quotes \
  -H "Authorization: Bearer nxos_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "fromAsset": "USD",
    "toAsset": "USDC",
    "fromAmount": "10000.00"
  }'

{
  "object": "quote",
  "quoteId": "quote_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "fromAsset": "USD",
  "toAsset": "USDC",
  "fromAmount": "10000.00",
  "toAmount": "9997.000000",
  "appliedRate": "1.0003",
  "spread": {
    "fee": "3.00",
    "asset": "USD"
  },
  "status": "PENDING",
  "expiresAt": "2025-03-15T14:35:00.000Z",
  "createdAt": "2025-03-15T14:30:00.000Z"
}
The response tells you exactly what you’ll get: 10,000 USD converts to 9,997 USDC after a $3.00 spread fee. The spread object shows the fee amount and which asset it’s denominated in (always the source asset).
Quotes expire after 5 minutes. Execute the quote before expiresAt or create a new one.

​
Step 4: Execute the quote

Execute the quote to complete the trade. Balances update atomically — USD is debited and USDC is credited in a single operation: 
curl -X POST https://api.sandbox.nxos.io/v1/quotes/quote_a1b2c3d4.../execute \
  -H "Authorization: Bearer nxos_sk_test_..."

{
  "object": "trade",
  "transactionId": "txn_b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5",
  "quoteId": "quote_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "fromAsset": "USD",
  "toAsset": "USDC",
  "fromAmount": "10000.00",
  "toAmount": "9997.000000",
  "status": "COMPLETED",
  "createdAt": "2025-03-15T14:31:00.000Z"
}
Your account now holds 9,997 USDC.

​
Step 5: Send crypto payout

Send the USDC to the registered crypto beneficiary: 
curl -X POST https://api.sandbox.nxos.io/v1/transactions/crypto-payouts \
  -H "Authorization: Bearer nxos_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "beneficiaryId": "bene_f1e2d3c4b5a6f1e2d3c4b5a6f1e2d3c4",
    "amount": "9997.000000",
    "asset": "USDC",
    "chainName": "ETHEREUM_MAINNET"
  }'

{
  "object": "transaction",
  "transactionId": "txn_c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "CRYPTO_PAYOUT",
  "status": "COMPLETED",
  "accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "beneficiaryId": "bene_f1e2d3c4b5a6f1e2d3c4b5a6f1e2d3c4",
  "amount": "9997.000000",
  "asset": "USDC",
  "toAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "createdAt": "2025-03-15T14:32:00.000Z"
}
The response includes the on-chain txHash — you can verify the transaction on a block explorer. Funds are debited immediately and the payout completes in a single request.

​
Summary

StepEndpointWhat happens
Check balanceGET /v1/accounts/{accountId}Verify fiat has arrived
Register beneficiaryPOST /v1/beneficiaries/cryptoOne-time setup for the destination wallet
Create quotePOST /v1/quotesLock in an exchange rate for 5 minutes
Execute tradePOST /v1/quotes/{quoteId}/executeConvert fiat to crypto atomically
Send payoutPOST /v1/transactions/crypto-payoutsSubmit on-chain and debit the account