Fund account wallets during testing

Put test money in a sandbox account with the deposit simulator, and when a public faucet works instead.

In sandbox, put test money in an account with the deposit simulator, Simulate a deposit. The simulator acts as the bank that sends the deposit, so the real deposit process runs, including fees, ledger entries and webhooks.

A money example. Ada's sandbox NGN account is active. You simulate a 5,000.00 NGN deposit. Gravv books it, sends transfer.inflow.completed, and the account's balance rises by 5,000.00.

Simulate a deposit

The simulator works with a sandbox key (grvSec_sandbox_…) only. A scoped key needs transfer:initiate. Each new Idempotency-Key makes a new deposit. Send amount as a string.

curl --request POST \
     --url https://api.gravv.xyz/v2/accounts/simulate/deposit \
     --header 'Api-Key: <API_KEY>' \
     --header 'Idempotency-Key: e79fe6d7-9791-49ad-bad5-a9a0f88d653b' \
     --header 'Content-Type: application/json' \
     --data '
{
  "account_id": "6f1c2a9e-3b1d-4f7a-9c62-0d8e4b7a5c11",
  "amount": "5000.00",
  "currency": "NGN"
}
'

{
  "data": {
    "accepted": true,
    "reference": "d3b07384-d9a0-4c8f-9e2b-6f1a2c3d4e5f",
    "state": "pending"
  },
  "error": null
}

accepted means Gravv received the deposit, not that it credited it. Wait for transfer.inflow.completed (or transfer.inflow.deposit_settled on a wallet-backed account), then read the account. For the full steps, see Test accounts with a simulated deposit.

Using a faucet

On sandbox wallets on EVM networks (polygon, ethereum, avalanche_c_chain), the USDC balance is the sandbox test dollar, a test token that stands for US dollars. USDC from a public faucet does not show on an account wallet on those networks. A faucet works only for standalone Stellar and Solana wallets. See Fund wallets during testing.