Request
Create a quote for converting between currencies. The quote locks in a price for 30 seconds and includes a transparent fee breakdown.
Body parameters
Customer requesting the quote
Source asset: BRL, USDT, or BTC
Target asset: BRL, USDT, or BTC
Amount in smallest unit of the specified amount_asset
Which asset the amount refers to: must match from_asset or to_asset
Whether amount is net (after fees) or gross (before fees)
net: Amount the customer receives (for to_asset) or spends after fees (for from_asset)gross: Total amount including fees
Partner fee in basis points (100 bps = 1%). This fee is added to the total and split between you and Bipa.
Response
Unique quote identifier to use when executing
Customer who requested the quote
Total amount debited from customer (smallest unit)
Total amount credited to customer (smallest unit)
Decimal places for source asset
Decimal places for target asset
Exchange price: cost of 1 unit of to_asset in from_asset (smallest unit)
Decimal places for displaying the price
Fee breakdown
Total fee in from_asset smallest unit
Total fee as basis points of the transaction
Partner’s fee portion in from_asset smallest unit
Partner fee as basis points
Bipa’s fee portion in from_asset smallest unit
Quote status: pending, expired, or executed
ISO 8601 expiration timestamp (30 seconds from creation)
ISO 8601 creation timestamp
curl -X POST https://api.bipa.tech/v1/quotes \
-H "Authorization: Bearer bipa_live_sk_..." \
-H "Content-Type: application/json" \
-d '{
"customer_id": "cus_a1b2c3d4e5f6",
"from_asset": "BRL",
"to_asset": "BTC",
"amount": "100000",
"amount_asset": "BRL",
"amount_type": "gross",
"partner_fee_bps": 50
}'
{
"id": "quote_abc123xyz",
"customer_id": "cus_a1b2c3d4e5f6",
"from_asset": "BRL",
"to_asset": "BTC",
"from_amount": "100000",
"to_amount": "24628",
"from_decimals": 2,
"to_decimals": 8,
"price": "40200000",
"price_decimals": 2,
"fees": {
"total": "1000",
"total_bps": 100,
"partner": "500",
"partner_bps": 50,
"bipa": "500",
"bipa_bps": 50
},
"status": "pending",
"expires_at": "2024-01-15T10:30:30Z",
"created_at": "2024-01-15T10:30:00Z"
}
Understanding the quote
Price interpretation
The price field represents how much from_asset you need for 1 unit of to_asset:
BRL → BTC quote:
price = "40200000"
price_decimals = 2
1 BTC = 40200000 / 10^2 = R$ 402,000.00
Fee calculation
Fees are expressed both as absolute amounts and basis points:
# Example: R$ 1,000 → BTC with 100 bps total fee
from_amount = 100000 # R$ 1,000.00
fees_total = 1000 # R$ 10.00
fees_total_bps = 100 # 1%
# Net amount used for conversion
net_for_conversion = from_amount - fees_total # R$ 990.00
# Partner earns 50 bps of the transaction
partner_fee = 500 # R$ 5.00
partner_bps = 50
# Bipa earns 50 bps
bipa_fee = 500 # R$ 5.00
bipa_bps = 50
Amount type examples
gross from_asset
net to_asset
net from_asset
“I want to spend exactly R$ 1,000”{
"amount": "100000",
"amount_asset": "BRL",
"amount_type": "gross"
}
from_amount = "100000" (exactly R$ 1,000 debited) “I want to receive exactly 0.001 BTC”{
"amount": "100000",
"amount_asset": "BTC",
"amount_type": "net"
}
to_amount = "100000" (exactly 0.001 BTC credited) “I want R$ 990 worth of BTC after fees”{
"amount": "99000",
"amount_asset": "BRL",
"amount_type": "net"
}
For the best user experience, use amount_type: "gross" when the user enters a BRL amount, and amount_type: "net" when they enter a crypto amount.
