Virtual Accounts

Create a liquidation address

Create a liquidation address on a virtual account: a per-account crypto deposit address that automatically converts incoming stablecoin deposits (USDC/USDT) to USD and pays them out to a configured bank recipient (an off-ramp). Supported only for US_BANK virtual accounts in active status.

Required header: Idempotency-Key (a UUID). Replaying the same key returns the original result instead of creating a duplicate.

Request body

network — solana, polygon, or tron; token — USDC or USDT. Only these combinations are allowed: USDC on Solana or Polygon, USDT on Polygon or Tron. USDT on Solana is rejected.
recipient — a discriminated union on type (individual requires first_name/last_name; business requires company_name), each containing an account object keyed by account_type (ACH, WIRE, or SWIFT). For SWIFT, recipient.email is required.
markup (optional) — your added margin { fixed?, percentage?, fx? } as decimal strings (up to 4 decimals).

The response (201) returns the address id (prefixed liq_), the on-chain deposit address, the resolved recipient (with the account number masked to the last 4 digits), the wallet, and any markup.

Errors: 400 for an unsupported network/token combination or a non-eligible virtual account; 409 if a liquidation address already exists for that bank account on the virtual account.

Example response (201):

{
  "id": "liq_550e8400-e29b-41d4-a716-446655440000",
  "virtual_account_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "status": "active",
  "network": "polygon",
  "token": "USDC",
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "recipient": {
    "id": "rec_3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "type": "individual",
    "name": "Jane Doe",
    "account_type": "ACH",
    "bank_name": "Example Bank",
    "account_number_last4": "7890"
  },
  "wallet": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "network": "polygon"
  },
  "markup": {
    "fixed": "1.50",
    "percentage": "0.25",
    "fx": "0.10"
  },
  "created_at": "2026-06-25T12:00:00.000Z"
}

POST

virtual-accounts

{virtual_account_id}

liquidation-address

Create a liquidation address

curl --request POST \
  --url https://api.balampay.com/v1/virtual-accounts/{virtual_account_id}/liquidation-address \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Api-Version: <x-api-version>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "network": "polygon",
  "token": "USDC",
  "recipient": {
    "type": "individual",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "account": {
      "account_type": "ACH",
      "routing_number": "021000021",
      "account_number": "1234567890",
      "type": "checking",
      "doc_type": "SSN",
      "doc_number": "123-45-6789",
      "bank_name": "Example Bank",
      "bank_address": "123 Market St, New York, NY"
    }
  },
  "markup": {
    "fixed": "1.50",
    "percentage": "0.25",
    "fx": "0.10"
  }
}
'

{
  "code": "<string>",
  "message": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

Authorizations

Authorization

string

header

required

Access token from POST /auth (the data.access_token value).

x-api-key

string

header

required

API key issued by Kira. Required on every request, including /auth.

Headers

X-Api-Version

string

required

Example:

"2026-04-14"

Idempotency-Key

string

required

Example:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

Path Parameters

virtual_account_id

string<uuid>

required

Virtual account UUID.

Body

application/json

The body is of type object.

Response

Success.

Simulate a deposit (sandbox)Returns `201` + `deposit_id` + `status: "completed"`. **The simulated deposit will NOT appear in `GET /v1/virtual-accounts/{id}/deposits` and will NOT change `GET /…/balance`** (the sandbox balance is a fixed provider value). Confirm via the `201` response itself + the (hand-delivered) `virtual_account.deposit_funds_received` webhook. `settlement_triggered: false` on a fiat deposit is normal, not an error.

⌘I

Create a liquidation address

curl --request POST \
  --url https://api.balampay.com/v1/virtual-accounts/{virtual_account_id}/liquidation-address \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Api-Version: <x-api-version>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "network": "polygon",
  "token": "USDC",
  "recipient": {
    "type": "individual",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "account": {
      "account_type": "ACH",
      "routing_number": "021000021",
      "account_number": "1234567890",
      "type": "checking",
      "doc_type": "SSN",
      "doc_number": "123-45-6789",
      "bank_name": "Example Bank",
      "bank_address": "123 Market St, New York, NY"
    }
  },
  "markup": {
    "fixed": "1.50",
    "percentage": "0.25",
    "fx": "0.10"
  }
}
'

{
  "code": "<string>",
  "message": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}