Quotations

Create a quotation

Create a quotation for a prospective payout and reserve a redeemable quote. A quotation prices the payout the same way POST /v1/virtual-accounts/{virtual_account_id}/payout/preview does — reusing the three payout calculation flows — but does not require a virtual account and always persists a quote. The response returns quote_id and quote_expires_at; redeem the quote_id on a payout to settle at the exact quoted amount, fees, and FX rate. The default quote lifespan is 15 minutes.

All monetary amounts are USD decimal strings (e.g. "1000.00").

Identify the destination with exactly one of:

recipient_id — a saved recipient (WIRE, ACH, or WALLET).
account_type — the rail (WIRE | ACH | WALLET) to price without a saved recipient. When account_type is WALLET and no recipient_id is given, wallet_network and wallet_token are also required.

Send at least one; if both are sent, recipient_id takes precedence.

The flow is auto-detected from the request:

Fiat-to-bank — a WIRE/ACH destination; omit payment_instructions. recipient_currency is USD.
Crypto-funded (crypto-to-bank) — supply payment_instructions (the stablecoin/network you deposit to fund the payout); recipient_currency is USD.
Fiat-to-crypto — a WALLET destination; the recipient receives stablecoins and recipient_currency is USDC or USDT.

Key request fields:

amount (required) — positive USD decimal string.
inverse_calculation (default false) — when true, amount is the desired recipient amount and the engine back-solves the source amount.
client_markup — per-quote markup override { fixed_fee, percentage_fee, fx_markup? } as decimal strings (percentage_fee is 0–1, e.g. 0.01 = 1%). Replaces your configured markup for this quote only.

Response returns the source amount/currency, the recipient_amount/recipient_currency, an aggregated fees breakdown (base fees, your markup, network fee, optional FX detail, and totals), and the reserved quote_id / quote_expires_at.

Errors: 400 validation_error (request failed schema validation) or bad_request (e.g. "Total fees exceed or equal the payout amount", returned when amount is below the rail minimum); 401 unauthorized; 404 not_found for an unknown recipient or client.

Note: this is the 2026-04-14 preview-shape quotation. The line-by-line itemized fee envelope — integer minor units, pricing_context, depeg-aware conversion, and an itemized fees[] array — requires pinning API version 2026-06-01 or later. See the Itemized quotations guide.

POST

quotations

curl --request POST \
  --url https://api.balampay.com/v1/quotations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "amount": "1000.00",
  "recipient_id": "{{recipient_id}}"
}
'

{
  "amount": "1000.00",
  "currency": "USD",
  "fees": {
    "base_fees": {
      "bank_account_fee": "5.00",
      "bank_account_fee_percentage": "0.005",
      "fixed_fee": "5.00",
      "percentage_fee": "5.00",
      "total": "10.00"
    },
    "client_markup": {
      "fixed_fee": "0.00",
      "percentage_fee": "2.50",
      "total": "2.50"
    },
    "network_fee": "0.00",
    "total_fees": "12.50",
    "total": "12.50"
  },
  "recipient_amount": "987.50",
  "recipient_currency": "USD",
  "quote_id": "a1b2c3d4-0000-0000-0000-000000000000",
  "quote_expires_at": "2026-04-14T18:15:00.000Z"
}

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

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

Changed in this version.

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

Optional. The date-versioned API version to apply for this request (e.g. 2026-04-14). When sent it always wins, even over your pinned account default. When omitted, the API uses your account's pinned version if set, otherwise a baseline default.

Example:

"2026-04-14"

Body

application/json

Create-quotation request (API version 2026-04-14). Prices a prospective payout and always reserves a redeemable quote. Identify the destination with exactly one of recipient_id or account_type — send at least one (if both are sent, recipient_id wins). There is no top-level currency: payouts are always priced in USD. Unknown fields are ignored.

amount

string

required

