Get rate preview¶

GET /api/v1/rates/preview

Retrieves a preliminary, non-binding exchange rate and platform fee for display purposes. Rates and fees can vary by chain, so chain is required.

Note

This rate is informational only. The guaranteed rate is established when creating a settlement.

Query parameters¶

Field	Type	Required	Description
`source_currency`	string	Yes	Source currency code (e.g., `KES`).
`destination_currency`	string	Yes	Destination currency code (e.g., `USDT`).
`chain`	string	Yes	Blockchain network in CAIP-2 format (e.g., `eip155:137`).
`external_merchant_id`	string	Yes	Partner's merchant identifier, as registered with Bitlipa.

Response¶

Field	Type	Description
`source_currency`	string	Source currency.
`destination_currency`	string	Destination currency.
`chain`	string	Blockchain network (CAIP-2).
`exchange_rate`	number	Current indicative rate.
`platform_fee`	number	Fixed platform fee in the destination currency.
`timestamp`	string	When this rate was generated (ISO 8601).

About platform_fee

This is a fixed fee denominated in the destination currency (e.g., USDT). The fee amount may vary per merchant and chain.

Example¶

PythoncURLResponse — 200 OK

import hashlib, hmac, time, uuid
from urllib.parse import urlencode
import requests

API_KEY = "pk_live_xxx"
API_SECRET = b"sk_live_xxx"

path = "/api/v1/rates/preview"
params = {
    "source_currency": "KES",
    "destination_currency": "USDT",
    "chain": "eip155:137",
    "external_merchant_id": "merchant_123",
}
query = urlencode(params)

ts, nonce = str(int(time.time())), str(uuid.uuid4())
sig = hmac.new(
    API_SECRET,
    f"{ts}\nGET\n{path}\n{query}\n".encode(),
    hashlib.sha256,
).hexdigest()

resp = requests.get(
    f"https://api.bitlipa.com{path}?{query}",
    headers={
        "Authorization": API_KEY,
        "X-Bitlipa-Timestamp": ts,
        "X-Bitlipa-Nonce": nonce,
        "X-Bitlipa-Signature": sig,
    },
    timeout=10,
)
print(resp.json())

TS=$(date +%s); NONCE=$(uuidgen)
QUERY="source_currency=KES&destination_currency=USDT&chain=eip155%3A137&external_merchant_id=merchant_123"
SIG=$(printf '%s\nGET\n/api/v1/rates/preview\n%s\n' "$TS" "$QUERY" \
  | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $2}')

curl "https://api.bitlipa.com/api/v1/rates/preview?$QUERY" \
  -H "Authorization: $API_KEY" \
  -H "X-Bitlipa-Timestamp: $TS" \
  -H "X-Bitlipa-Nonce: $NONCE" \
  -H "X-Bitlipa-Signature: $SIG"

{
  "source_currency": "KES",
  "destination_currency": "USDT",
  "chain": "eip155:137",
  "exchange_rate": 0.0077,
  "platform_fee": 1.50,
  "timestamp": "2024-01-15T10:30:00Z"
}

Implementation notes¶

Polling. Refresh every 30–60 seconds while the user is on the payment screen.
Rate divergence. The final rate at settlement creation may differ due to market movement.