Quotation Guide

Overview

Quotations provide real-time exchange rate calculations for cross-border payments. A quote includes the exchange rate, all applicable fees, and the exact amount the recipient will receive.

Create a Quote

Endpoint

POST /v1/quotations

Headers

Header	Required	Description
`Authorization`	Yes	Bearer token from authentication
`x-api-key`	Yes	Your API key
`Content-Type`	Yes	Must be `application/json`

Request Body

{
  "base_currency": "USD",
  "quote_currency": "MXN",
  "amount": 1000.00,
  "amount_in_destination": false,
  "account_type": "SPEI",
  "network": "solana"
}

Request Fields

Field	Type	Required	Description
`base_currency`	string	No	Source currency. Defaults to `"USD"`. Valid: `USD`, `USDC`, `USDT`
`quote_currency`	string	Yes	Target currency (see supported currencies below)
`amount`	number	Yes	Amount to convert (must be positive)
`amount_in_destination`	boolean	No	If `true`, `amount` is the destination amount. Defaults to `false`
`account_type`	string	No	Payment rail. Defaults based on currency
`network`	string	No	Blockchain network for stablecoins (USDC/USDT only)

Example Request

curl -X POST https://api.balampay.com/v1/quotations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_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": {
      "base_fees": {
        "fixed_fee": 5.00,
        "percentage_fee": 10.00,
        "fx_markup": 0.005
      },
      "client_markup": {
        "fixed_fee": 2.50,
        "percentage_fee": 5.00,
        "fx_markup": 0.003
      },
      "network_fee": 0.00,
      "penalty_markup": 0.00,
      "total_fees": 22.50
    }
  }
}

Response Fields

Field	Description
`quote_id`	Unique identifier for the quote
`base_amount`	Amount in source currency
`base_currency`	Source currency code
`quote_amount`	Amount recipient will receive
`quote_currency`	Destination currency code
`account_type`	Payment rail used
`rate`	Commercial exchange rate
`kira_rate`	Effective rate after all markups
`expiration_ts`	Quote expiration timestamp (10 minutes from creation)
`status`	Quote status (`ACTIVE`, `EXPIRED`, `USED`)
`fees`	Detailed fee breakdown
`network`	Blockchain network (stablecoins only)

Supported Currencies

Base Currencies

Currency	Description	Networks
`USD`	US Dollar	N/A
`USDC`	USD Coin	Solana (default), Polygon
`USDT`	Tether	Tron (default), Polygon

Quote Currencies

Currency	Region	Default Account Type	Valid Account Types
`MXN`	Mexico	SPEI	SPEI
`COP`	Colombia	PSE	PSE, WALLET
`ARS`	Argentina	ARS	ARS
`BRL`	Brazil	BRL	BRL
`CLP`	Chile	CLP	CLP
`PEN`	Peru	PEN	PEN
`UYU`	Uruguay	UYU	UYU
`GTQ`	Guatemala	GTQ	GTQ
`CRC`	Costa Rica	CRC	CRC
`DOP`	Dominican Republic	DOP	DOP
`PYG`	Paraguay	PYG	PYG
`USD`	United States	ACH	ACH, WIRE, SWIFT, PEUSD, ECUSD, PAUSD, SVUSD
`USDC`	Global	WALLET	WALLET
`USDT`	Global	WALLET	WALLET

Stablecoin Networks

When using USDC or USDT as the base currency, you can specify which blockchain network to use.

USDC Networks

Network	Description
`solana`	Solana blockchain (default)
`polygon`	Polygon (Matic) blockchain

USDT Networks

Network	Description
`tron`	Tron blockchain (default)
`polygon`	Polygon (Matic) blockchain

Example: USDC Quote with Specific Network

curl -X POST https://api.balampay.com/v1/quotations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base_currency": "USDC",
    "quote_currency": "MXN",
    "amount": 500.00,
    "network": "polygon"
  }'

Response with Network

{
  "data": {
    "quote_id": "550e8400-e29b-41d4-a716-446655440000",
    "base_amount": 500.00,
    "base_currency": "USDC",
    "quote_amount": 9750.00,
    "quote_currency": "MXN",
    "account_type": "SPEI",
    "network": "polygon",
    "rate": 19.80,
    "kira_rate": 19.62,
    "expiration_ts": "2026-02-03T12:15:00.000Z",
    "status": "ACTIVE",
    "fees": {
      "network_fee": 1.00,
      "total_fees": 15.00
    }
  }
}

Account Types

The account_type parameter specifies which payment rail to use. If not provided, it defaults based on the quote currency.

USD Account Types

When quote_currency is USD, you can choose from multiple rails:

Account Type	Description
`ACH`	US domestic bank transfer (default)
`WIRE`	US domestic wire transfer
`SWIFT`	International wire transfer
`PEUSD`	USD in Peru
`ECUSD`	USD in Ecuador
`PAUSD`	USD in Panama
`SVUSD`	USD in El Salvador

Example: USD Quote with WIRE

