> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nxos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Onramp: fiat to crypto

> Accept fiat currency, convert to a stablecoin, and send it on-chain.

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:

```bash theme={null}
curl https://api.sandbox.nxos.io/v1/accounts/acct_a1b2c3d4... \
  -H "Authorization: Bearer nxos_sk_test_..."
```

```json theme={null}
{
  "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:

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "object": "beneficiary",
  "beneficiaryId": "bene_f1e2d3c4b5a6f1e2d3c4b5a6f1e2d3c4",
  "type": "CRYPTO",
  "nickname": "Treasury Wallet",
  "status": "ACTIVE",
  "crypto": {
    "chainName": "ethereum",
    "chainDisplayName": null,
    "platform": null,
    "address": "0x1234567890abcdef1234567890abcdef12345678"
  },
  "bank": null
}
```

<Note>
  `chainDisplayName` and `platform` are `null` on create responses. They are populated when you fetch the beneficiary later.
</Note>

## 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):

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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).

<Warning>
  Quotes expire after 5 minutes. Execute the quote before `expiresAt` or create a new one.
</Warning>

## 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:

```bash theme={null}
curl -X POST https://api.sandbox.nxos.io/v1/quotes/quote_a1b2c3d4.../execute \
  -H "Authorization: Bearer nxos_sk_test_..."
```

```json theme={null}
{
  "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:

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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     |