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

# REST API Quickstart

> Open a virtual account and receive a test deposit in staging

In this quickstart, you will open an EUR virtual account in the Staging environment and receive a test deposit in the user's wallet. You will:

* Open a virtual account for a user
* Simulate a bank transfer into the account
* Read the order and see the EURC delivered to the wallet

No real bank transfer is sent. The simulated deposit follows the same path as a real one.

> [!NOTE]
>
> Virtual Accounts are gated in both staging and production. [Contact Crossmint](https://www.crossmint.com/contact/sales) to get access.

## Prerequisites

* **Verified user**: a staging user who has passed onramp KYC. See [User Onboarding and KYC](https://docs.crossmint.com/onramp/introduction/user-onboarding.md).
* **Registered wallet**: the user's wallet on Solana, linked to the user with ownership verified through the [Link Wallet API](https://docs.crossmint.com/api-reference/users/link-wallet.md). The user's own Crossmint wallet needs no linking.
* **API Key**: a staging server API key with the `virtual-accounts.create`, `virtual-accounts.read`, and `orders.read` scopes. In staging, all scopes are included by default.

## Integration Steps

**1. Open the Account**

Send the user, the currency, and the wallet and token that deposits go to.

```bash cURL theme={null}
curl --request POST \
    --url https://staging.crossmint.com/api/2026-09-16/virtual-accounts \
    --header 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
        "userLocator": "email:jane@example.com",
        "label": "EUR deposits",
        "source": {
            "currency": "eur"
        },
        "destination": {
            "walletAddress": "7vQ3mXk2Lp9RtYw4NcB8sHd6JfGa1ZeUoTq5Vr3k9Px",
            "tokenLocator": "solana:eurc"
        }
    }'
```

```js Node.js theme={null}
const response = await fetch("https://staging.crossmint.com/api/2026-09-16/virtual-accounts", {
    method: "POST",
    headers: {
        "X-API-KEY": "<YOUR_SERVER_API_KEY>",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        userLocator: "email:jane@example.com",
        label: "EUR deposits",
        source: {
            currency: "eur",
        },
        destination: {
            walletAddress: "7vQ3mXk2Lp9RtYw4NcB8sHd6JfGa1ZeUoTq5Vr3k9Px",
            tokenLocator: "solana:eurc",
        },
    }),
});

console.log(await response.json());
```

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

response = requests.post(
    "https://staging.crossmint.com/api/2026-09-16/virtual-accounts",
    headers={"X-API-KEY": "<YOUR_SERVER_API_KEY>"},
    json={
        "userLocator": "email:jane@example.com",
        "label": "EUR deposits",
        "source": {
            "currency": "eur",
        },
        "destination": {
            "walletAddress": "7vQ3mXk2Lp9RtYw4NcB8sHd6JfGa1ZeUoTq5Vr3k9Px",
            "tokenLocator": "solana:eurc",
        },
    },
)

print(response.json())
```

The account returns `201` with the bank details in `depositInstructions`:

```json Response theme={null}
{
    "virtualAccountId": "7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35",
    "userLocator": "email:jane@example.com",
    "label": "EUR deposits",
    "status": "active",
    "statusReason": null,
    "depositInstructions": {
        "bankAccount": {
            "iban": "MT00EXAMPLE0000000000000000000",
            "bic": "EXAMPLEXXX",
            "accountHolder": {
                "name": "Jane Doe"
            },
            "entityType": "individual",
            "institutionName": "OpenPayd Financial Services Malta Limited",
            "institutionAddress": "Level 3, 137 Spinola Road, St Julian's STJ 3011, Malta",
            "currency": "eur",
            "country": "MT",
            "rails": {
                "supported": ["sct", "sct-inst"]
            }
        }
    },
    "destination": {
        "walletAddress": "7vQ3mXk2Lp9RtYw4NcB8sHd6JfGa1ZeUoTq5Vr3k9Px",
        "tokenLocator": "solana:eurc"
    },
    "createdAt": "2026-11-16T10:00:00.000Z",
    "updatedAt": "2026-11-16T10:00:04.000Z"
}
```

Save the `virtualAccountId`. When the call answers `403 payments:virtual-account.not-eligible`, the user still has to pass KYC. See [When the User Is Not Eligible](https://docs.crossmint.com/virtual-accounts/guides/open-a-virtual-account.md#when-the-user-is-not-eligible). When `status` is `pending`, see [Wait for the Bank Details](https://docs.crossmint.com/virtual-accounts/guides/open-a-virtual-account.md#integration-steps).

**2. Simulate a Deposit**

In production, the user sends a bank transfer to the IBAN. In staging, the `simulate-deposit` call makes a deposit arrive in the account. Send it with the `completed` outcome:

```bash cURL theme={null}
curl --request POST \
    --url https://staging.crossmint.com/api/2026-09-16/virtual-accounts/7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35/simulate-deposit \
    --header 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
        "amount": "200.00",
        "sender": {
            "name": "JANE DOE"
        },
        "rail": "sct-inst",
        "outcome": "completed"
    }'
```

```js Node.js theme={null}
const response = await fetch("https://staging.crossmint.com/api/2026-09-16/virtual-accounts/7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35/simulate-deposit", {
    method: "POST",
    headers: {
        "X-API-KEY": "<YOUR_SERVER_API_KEY>",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        amount: "200.00",
        sender: {
            name: "JANE DOE",
        },
        rail: "sct-inst",
        outcome: "completed",
    }),
});

