> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rolla.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Simulate a USD Deposit (Sandbox)
> Sandbox only: simulate an incoming USD deposit into your account's USD wallet. Dispatched to the account's USD provider sandbox; the wallet is credited asynchronously via the provider's deposit webhook. Returns 404 in production. Requires an issued, active USD account.
A testing helper that simulates an **incoming USD deposit** into your account's **USD wallet** so you can verify your USD funding flow end-to-end — the wallet is credited and the deposit [webhook](/api-reference/webhooks/overview) is delivered — **without sending a real wire transfer**.
It is the USD counterpart of [Simulate a Deposit](/api-reference/endpoint/wallet/simulate-deposit). The request is dispatched to your account's USD provider sandbox; the wallet balance is then credited **asynchronously** via that provider's normal deposit webhook — so the call only *submits* the simulated inbound transfer.
**Sandbox / testing only.** This endpoint does **not** exist in production — calls to the production API return `404 Not Found`. Use it against your sandbox environment only.
## Prerequisites
The account must already have an **issued, active USD account**. Issue one first via [Issue a Bank Account](/api-reference/endpoint/accounts/issue-bank-account) with `currency: "USD"`. If no USD account is provisioned yet, the call returns `404` with code `USD_ACCOUNT_NOT_FOUND`.
To simulate a deposit for a specific sub-account under your tenancy, send its id in the `X-Account-Id` header. Without it the deposit is credited to **your own** business, which returns `404` if your business has no USD account of its own.
This endpoint always credits the client's **primary** USD account. If the client holds several deposit accounts — one per [`reference`](/api-reference/endpoint/accounts/issue-bank-account#multiple-usd-deposit-accounts) — use [Simulate an Account Deposit](/api-reference/endpoint/accounts/simulate-deposit) instead, which can target one of them by reference.
## Request Body
| Field | Type | Required | Description |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `amount` | string | Yes | Deposit amount in major units of USD (e.g. `"100"` or `"100.50"`). Must be greater than 0. |
| `reference` | string | No | Your own reference for the simulated transfer. If omitted, a reference is generated for you. |
| `sender_name` | string | No | Name to record as the sender/counterparty on the transaction. |
## Example Request
```bash theme={null}
curl -X POST "https://api-staging.rolla.xyz/api/v1/external/wallet/simulate-usd-deposit" \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"amount": "100",
"sender_name": "John Sender"
}'
```
## Example Response
```json theme={null}
{
"status": 201,
"success": true,
"message": "Simulated USD deposit submitted",
"data": {
"status": "submitted",
"amount": "100",
"currency": "USD",
"reference": "RL_SIM_A7CAF7AC3673",
"transferId": "9d56e63c-2f2f-42b3-9ef7-1852677692cf",
"message": "Simulated incoming USD transfer submitted. The balance will be credited to the wallet via the provider webhook."
}
}
```
## What happens
1. The request is routed to your account's USD provider sandbox, which submits a simulated incoming transfer against your USD account. The response `status` is `submitted` — the balance is **not** credited yet.
2. The provider then delivers a deposit webhook through the **same crediting path a real USD deposit uses**, and your USD wallet is credited.
3. The transaction is completed, emitting the deposit webhook to your configured endpoint: a `transaction.pending` event, followed by `transaction.completed`. See [Webhook Payloads](/api-reference/webhooks/payloads).
Because the credit is delivered by the provider webhook, it is **not instant**. After a `submitted` response, poll [List Wallets](/api-reference/endpoint/wallet/wallets) or [Transactions](/api-reference/endpoint/wallet/transactions) until the USD balance lands.
Because this credits a real (sandbox) wallet balance, treat it like any other write: it moves your test wallet's balance and generates a real transaction record and webhook delivery.
## OpenAPI
````yaml POST /wallet/simulate-usd-deposit
openapi: 3.1.0
info:
title: Rolla Developer API
description: >-
API for programmatic transaction management on the Rolla platform. Monetary
`amount` fields use the smallest unit of the referenced currency unless an
endpoint says otherwise (e.g. NGN = kobo, USD = cents, where **100 cents =
USD 1.00**).
version: 1.0.0
servers:
- url: https://api.rolla.xyz/api/v1/external
description: Production server
security:
- apiKeyAuth: []
paths:
/wallet/simulate-usd-deposit:
post:
summary: Simulate a USD Deposit (Sandbox)
description: >-
Sandbox only: simulate an incoming USD deposit into your account's USD
wallet. Dispatched to the account's USD provider sandbox; the wallet is
credited asynchronously via the provider's deposit webhook. Returns 404
in production. Requires an issued, active USD account.
operationId: simulateUsdDeposit
parameters:
- name: X-Account-Id
in: header
required: false
schema:
type: string
format: uuid
description: >-
Target a specific sub-account under your tenancy. Omit to use the
calling account.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- amount
properties:
amount:
type: string
description: >-
Deposit amount in major units of USD. Must be greater than
0.
example: '100'
reference:
type: string
description: >-
Your own reference for the simulated transfer.
Auto-generated if omitted.
maxLength: 120
sender_name:
type: string
description: >-
Name to record as the sender/counterparty on the
transaction.
maxLength: 120
example: John Sender
responses:
'201':
description: Simulated USD deposit submitted
content:
application/json:
example:
status: 201
success: true
message: Simulated USD deposit submitted
data:
status: submitted
amount: '100'
currency: USD
reference: RL_SIM_A7CAF7AC3673
transferId: 9d56e63c-2f2f-42b3-9ef7-1852677692cf
message: >-
Simulated incoming USD transfer submitted. The balance will
be credited to the wallet via the provider webhook.
'404':
description: >-
No USD account provisioned (USD_ACCOUNT_NOT_FOUND), or endpoint
called in production.
servers:
- url: https://api-staging.rolla.xyz/api/v1/external
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: Your Rolla API key
````