Create a settlement¶

POST /api/v1/settlements

Creates a new settlement request. Bitlipa returns a quote that includes the exchange rate, fees, and fulfillment information.

Request body¶

Field	Type	Required	Description
`source_amount`	integer	Yes	Gross amount in minor units (the total Bitlipa expects to receive).
`source_currency`	string	Yes	Source currency code (e.g., `KES`).
`destination_currency`	string	Yes	Destination currency code (e.g., `USDT`).
`external_merchant_id`	string	Yes	Partner's merchant identifier, as registered with Bitlipa.
`chain`	string	Yes	Blockchain network in CAIP-2 format.
`wallet_address`	string	Yes	Destination wallet address.

Supported chains (CAIP-2)¶

Chain	Format
Polygon	`eip155:137`

Response¶

Field	Type	Description
`tx_id`	string	Bitlipa transaction identifier.
`status`	string	Always `quoted` for new settlements.
`source_currency`	string	Source currency code.
`destination_currency`	string	Destination currency code.
`chain`	string	Blockchain network (CAIP-2).
`exchange_rate`	number	Guaranteed rate for this quote.
`destination_amount`	number	Net amount to be delivered (after fee deduction).
`platform_fee`	number	Fixed platform fee.
`fulfillment`	string	`full`, `partial`, or `none`.
`expected_source_amount`	integer	Gross source amount to be settled (minor units).
`expires_at`	string	Quote expiration (ISO 8601).

Gross vs. net amounts

expected_source_amount is the gross source amount Bitlipa expects to receive.
destination_amount is the net amount delivered to the wallet (after platform_fee is deducted).
Calculation: destination_amount = (expected_source_amount × exchange_rate) − platform_fee.

Partial fulfillment

If fulfillment is partial, the expected_source_amount will be less than the requested source_amount due to liquidity constraints. The partner should present this to the merchant for acceptance.

Example¶

PythoncURLResponse — 201 Created

import hashlib, hmac, json, time, uuid
import requests

API_KEY = "pk_live_xxx"
API_SECRET = b"sk_live_xxx"

path = "/api/v1/settlements"
body = json.dumps({
    "source_amount": 100000,
    "source_currency": "KES",
    "destination_currency": "USDT",
    "external_merchant_id": "merchant_123",
    "chain": "eip155:137",
    "wallet_address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
}, separators=(",", ":"))

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

resp = requests.post(
    f"https://api.bitlipa.com{path}",
    data=body,
    headers={
        "Authorization": API_KEY,
        "Content-Type": "application/json",
        "X-Bitlipa-Timestamp": ts,
        "X-Bitlipa-Nonce": nonce,
        "X-Bitlipa-Signature": sig,
    },
    timeout=10,
)
print(resp.json())

TS=$(date +%s); NONCE=$(uuidgen)
BODY='{"source_amount":100000,"source_currency":"KES","destination_currency":"USDT","external_merchant_id":"merchant_123","chain":"eip155:137","wallet_address":"0x742d35Cc6634C0532925a3b844Bc454e4438f44e"}'
SIG=$(printf '%s\nPOST\n/api/v1/settlements\n\n%s' "$TS" "$BODY" \
  | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $2}')

curl -X POST https://api.bitlipa.com/api/v1/settlements \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Bitlipa-Timestamp: $TS" \
  -H "X-Bitlipa-Nonce: $NONCE" \
  -H "X-Bitlipa-Signature: $SIG" \
  -d "$BODY"

{
  "tx_id": "tx_abc123def456",
  "status": "quoted",
  "source_currency": "KES",
  "destination_currency": "USDT",
  "chain": "eip155:137",
  "exchange_rate": 0.0077,
  "destination_amount": 5.20,
  "platform_fee": 2.50,
  "fulfillment": "full",
  "expected_source_amount": 100000,
  "expires_at": "2024-01-15T10:35:00Z"
}

Example calculation. expected_source_amount (100,000 KES) × exchange_rate (0.0077) = 7.70 USDT gross. Then 7.70 − platform_fee (2.50) = destination_amount (5.20 USDT net).

Next step¶

Once the merchant accepts the quote, call Confirm a settlement before expires_at.