console.log(await response.json());
```

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

response = requests.post(
    "https://staging.crossmint.com/api/2026-09-16/virtual-accounts/7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35/simulate-deposit",
    headers={"X-API-KEY": "<YOUR_SERVER_API_KEY>"},
    json={
        "amount": "200.00",
        "sender": {
            "name": "JANE DOE",
        },
        "rail": "sct-inst",
        "outcome": "completed",
    },
)

print(response.json())
```

The call answers `202` with the `orderId` of the deposit:

```json Response theme={null}
{
    "simulationId": "5d8a1f3c-7e2b-4c9a-b6d0-3f1e8a2c4b57",
    "orderId": "c41e8a7d-2f5b-4d9e-b3a6-8e1f0c7d5b92",
    "virtualAccountId": "7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35",
    "amount": "200.00",
    "currency": "eur",
    "outcome": "completed"
}
```

**3. Read the Order**

Every deposit is an order. Read it with the [Get Order API](https://docs.crossmint.com/onramp/api-reference/get-order.md):

```bash cURL theme={null}
curl --request GET \
    --url https://staging.crossmint.com/api/2022-06-09/orders/c41e8a7d-2f5b-4d9e-b3a6-8e1f0c7d5b92 \
    --header 'X-API-KEY: <YOUR_SERVER_API_KEY>'
```

```js Node.js theme={null}
const response = await fetch("https://staging.crossmint.com/api/2022-06-09/orders/c41e8a7d-2f5b-4d9e-b3a6-8e1f0c7d5b92", {
    method: "GET",
    headers: {
        "X-API-KEY": "<YOUR_SERVER_API_KEY>",
    },
});

console.log(await response.json());
```

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

response = requests.get(
    "https://staging.crossmint.com/api/2022-06-09/orders/c41e8a7d-2f5b-4d9e-b3a6-8e1f0c7d5b92",
    headers={"X-API-KEY": "<YOUR_SERVER_API_KEY>"},
)

print(response.json())
```

When `phase` is `completed`, the stablecoins are in the wallet:

```json Response (excerpt) theme={null}
{
    "orderId": "c41e8a7d-2f5b-4d9e-b3a6-8e1f0c7d5b92",
    "phase": "completed",
    "lineItems": [
        {
            "chain": "solana",
            "quote": {
                "status": "valid",
                "charges": {
                    "transferFee": {
                        "amount": "0.10",
                        "currency": "eur"
                    },
                    "crossmintFees": {
                        "amount": "0.00",
                        "currency": "eur"
                    },
                    "fees": {
                        "type": "exact",
                        "amount": "0.10",
                        "currency": "eur"
                    }
                },
                "totalPrice": {
                    "amount": "200.00",
                    "currency": "eur"
                }
            },
            "delivery": {
                "status": "completed",
                "recipient": {
                    "locator": "solana:7vQ3mXk2Lp9RtYw4NcB8sHd6JfGa1ZeUoTq5Vr3k9Px",
                    "walletAddress": "7vQ3mXk2Lp9RtYw4NcB8sHd6JfGa1ZeUoTq5Vr3k9Px"
                },
                "txId": "3Ry7nQ5wK2mT8vB4hZ6dF1sJ9gL2aE7uC5nX3yP8qW4rD6mV1bH9jS2fN5kG8zA3cT7xM4wQ1eR6tY9uE2pLk",
                "tokens": [
                    {
                        "locator": "solana:HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr",
                        "quantity": "199900000",
                        "symbol": "EURC",
                        "decimals": 6
                    }
                ]
            }
        }
    ],
    "quote": {
        "status": "valid",
        "totalPrice": {
            "amount": "200.00",
            "currency": "eur"
        },
        "exchangeRate": {
            "sourceCurrency": "eur",
            "destinationCurrency": "eurc",
            "rate": "1.0000"
        }
    }
}
```

`lineItems[].delivery.txId` is the onchain transaction, and `tokens` holds the amount delivered. The amounts, rate, and fees are illustrative.

## Learn More

> [card] [How Virtual Accounts Work](https://docs.crossmint.com/virtual-accounts/concepts/how-it-works.md)
>
> The flow of an account and of each deposit

> [card] [Open a Virtual Account](https://docs.crossmint.com/virtual-accounts/guides/open-a-virtual-account.md)
>
> Eligibility, terms of service, pending accounts, and errors
