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. A quote_for preview is standalone — rail, payment_instructions, and from_held_balance are account-bound and cannot be combined with it.

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: ACH_STANDARD, ACH_SAME_DAY, WIRE_DOMESTIC.
payment_instructions — declare a crypto funding leg { currency, network } (account-bound quotes only).
effective_at — optional ISO 8601 timestamp (with timezone offset); prices the quote as of that time (defaults to now).
from_held_balance (default false) — price a payout from your on-book balance (account-bound quotes only; cannot be combined with payment_instructions); the response may include an advisory balance_sufficient flag.
client_markup — per-quote markup override { fixed_minor?, percentage_bps? }. Scale fixed_minor by the precision of the currency you fund with (×100 for USD, ×10⁶ for USDC/USDT); percentage_bps is 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: this itemized response shape is what POST /v1/quotations returns on the 2026-06-01 pin (and later). Versions before 2026-06-01 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-key: <api-key>' \
  --data '
{
  "virtual_account_id": "{{virtual_account_id}}",
  "amount": "1000.00",
  "target": {
    "currency": "USDC",
    "network": "polygon"
  },
  "inverse": false
}
'

import requests

url = "https://api.balampay.com/v1/quotations"

payload = {
    "virtual_account_id": "{{virtual_account_id}}",
    "amount": "1000.00",
    "target": {
        "currency": "USDC",
        "network": "polygon"
    },
    "inverse": False
}
headers = {
    "Authorization": "Bearer <token>",
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    virtual_account_id: '{{virtual_account_id}}',
    amount: '1000.00',
    target: {currency: 'USDC', network: 'polygon'},
    inverse: false
  })
};