curl -X POST https://api.balampay.com/v1/quotations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base_currency": "USD",
    "quote_currency": "USD",
    "amount": 5000.00,
    "account_type": "WIRE"
  }'

Inverse Calculation

Use amount_in_destination: true when you know how much the recipient should receive and need to calculate how much to send.

Example: Specify Destination Amount

curl -X POST https://api.balampay.com/v1/quotations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base_currency": "USD",
    "quote_currency": "MXN",
    "amount": 20000.00,
    "amount_in_destination": true
  }'

Response

{
  "data": {
    "quote_id": "550e8400-e29b-41d4-a716-446655440000",
    "base_amount": 1045.00,
    "base_currency": "USD",
    "quote_amount": 20000.00,
    "quote_currency": "MXN",
    "kira_rate": 19.62,
    "status": "ACTIVE"
  }
}

In this example:

You specified you want the recipient to receive 20,000 MXN
The API calculated you need to send 1,045 USD

Fee Structure

Fee Components

Component	Description
`base_fees.fixed_fee`	Platform fixed fee
`base_fees.percentage_fee`	Platform percentage fee (in base currency)
`base_fees.fx_markup`	Platform FX markup
`client_markup.fixed_fee`	Client-specific fixed fee
`client_markup.percentage_fee`	Client-specific percentage fee
`client_markup.fx_markup`	Client-specific FX markup
`network_fee`	Blockchain network fee (stablecoins only)
`penalty_markup`	Off-hours or holiday surcharge
`total_fees`	Sum of all fees

Fee Calculation

Total Fixed Fee = base_fees.fixed_fee + client_markup.fixed_fee + network_fee
Total Percentage Fee = (base_fees.percentage_fee + client_markup.percentage_fee) as rate

Amount After Fees = base_amount - Total Fixed Fee - (base_amount × Total Percentage Fee)
Quote Amount = Amount After Fees × kira_rate

Penalty Markup

Additional FX markup may apply during:

Off-hours: Evening and weekend hours (America/New_York timezone)
Holidays: Specific holiday dates

The penalty markup is automatically calculated and included in the quote.

Quote Expiration

All quotes expire 10 minutes after creation.

Status: ACTIVE → EXPIRED
Timestamp: expiration_ts field shows exact expiration time
Update: Updating quote amount resets the 10-minute timer

If you need a new rate after expiration, create a new quote.

Error Responses

Validation Error

Status: 400 Bad Request

{
  "error": "quote_currency is required",
  "valid_quote_currencies": ["MXN", "COP", "ARS", "BRL", "CLP", "PEN", "UYU", "GTQ", "CRC", "DOP", "PYG", "USD", "USDC", "USDT"]
}

Invalid Network

Status: 400 Bad Request

{
  "error": "Invalid network 'ethereum' for USDC",
  "valid_networks": ["solana", "polygon"]
}

Invalid Account Type

Status: 400 Bad Request

{
  "error": "Invalid account_type 'WIRE' for currency 'MXN'",
  "valid_account_types": ["SPEI"]
}

Currency Pair Not Enabled

Status: 400 Bad Request

{
  "error": {
    "code": "CURRENCY_PAIR_NOT_ENABLED",
    "message": "Currency pair not enabled for this account type",
    "details": {
      "base_currency": "USD",
      "quote_currency": "XYZ",
      "account_type": "SPEI"
    }
  }
}

Fees Exceed Amount

Status: 409 Conflict

{
  "error": {
    "code": "FEES_EXCEED_AMOUNT",
    "message": "Total fees exceed the amount",
    "details": {
      "amount": 10.00,
      "total_fees": 15.00
    }
  }
}

Invalid Calculated Amount

Status: 400 Bad Request

Occurs when using amount_in_destination: true with an amount too small to cover fees.

{
  "error": {
    "code": "INVALID_CALCULATED_AMOUNT",
    "message": "Amount too small to calculate with given fees",
    "details": {
      "requested_amount": 100.00,
      "calculated_base_amount": -50.00
    }
  }
}

Quote Not Found

Status: 404 Not Found

{
  "error": {
    "code": "QUOTE_NOT_FOUND",
    "message": "Quote not found: 550e8400-e29b-41d4-a716-446655440000"
  }
}

Quote Invalid State

Status: 400 Bad Request

{
  "error": {
    "code": "QUOTE_INVALID_STATE",
    "message": "Quote is not active or has expired"
  }
}

Unauthorized

Status: 401 Unauthorized

{
  "code": "unauthorized",
  "message": "No client ID found in claims"
}

Best Practices

Create quotes close to payout time - Quotes expire after 10 minutes
Handle expiration gracefully - If a quote expires, create a new one
Use inverse calculation wisely - Useful when the recipient needs an exact amount
Specify account type when needed - Use explicit account types for USD payouts
Check fee breakdown - Review the fee structure before committing to a payout
Store quote IDs - Save the quote_id to reference when creating payouts

Next Steps

After creating a quote:

Create a Payout - Use the quote to send funds to a recipient
Set up Webhooks - Track payout status updates

Support

Email: [email protected]
Recipients Guide: recipients.md
Payouts Guide: payouts.md