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

# Onramp to Helius Private Wallets

> Deposit onramp stablecoins into the recipient's Helius Private Wallet balance instead of their public token account

This guide covers how to deliver the stablecoins a user buys through Onramp into their private balance on Solana. By default, the tokens arrive in the recipient's public token account. With private delivery, they are deposited into the recipient's [Helius Private Wallet](https://www.helius.dev/docs/privacy/integration/wallet), part of [Solana Privacy Rings](https://www.helius.dev/docs/privacy). The resulting balance is encrypted onchain, and only the recipient can read it.

The deposit itself is a public Solana transaction, so the recipient address, the token, and the amount stay visible onchain. Only the balance it creates, and what the recipient does with that balance afterwards, is private.

## Prerequisites

* **Server API key**: with the `orders.create` and `orders.read` scopes. In staging, all scopes are included by default.
* **A recipient with a Private Wallet**: the Solana wallet address the tokens go to must have a registered [Helius Private Wallet](https://www.helius.dev/docs/privacy/integration/wallet). You can integrate one into your wallet or use the [Embedded Private Wallet](https://www.helius.dev/docs/privacy/integration/embedded-wallet).

## Supported Orders

Private delivery is available only for orders that meet all of the following:

| Requirement | Supported |
| :- | :- |
| Chain | Solana |
| Token | USDC and EURC |
| Order type | Onramp. Memecoin, NFT, and other token purchases are not supported. |
| Recipient | A Solana wallet address in `recipient.walletAddress`, with a registered Private Wallet |
| Buyer | Users who live outside the United States |

## Create the Order With Private Delivery

From your server, set `executionParameters.delivery` to `"private"` on the line item. The rest of the order is the same as any [onramp order](https://docs.crossmint.com/onramp/api-reference/create-order.md). Leave the field out, or set it to `"public"`, for a regular transfer.

```bash cURL theme={null}
curl --request POST \
    --url https://staging.crossmint.com/api/2022-06-09/orders \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
    --data '{
        "recipient": { "walletAddress": "USER_SOLANA_WALLET_ADDRESS" },
        "lineItems": [{
            "tokenLocator": "solana:4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
            "executionParameters": { "mode": "exact-in", "amount": "100", "delivery": "private" }
        }],
        "payment": {
            "method": "card",
            "receiptEmail": "user@example.com"
        }
    }'
```

```js Node.js theme={null}
const response = await fetch("https://staging.crossmint.com/api/2022-06-09/orders", {
    method: "POST",
    headers: {
        "X-API-KEY": "YOUR_SERVER_API_KEY",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        recipient: { walletAddress: "USER_SOLANA_WALLET_ADDRESS" },
        lineItems: [
            {
                tokenLocator: "solana:4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
                executionParameters: { mode: "exact-in", amount: "100", delivery: "private" },
            },
        ],
        payment: {
            method: "card",
            receiptEmail: "user@example.com",
        },
    }),
});
const { order, clientSecret } = await response.json();
```

```python Python theme={null}
import requests

response = requests.post(
    "https://staging.crossmint.com/api/2022-06-09/orders",
    headers={"X-API-KEY": "YOUR_SERVER_API_KEY", "Content-Type": "application/json"},
    json={
        "recipient": {"walletAddress": "USER_SOLANA_WALLET_ADDRESS"},
        "lineItems": [
            {
                "tokenLocator": "solana:4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
                "executionParameters": {"mode": "exact-in", "amount": "100", "delivery": "private"},
            }
        ],
        "payment": {"method": "card", "receiptEmail": "user@example.com"},
    },
)
print(response.json())
```

Create Order checks the chain, token, order type, and recipient, and looks up the recipient's Private Wallet in the onchain registry. The country restriction is checked later, when the buyer's country of residence is known after KYC. A successful Create Order response therefore does not confirm that the buyer is eligible. The rest of the flow, including KYC, payment, and the embedded checkout, is the same as for any onramp order.

> [!NOTE]
>
> Private delivery never falls back to a public transfer. If the recipient's Private Wallet is missing when the tokens
> are delivered, the order is not delivered and the user is refunded.

## Verify the Delivery

Fetch the order with [Get Order](https://docs.crossmint.com/onramp/api-reference/get-order.md). `lineItems[].executionParams.delivery` is `"private"` for an order created with private delivery. Once the order completes, the delivery transaction in `lineItems[].delivery` is the deposit into the recipient's private balance, not a transfer to their token account.

The tokens do not appear in the recipient's public token balance. The recipient reads them from their private balance with their Private Wallet. See [Read a private balance](https://www.helius.dev/docs/privacy/guides/read-balance) in the Helius docs.

## Troubleshooting

> [accordion] Order creation fails with 'The recipient wallet has no Helius Private Wallet. Private delivery needs one.'
>
> The wallet in `recipient.walletAddress` has no registered Private Wallet. Have the user create one, then create the order again, or create the order without `delivery: "private"`.

> [accordion] Order creation fails with 'Private delivery is only available for USDC and EURC onramp orders.'
>
> The line item buys a token other than USDC or EURC on Solana. Private delivery supports only those two onramp tokens.

> [accordion] Order creation fails with 'executionParameters.delivery 'private' is only available for onramp orders on Solana.'
>
> The line item is not an onramp token on Solana. For example, it buys a token on another chain, or a memecoin or an NFT on Solana. Use a USDC or EURC `tokenLocator` on Solana, or create the order without `delivery: "private"`.

> [accordion] Order creation fails with 'Private delivery needs a wallet recipient.'
>
> The order has no wallet recipient. Pass the user's Solana wallet address in `recipient.walletAddress`.

> [accordion] Payment fails with 'Private delivery is not available for US customers.'
>
> The user lives in the United States, where private delivery is not available. Create the order without `delivery: "private"`.

> [accordion] Order creation fails with a 502 status
>
> The Private Wallet registry could not be read to check the recipient. The error is temporary: create the order again.

## Next Steps

> [card] [Onramp to Non-Crossmint Wallets](https://docs.crossmint.com/onramp/guides/onramp-to-external-wallets.md)
>
> Link and verify wallets not created through Crossmint

> [card] [Get an Onramp Quote](https://docs.crossmint.com/onramp/guides/get-a-quote.md)
>
> Estimate the stablecoin amount before placing an order

> [card] [Create Order](https://docs.crossmint.com/onramp/api-reference/create-order.md)
>
> Full reference for the onramp order payload