fetch('https://api.balampay.com/v1/quotations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.balampay.com/v1/quotations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'virtual_account_id' => '{{virtual_account_id}}',
    'amount' => '1000.00',
    'target' => [
        'currency' => 'USDC',
        'network' => 'polygon'
    ],
    'inverse' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.balampay.com/v1/quotations"

	payload := strings.NewReader("{\n  \"virtual_account_id\": \"{{virtual_account_id}}\",\n  \"amount\": \"1000.00\",\n  \"target\": {\n    \"currency\": \"USDC\",\n    \"network\": \"polygon\"\n  },\n  \"inverse\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.balampay.com/v1/quotations")
  .header("Authorization", "Bearer <token>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"virtual_account_id\": \"{{virtual_account_id}}\",\n  \"amount\": \"1000.00\",\n  \"target\": {\n    \"currency\": \"USDC\",\n    \"network\": \"polygon\"\n  },\n  \"inverse\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.balampay.com/v1/quotations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"virtual_account_id\": \"{{virtual_account_id}}\",\n  \"amount\": \"1000.00\",\n  \"target\": {\n    \"currency\": \"USDC\",\n    \"network\": \"polygon\"\n  },\n  \"inverse\": false\n}"

response = http.request(request)
puts response.read_body

{
  "quote_id": "a1b2c3d4-0000-0000-0000-000000000000",
  "quote_expires_at": "2026-06-10T18:15:00.000Z",
  "source": {
    "amount": 5000000,
    "currency": "USD",
    "precision": 2
  },
  "recipient": {
    "amount": 49920000000,
    "currency": "USDC",
    "precision": 6
  },
  "pricing_context": {
    "tier": "tier_1",
    "starting_tier": "tier_1",
    "intro_period_active": false,
    "transactional_waived": false,
    "month_cumulative": 0,
    "month_cumulative_currency": "USD",
    "from_held_balance": false
  },
  "conversion": {
    "pair": "USD/USDC",
    "rate": "1.000000",
    "market_rate": "0.999700",
    "clamp": "pinned_to_peg",
    "rate_source": "kraken",
    "source_amount": 4992000,
    "source_currency": "USD",
    "target_amount": 49920000000,
    "target_currency": "USDC",
    "locked_at": "2026-06-10T18:00:00.000Z",
    "ttl_seconds": 900
  },
  "fees": [
    {
      "code": "inbound",
      "kind": "percentage",
      "charged_by": "kira",
      "status": "active",
      "version": "v1",
      "deprecated_at": null,
      "amount": 4000,
      "currency": "USD",
      "precision": 2,
      "calculation_method": "percentage",
      "rate_bps": 8,
      "basis_amount": 5000000,
      "basis_currency": "USD"
    },
    {
      "code": "wire_domestic_inbound",
      "kind": "fixed",
      "charged_by": "kira",
      "status": "active",
      "version": "v1",
      "deprecated_at": null,
      "amount": 1500,
      "currency": "USD",
      "precision": 2
    },
    {
      "code": "inbound_markup",
      "kind": "percentage",
      "charged_by": "client",
      "status": "active",
      "version": "v1",
      "deprecated_at": null,
      "amount": 2500,
      "currency": "USD",
      "precision": 2,
      "calculation_method": "percentage",
      "rate_bps": 5,
      "basis_amount": 5000000,
      "basis_currency": "USD"
    }
  ],
  "totals": {
    "kira_revenue_total": 5500,
    "client_markup_total": 2500,
    "fee_total": 8000,
    "source_net_amount": 4992000,
    "currency": "USD",
    "precision": 2
  }
}

{
  "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-06-01"

Body

application/json

Option 1
Option 2

virtual_account_id

string<uuid>

required

amount

string

required

Amount to quote, as a 2-decimal DECIMAL STRING (e.g. "1000.00"). For a virtual_account_id quote it's in the virtual account's own currency (USD for a fiat VA; USDC/USDT for a crypto VA — quoting a crypto VA returns source.currency: "USDC"). For a quote_for preview it's in quote_for.currency. When inverse: true, this is instead the desired amount the RECIPIENT should receive. Must be > 0 (the pattern rejects 0.00).

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

quote_for

object

Pre-account preview target. rail and currency must be coherent: TRON → USDT, SOLANA/POLYGON → USDC, and bank rails (ACH_STANDARD/ACH_SAME_DAY/WIRE_DOMESTIC) → USD. A mismatch returns 400.

Show child attributes

target

object

The delivery side you want the recipient to receive: currency (USD, USDC, or USDT) and, for a stablecoin, the delivery network. network is required when currency is USDC/USDT — omitting it returns 400 "network is required when currency is a stablecoin". Omit target entirely for a same-currency quote.

Show child attributes

inverse

boolean

default:false

When false (default), amount is the source amount and the engine computes what the recipient receives. When true, amount is the desired recipient amount and the engine grosses up the source amount instead. Quoting amount: "1000.00", inverse: true returned recipient.amount: 100001 ($1000.01, rounded up by 1 cent) and a grossed-up source.amount: 100081 — the recipient receives at least the requested amount.

rail

enum<string>

Optional outbound bank-rail hint, for virtual_account_id quotes only (a fiat VA accepts several rails on one account number). Adding rail: "WIRE_DOMESTIC" adds a wire_domestic_inbound line to the response fees[] that isn't present without it. Rejected with 400 when combined with quote_for — "top-level rail applies to virtual_account_id quotes only; quote_for carries its own rail".

Available options:

ACH_STANDARD,

ACH_SAME_DAY,

WIRE_DOMESTIC

payment_instructions

object

Supply to price a CRYPTO-FUNDED quote: the stablecoin (currency: USDC/USDT) and blockchain (network: solana/polygon/tron) you will deposit to fund the payout. Adding this to a quote against a FIAT virtual account prices the crypto leg (same result as quoting a crypto virtual account directly) and adds the funding network's fee line to fees[]. A USD-pegged stablecoin is priced on its USD face value (1:1), so source still reports USD with precision: 2 — conversion.pair is what names the stablecoin you deposit.

Show child attributes

effective_at

string<date-time>

Optional ISO 8601 timestamp (with timezone offset). Prices the quote as of this time; defaults to the current time.

from_held_balance

boolean

default:false

client_markup

object

Per-quote markup override that replaces your configured markup for this quote only. Provide at least one of fixed_minor (minor units of the currency you fund with) or percentage_bps (basis points) with a value greater than 0.

Show child attributes

Response

Created.

quote_id

string<uuid> | null

required

UUID of the persisted, redeemable quote. null on a quote_for (pre-account preview) quote, which is informational only; a real UUID on a virtual_account_id quote.

quote_expires_at

string

required

ISO-8601 timestamp when this quote (and its locked conversion rate) expires. Always exactly 900 seconds (15 minutes) after conversion.locked_at.

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

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-key: <api-key>' \
  --data '
{
  "virtual_account_id": "{{virtual_account_id}}",
  "amount": "1000.00",
  "target": {
    "currency": "USDC",
    "network": "polygon"
  },
  "inverse": false
}
'

import requests

url = "https://api.balampay.com/v1/quotations"

payload = {
    "virtual_account_id": "{{virtual_account_id}}",
    "amount": "1000.00",
    "target": {
        "currency": "USDC",
        "network": "polygon"
    },
    "inverse": False
}
headers = {
    "Authorization": "Bearer <token>",
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    virtual_account_id: '{{virtual_account_id}}',
    amount: '1000.00',
    target: {currency: 'USDC', network: 'polygon'},
    inverse: false
  })
};

fetch('https://api.balampay.com/v1/quotations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.balampay.com/v1/quotations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'virtual_account_id' => '{{virtual_account_id}}',
    'amount' => '1000.00',
    'target' => [
        'currency' => 'USDC',
        'network' => 'polygon'
    ],
    'inverse' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.balampay.com/v1/quotations"

	payload := strings.NewReader("{\n  \"virtual_account_id\": \"{{virtual_account_id}}\",\n  \"amount\": \"1000.00\",\n  \"target\": {\n    \"currency\": \"USDC\",\n    \"network\": \"polygon\"\n  },\n  \"inverse\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.balampay.com/v1/quotations")
  .header("Authorization", "Bearer <token>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"virtual_account_id\": \"{{virtual_account_id}}\",\n  \"amount\": \"1000.00\",\n  \"target\": {\n    \"currency\": \"USDC\",\n    \"network\": \"polygon\"\n  },\n  \"inverse\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.balampay.com/v1/quotations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"virtual_account_id\": \"{{virtual_account_id}}\",\n  \"amount\": \"1000.00\",\n  \"target\": {\n    \"currency\": \"USDC\",\n    \"network\": \"polygon\"\n  },\n  \"inverse\": false\n}"

response = http.request(request)
puts response.read_body

{
  "quote_id": "a1b2c3d4-0000-0000-0000-000000000000",
  "quote_expires_at": "2026-06-10T18:15:00.000Z",
  "source": {
    "amount": 5000000,
    "currency": "USD",
    "precision": 2
  },
  "recipient": {
    "amount": 49920000000,
    "currency": "USDC",
    "precision": 6
  },
  "pricing_context": {
    "tier": "tier_1",
    "starting_tier": "tier_1",
    "intro_period_active": false,
    "transactional_waived": false,
    "month_cumulative": 0,
    "month_cumulative_currency": "USD",
    "from_held_balance": false
  },
  "conversion": {
    "pair": "USD/USDC",
    "rate": "1.000000",
    "market_rate": "0.999700",
    "clamp": "pinned_to_peg",
    "rate_source": "kraken",
    "source_amount": 4992000,
    "source_currency": "USD",
    "target_amount": 49920000000,
    "target_currency": "USDC",
    "locked_at": "2026-06-10T18:00:00.000Z",
    "ttl_seconds": 900
  },
  "fees": [
    {
      "code": "inbound",
      "kind": "percentage",
      "charged_by": "kira",
      "status": "active",
      "version": "v1",
      "deprecated_at": null,
      "amount": 4000,
      "currency": "USD",
      "precision": 2,
      "calculation_method": "percentage",
      "rate_bps": 8,
      "basis_amount": 5000000,
      "basis_currency": "USD"
    },
    {
      "code": "wire_domestic_inbound",
      "kind": "fixed",
      "charged_by": "kira",
      "status": "active",
      "version": "v1",
      "deprecated_at": null,
      "amount": 1500,
      "currency": "USD",
      "precision": 2
    },
    {
      "code": "inbound_markup",
      "kind": "percentage",
      "charged_by": "client",
      "status": "active",
      "version": "v1",
      "deprecated_at": null,
      "amount": 2500,
      "currency": "USD",
      "precision": 2,
      "calculation_method": "percentage",
      "rate_bps": 5,
      "basis_amount": 5000000,
      "basis_currency": "USD"
    }
  ],
  "totals": {
    "kira_revenue_total": 5500,
    "client_markup_total": 2500,
    "fee_total": 8000,
    "source_net_amount": 4992000,
    "currency": "USD",
    "precision": 2
  }
}

{
  "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

RFIs

Create a quotation

Authorizations

Headers

Body

Response