Quotations

Create a quotation

Create a quotation: a priced, itemized fee envelope for a prospective payment. A quotation can optionally be persisted as a redeemable quote_id that locks the fees and FX rate so a later payout settles at the quoted price. All monetary amounts are returned as integer minor units paired with an explicit precision (e.g. 100000 at precision 2 is 1000.00).

Provide exactly one of:

virtual_account_id — price against an existing virtual account (the account pins the funding direction, source currency, and network). This persists the quote and returns a real quote_id you can redeem on a payout.
quote_for — a pre-account preview ({ rail, currency }) that does not persist and returns quote_id: null.

Sending both, or neither, returns 400.

Key request fields:

amount (required) — a positive two-decimal string, e.g. "1000.00".
target — destination { currency, network? }. currency is one of USD, USDC, USDT; network (solana, polygon, tron) is required when the target currency is a stablecoin.
inverse (default false) — when true, amount is the desired recipient amount and the engine back-solves the source amount.
rail — bank-rail hint for account-bound quotes: FEDNOW, ACH_STANDARD, ACH_SAME_DAY, WIRE_DOMESTIC, WIRE_SWIFT.
payment_instructions — declare a crypto funding leg { currency, network } (account-bound quotes only).
from_held_balance (default false) — price a payout from your on-book balance; the response may include an advisory balance_sufficient flag.
client_markup — per-quote markup override { fixed_minor?, percentage_bps? } (cents and basis points). Replaces your configured markup for this quote only.

Response returns source and recipient money objects, a pricing_context, a depeg-aware conversion block, an itemized fees[] array (each line carries code, kind "fixed"/"percentage", charged_by "kira"/"client", status, signed amount), and totals. The quote expires at quote_expires_at (default TTL 15 minutes).

Errors: 400 validation_error or fees_exceed_amount; 401 unauthorized; 404 for an unknown or foreign virtual account.

Note: the itemized response shape requires pinning to API version 2026-06-01 or later. Older versions return a simpler preview shape.

POST

quotations

Create a quotation

curl --request POST \
  --url https://api.balampay.com/v1/quotations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Version: <x-api-version>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "virtual_account_id": "{{virtual_account_id}}",
  "amount": "1000.00",
  "target": {
    "currency": "USDC",
    "network": "polygon"
  },
  "inverse": false
}
'

{
  "quote_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "quote_expires_at": "<string>",
  "source": {
    "amount": 1,
    "currency": "<string>",
    "precision": 1
  },
  "recipient": {
    "amount": 1,
    "currency": "<string>",
    "precision": 1
  },
  "pricing_context": {
    "intro_period_active": true,
    "transactional_waived": true,
    "month_cumulative": 1,
    "month_cumulative_currency": "<string>",
    "from_held_balance": true
  },
  "conversion": {
    "pair": "<string>",
    "rate": "<string>",
    "source_amount": 1,
    "source_currency": "<string>",
    "target_amount": 1,
    "target_currency": "<string>",
    "market_rate": "<string>",
    "locked_at": "<string>",
    "ttl_seconds": 123
  },
  "fees": [
    {
      "code": "<string>",
      "version": "<string>",
      "deprecated_at": "<string>",
      "amount": 1,
      "currency": "<string>",
      "precision": 1,
      "kind": "fixed"
    }
  ],
  "totals": {
    "kira_revenue_total": 1,
    "client_markup_total": 1,
    "fee_total": 1,
    "source_net_amount": 1,
    "currency": "<string>",
    "precision": 1
  },
  "balance_sufficient": true
}

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"

Body

application/json

Option 1
Option 2

virtual_account_id

string<uuid>

required

amount

string

required

Must be > 0 (pattern excludes 0.00 / 00.00 / etc).

Pattern: ^(?!0+\.0+$)\d+\.\d{2}$

quote_for

object

Show child attributes

target

object

Show child attributes

inverse

boolean

default:false

rail

enum<string>

Available options:

FEDNOW,

ACH_STANDARD,

ACH_SAME_DAY,

WIRE_DOMESTIC,

WIRE_SWIFT

payment_instructions

object

Show child attributes

effective_at

string<date-time>

from_held_balance

boolean

default:false

client_markup

object

Show child attributes

Response

Created.

quote_id

string<uuid> | null

required

quote_expires_at

string

required

source

object

required

Show child attributes

recipient

object

required

Show child attributes

pricing_context

object

required

Show child attributes

conversion

object

required

Show child attributes

fees

object[]

required

Option 1
Option 2

Show child attributes

totals

object

required

Show child attributes

balance_sufficient

boolean

Preview a payout

⌘I

Create a quotation

curl --request POST \
  --url https://api.balampay.com/v1/quotations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Version: <x-api-version>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "virtual_account_id": "{{virtual_account_id}}",
  "amount": "1000.00",
  "target": {
    "currency": "USDC",
    "network": "polygon"
  },
  "inverse": false
}
'

{
  "quote_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "quote_expires_at": "<string>",
  "source": {
    "amount": 1,
    "currency": "<string>",
    "precision": 1
  },
  "recipient": {
    "amount": 1,
    "currency": "<string>",
    "precision": 1
  },
  "pricing_context": {
    "intro_period_active": true,
    "transactional_waived": true,
    "month_cumulative": 1,
    "month_cumulative_currency": "<string>",
    "from_held_balance": true
  },
  "conversion": {
    "pair": "<string>",
    "rate": "<string>",
    "source_amount": 1,
    "source_currency": "<string>",
    "target_amount": 1,
    "target_currency": "<string>",
    "market_rate": "<string>",
    "locked_at": "<string>",
    "ttl_seconds": 123
  },
  "fees": [
    {
      "code": "<string>",
      "version": "<string>",
      "deprecated_at": "<string>",
      "amount": 1,
      "currency": "<string>",
      "precision": 1,
      "kind": "fixed"
    }
  ],
  "totals": {
    "kira_revenue_total": 1,
    "client_markup_total": 1,
    "fee_total": 1,
    "source_net_amount": 1,
    "currency": "<string>",
    "precision": 1
  },
  "balance_sufficient": true
}