Skip to main content

Wallets & vIBANs

CashXChain uses a wallet abstraction to present balances without requiring end users to manage private keys or understand blockchain infrastructure. A wallet in the API is a logical balance container scoped to a customer and currency.

Balance model​

Balance typeMeaning
availableFunds immediately usable for payments.
pendingFunds expected but not yet final (incoming transfers in transit).
reservedFunds held for pending outbound payments, fee reserves, or FX quote locks.
restrictedFunds that cannot move — compliance hold, account restriction, or partner limitation.

GET /v1/accounts/me/balance​

Returns the caller's balance breakdown across all currencies.

Auth: Elevated — JWT or master key only.

GET /v1/accounts/me/balance
Authorization: Bearer <token>
{
  "totals": [
    { "currency": "USD",  "amount": "1000.00", "available": "1000.00", "pending": "0.00" },
    { "currency": "USDC", "amount": "50.00",   "available": "50.00",   "pending": "0.00" }
  ]
}

Virtual IBANs (vIBANs)​

A vIBAN is a dedicated bank account number issued to a customer by a payment partner (e.g. Veem). Customers can receive fiat wire transfers to their vIBAN, which credits their CashXChain balance.

vIBANs carry full bank routing metadata: IBAN number, BIC/SWIFT, sort codes, or ACH routing numbers depending on the currency and jurisdiction.

POST /v1/customers/{id}/vibans — Create vIBAN​

Provisions a vIBAN for a customer via a specified partner. The backend submits the application and polls the partner until the vIBAN is approved (up to 10 attempts with 500ms backoff).

Auth: Elevated — JWT or master key only.
Header: Idempotency-Key: <unique-string> — required.

POST /v1/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6/vibans
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: viban-usd-2026-001
{
  "partner": "veem",
  "currency": "USD",
  "display_name": "USD Receiving Account"
}

If the partner has not finished provisioning within the polling window, the API returns 202 Accepted with an application_id. Poll GET /v1/customers/:id/vibans to check status.

GET /v1/customers/{id}/vibans — List vIBANs​

Lists all vIBANs provisioned for a customer.

Auth: Elevated — JWT or master key only.

GET /v1/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6/vibans
Authorization: Bearer <token>

GET /v1/customers/{id}/vibans/{viban_id} — Get vIBAN​

Returns full detail for a single vIBAN including bank routing numbers.

Auth: Elevated — JWT or master key only.

GET /v1/customers/:id/vibans/:viban_id
Authorization: Bearer <token>

GET /v1/customers/{id}/vibans/{viban_id}/balance — vIBAN balance​

Returns the balance held at the partner for this specific vIBAN.

Auth: Elevated — JWT or master key only.

GET /v1/customers/{id}/vibans/{viban_id}/transactions — vIBAN transactions​

Returns the transaction history for a vIBAN.

Auth: Elevated — JWT or master key only.

GET /v1/customers/{id}/wallet — Crypto wallet​

Returns the customer's crypto wallet information (Solana address, Coinbase CDP link).

Auth: Elevated — JWT or master key only.

GET /v1/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6/wallet
Authorization: Bearer <token>

GET /v1/accounts/me/vibans — Caller's vIBANs​

Shortcut to list all vIBANs for the account associated with the calling credential.

Auth: Elevated — JWT or master key only.

Sandbox faucet​

In sandbox, use the faucet to credit test balances:

POST /v1/sandbox/faucet
Authorization: Bearer <jwt>
Content-Type: application/json
{
  "currency": "USD",
  "amount": "10000.00"
}

The faucet is only available when APP_ENV=sandbox and requires a valid JWT.

Crypto rails​

USDC and EURC transfers route via Coinbase CDP on Solana. Before sending USDC/EURC:

  1. Ensure the sender has a Solana wallet provisioned (GET /v1/customers/:id/wallet).
  2. Validate the recipient address: GET /v1/utility/validate-address?address=<addr>&chain=solana&asset=USDC.
  3. If ata_exists=false, the first transfer will create the recipient's token account — the ~0.002 SOL rent is deducted from the transaction.