Onramp: fiat to crypto

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

Fiat lands in your account (e.g., a wire transfer credits your USD balance)
Create a quote to convert USD to USDC
Execute the quote — balances update atomically
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

Step	Endpoint	What happens
Check balance	`GET /v1/accounts/{accountId}`	Verify fiat has arrived
Register beneficiary	`POST /v1/beneficiaries/crypto`	One-time setup for the destination wallet
Create quote	`POST /v1/quotes`	Lock in an exchange rate for 5 minutes
Execute trade	`POST /v1/quotes/{quoteId}/execute`	Convert fiat to crypto atomically
Send payout	`POST /v1/transactions/crypto-payouts`	Submit on-chain and debit the account

​Prerequisites

​Flow overview

​Step 1: Check your balance

​Step 2: Register a crypto beneficiary

​Step 3: Create a quote

​Step 4: Execute the quote

​Step 5: Send crypto payout

​Summary

Prerequisites

Flow overview

Step 1: Check your balance

Step 2: Register a crypto beneficiary

Step 3: Create a quote

Step 4: Execute the quote

Step 5: Send crypto payout

Summary