Bitlipa Settlement API¶

The Bitlipa Settlement API lets partners convert fiat to crypto on behalf of merchants. A typical integration follows a quote → confirm → execute flow, with terminal status delivered via webhook.

1. Authenticate

Every request is signed with HMAC-SHA256 using your API secret.

Authentication
2. Create a settlement

Send a settlement request and receive a quote with a guaranteed rate.

Create a settlement
3. Confirm or cancel

Confirm to execute, or cancel before expiry.

Confirm a settlement
4. Receive a callback

Bitlipa POSTs to your callback_url once the on-chain transfer settles.

Callbacks

Status lifecycle¶

┌─────────┐
│ quoted  │ ← POST /settlements
└────┬────┘
     │
     ├──── POST /confirm ────► ┌────────────┐
     │                         │ processing │
     │                         └─────┬──────┘
     │                               │
     │                   ┌───────────┴───────────┐
     │                   ▼                       ▼
     │             ┌──────────┐           ┌────────┐
     │             │ executed │           │ failed │
     │             └──────────┘           └────────┘
     │
     ├──── POST /cancel ────► ┌───────────┐
     │                        │ cancelled │
     │                        └───────────┘
     │
     └──── (expires_at passes, no action)
                    │
                    ▼
           Quote becomes invalid
           (POST /confirm returns 410)

Status definitions¶

Status	Description
`quoted`	Quote created, awaiting confirmation
`processing`	Confirmed, blockchain transaction in progress
`executed`	Crypto successfully delivered
`failed`	Execution failed (see `failure_reason`)
`cancelled`	Cancelled by partner before confirmation

Allowed transitions¶

From	To	Trigger
`quoted`	`processing`	`POST /confirm`
`quoted`	`cancelled`	`POST /cancel`
`quoted`	(invalid)	`expires_at` passes
`processing`	`executed`	Blockchain confirmation
`processing`	`failed`	Execution error

Base URL¶

https://api.bitlipa.com

All endpoints are prefixed with /api/v1.

Conventions¶

All request and response bodies are JSON.
Timestamps are ISO 8601 with timezone (2024-01-15T10:30:00Z).
Money amounts follow the rules in Amounts & precision.