Quotations

Overview

Quotations (quotes) provide real-time exchange rate calculations including all applicable fees and markups. Before creating a payout, you should create a quote to know exactly how much the recipient will receive.

Prerequisites

• You have authenticated and obtained an access token (Getting Started)
• You have your API credentials ready

Quote Lifecycle

graph LR
    A[Create Quote] --> B[Quote Active]
    B --> C{Within 10 min?}
    C -->|Yes| D[Use in Payout]
    C -->|No| E[Quote Expired]
    D --> F[Quote Used]
    E --> G[Create New Quote]

Guides in This Section

Quotation Guide

Quotation Guide

Learn how to:

• Create quotes for different currency pairs
• Understand fee breakdowns
• Use stablecoin networks
• Handle inverse calculations (amount in destination)

Key endpoints:

• POST /v1/quotations - Create a new quote

Supported Currencies

Base Currencies (Source)

Quote Currencies (Destination)

Quick Example

Create a Quote (USD to MXN)

curl -X POST https://api.balampay.com/v1/quotations \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base_currency": "USD",
    "quote_currency": "MXN",
    "amount": 1000.00
  }'

Response

{
  "data": {
    "quote_id": "550e8400-e29b-41d4-a716-446655440000",
    "base_amount": 1000.00,
    "base_currency": "USD",
    "quote_amount": 19110.00,
    "quote_currency": "MXN",
    "account_type": "SPEI",
    "rate": 19.80,
    "kira_rate": 19.62,
    "expiration_ts": "2026-02-03T12:15:00.000Z",
    "status": "ACTIVE",
    "fees": {
      "total_fees": 25.00
    }
  }
}

Key Concepts

Quote Expiration

All quotes expire 10 minutes after creation. You must use the quote in a payout before it expires. If a quote expires, create a new one.

Fees & Rates

• Commercial Rate (rate): The market exchange rate
• Kira Rate (kira_rate): The effective rate after all markups
• Fees: Fixed fees + percentage fees deducted from the amount

Stablecoin Networks

When using USDC or USDT as base currency, specify the network:

HTTP Status Codes

Next Steps

After creating a quote:

1. Create a Payout - Use the quote to send funds
2. Set up Webhooks - Track payout status

Support

• Email: [email protected]
• Full Quotation Guide: quotations.md