Positive USD decimal amount, e.g. "1000.00". Up to 2 decimals for fiat and fiat-to-crypto flows; up to 8 decimals for crypto-funded flows (payment_instructions supplied), which are rounded down to 2 decimals when your account has high-precision round-down enabled. When inverse_calculation is true, this is instead the amount the recipient should receive.

Example:

"1000.00"

recipient_id

string<uuid>

UUID of a saved recipient (WIRE, ACH, or WALLET). Provide this or account_type. The recipient's rail and — for a WALLET recipient — its network/token drive the pricing.

account_type

enum<string>

Rail to price against without a saved recipient. Provide this instead of recipient_id. When WALLET (and no recipient_id), wallet_network and wallet_token are also required.

Available options:

WIRE,

WALLET,

ACH

wallet_network

enum<string>

Destination network for a fiat-to-crypto quote. Required when account_type is WALLET without a recipient_id.

Available options:

solana,

polygon,

tron

wallet_token

enum<string>

Destination stablecoin for a fiat-to-crypto quote. Required with wallet_network. Note: tron does not support USDC.

Available options:

USDC,

USDT

inverse_calculation

boolean

default:false

When true, treat amount as the amount the recipient should receive and back-solve the source amount. The recipient receives at least the requested amount (rounding may deliver up to one minor unit more, never less).

payment_instructions

object

Supply to price a crypto-funded payout — the stablecoin and network you will deposit to fund it. Omit for a fiat-funded payout.

Show child attributes

client_markup

object

Override your account-configured markup for this quote only. Values are decimal strings (this is the 2026-04-14 shape — not the integer cents/bps of the 2026-06-01 itemized envelope).

Show child attributes

Response

Created. The quotation was priced and a quote reserved.

Create-quotation response (API version 2026-04-14). Mirrors the payout preview and always carries a redeemable quote_id. All monetary values are decimal strings — not the integer minor units of the 2026-06-01 itemized envelope. Redeem quote_id on POST /v1/virtual-accounts/{virtual_account_id}/payout to settle at the quoted amount, fees, and rate before it expires.

amount

string

required

Source amount in USD, 2 decimals.

currency

string

required

Always USD.

Example:

"USD"

fees

object

required

The fee breakdown, all values USD decimal strings. fees.total and fees.total_fees are identical (documented duplicate — use either).

Show child attributes

recipient_amount

string

required

Amount the recipient receives after fees. USD with 2 decimals for bank rails; the stablecoin amount with up to 6 decimals for fiat-to-crypto.

recipient_currency

string

required

USD for bank rails; USDC/USDT for fiat-to-crypto.

quote_id

string<uuid>

required

The reserved quote. Redeem it on POST /v1/virtual-accounts/{virtual_account_id}/payout to lock the quoted amount, fees, and rate. Single-use; the quote must belong to the same client and not be expired or already redeemed.

quote_expires_at

string

required

ISO-8601 expiry. Default quote lifespan is 15 minutes; re-quote if it lapses.

payment_instructions

object

Echoed back only when the request supplied it.

Show child attributes

curl --request POST \
  --url https://api.balampay.com/v1/quotations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "amount": "1000.00",
  "recipient_id": "{{recipient_id}}"
}
'

{
  "amount": "1000.00",
  "currency": "USD",
  "fees": {
    "base_fees": {
      "bank_account_fee": "5.00",
      "bank_account_fee_percentage": "0.005",
      "fixed_fee": "5.00",
      "percentage_fee": "5.00",
      "total": "10.00"
    },
    "client_markup": {
      "fixed_fee": "0.00",
      "percentage_fee": "2.50",
      "total": "2.50"
    },
    "network_fee": "0.00",
    "total_fees": "12.50",
    "total": "12.50"
  },
  "recipient_amount": "987.50",
  "recipient_currency": "USD",
  "quote_id": "a1b2c3d4-0000-0000-0000-000000000000",
  "quote_expires_at": "2026-04-14T18:15:00.000Z"
}

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

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

Authentication

Versioning

Users

Virtual Accounts

Quotations

Payouts

Recipients

Reference

Create a quotation

Authorizations

Headers

Body

Response