Skip to main content

Simulate USD Deposit (Sandbox)

In sandbox, USD deposits and payouts are simulated end-to-end — you do not need to send a real wire transfer to finish the flow. This page explains how the simulation works so you can run the full USD → crypto → USD journey without touching real rails.

info

This behavior is sandbox only. In production the sender must actually wire the funds to the account details returned at ticket creation for the ticket to move beyond UNPAID.

What happens when you create a USD ticket in sandbox​

  1. Quote + ticket — you call GET /v2/account/quote/fixed-rate and then POST /v2/account/tickets/ exactly like in production. The flow is identical from an API consumer perspective.
  2. Deposit instructions — the ticket response includes a usdDepositInstructions block with the account number, routing number, bank details and a depositMessage. In sandbox these are mock values and will never receive a real wire; the bankAccountNumber and depositMessage are unique per ticket, the remaining fields are fixed.
  3. Auto-settlement (async) — the sandbox advances the deposit through its lifecycle on its own, as if the wire had arrived and cleared, and feeds the resulting events into the same processing pipeline production uses.
  4. Ticket lifecycle completes — the ticket transitions UNPAID → PROCESSING → PAID, mock tokens are credited, and the usual TICKET-CREATED, DEPOSIT-PROCESSING, DEPOSIT-SUCCESS and TICKET-COMPLETE webhooks fire, matching production.

Settlement takes about a minute from ticket creation. Nothing is required from you in between — there is no endpoint to call to push the deposit forward.

Amount limits​

The USD simulation has no amount cap — it fires for any ticket. Your account's own KYC/KYB limits still apply exactly as in production, so a deposit above your configured limit fails the same way it would live.

Example​

1. Quote​

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate?inputCurrency=USD&inputPaymentMethod=WIRE&inputAmount=150&outputCurrency=USDC&outputPaymentMethod=INTERNAL&inputThirdParty=false&outputThirdParty=false&blockchainSendMethod=PERMIT" \
  -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

2. Ticket​

USD payins take no rail-specific ticket block — there is no sender account to declare.

curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/tickets/" \
  -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteToken": "eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "ticketBlockchainOutput": {
      "walletAddress": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
      "walletChain": "POLYGON"
    }
  }'

Sample response:

{
  "id": "46573ffc-2ca1-4715-9c2f-1594b62ec853",
  "expiration": "2026-09-14T12:22:13.308963961Z",
  "usdDepositInstructions": {
    "accountHolderName": "BRLA",
    "bankAccountNumber": "227247550465",
    "bankRoutingNumber": "101019644",
    "accountType": "CHECKING",
    "bankName": "Lead Bank",
    "bankAddress": "1801 Main St., Kansas City, MO 64108",
    "depositMessage": "UYW0Y17EKE9VXL19UYW0",
    "paymentRail": "WIRE"
  }
}

3. Poll the ticket​

Nothing else is required. Poll the ticket until it reports PAID:

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/tickets/46573ffc-2ca1-4715-9c2f-1594b62ec853" \
  -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

You should see the status transition from UNPAID → PROCESSING → PAID.

Simulating USD payouts​

Crypto → USD payouts are simulated as well, and take about the same minute to settle.

1. Register a USD beneficiary​

curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/usd/" \
  -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "my-usd-account",
    "bankAccountNumber": "12345678901",
    "bankRoutingNumber": "021000021",
    "bankBeneficiaryName": "Jane Doe",
    "bankName": "JPMorgan Chase",
    "beneficiaryAddress": {
      "streetLine1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "USA"
    }
  }'

2. Quote and create the payout ticket​

Quote with inputCurrency=USDC, inputPaymentMethod=INTERNAL, outputCurrency=USD and outputPaymentMethod=WIRE, then reference the beneficiary through ticketUsdOutput.beneficiaryUsdBankAccountId:

curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/tickets/" \
  -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteToken": "eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "ticketUsdOutput": {
      "beneficiaryUsdBankAccountId": "0e737c6a-d524-4f94-8516-93fe8dbd9587"
    }
  }'

No real payout is executed and no real USD leaves the account. Poll the ticket until it reports PAID.

tip

Need USDC to test a payout with? Run a USD deposit first, or see Receive Mock Funds to fund the balance through PIX.

What is not simulated​

The following still behave exactly as production would:

  • KYC/KYB approval for new accounts, including USD KYC and USD KYB
  • Account limit consumption on both the deposit and the payout
  • Beneficiary field validation (routing number format, required address fields)

If any of those return an unexpected error in sandbox, it reflects a real issue — not the simulation.