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, or rejected by an admin (approval_state = rejected)

Manual approval does not add a status — see approval_state

status describes the settlement lifecycle and its value set is unchanged. A settlement that exceeds the pair maximum is created as an ordinary quoted quote, but with approval_state = pending (an additive field) — it cannot be confirmed until an admin approves it. approval_state is pending / approved / rejected, or null for ordinary settlements. See Amounts requiring manual approval.

Allowed transitions

From	To	Trigger
quoted (approval_state = pending)	quoted (approval_state = approved)	Admin approves (re-prices, refreshes expires_at)
quoted (approval_state = pending)	cancelled (approval_state = rejected)	Admin rejects
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.