Reconcile balances and ledger entries

Balance endpoints expose funds available to this merchant and environment. Ledger entries explain every balance movement.

Pay a connected application from your balance

OAuth permissions balance-payments:read and balance-payments:write authorize internal payments to the registered application owner. API keys cannot call these endpoints. Supported currencies are USDT, RUB, BNB, GRAM, LTC, POL, ARB, USDC and USDE. GRAM uses eight ledger decimals; the others use two. TON is accepted as a legacy alias for GRAM. Read GET /currencies for balance_payment_supported and decimals. Internal payments have no administrative review and never create an external withdrawal; self-payments are rejected.

The merchant needs available funds in the requested currency. Cloud payments do not select a network or convert another balance automatically. Checkout deposits arrive directly on Bybit and, with the default auto-sale, credit USDT. Convert available funds or configure a LirPay autoswap destination before paying in another currency. Ledger decimals are separate from blockchain and Bybit invoice precision.

POST /balance-payments
Idempotency-Key: order-123-reserve
{"external_id":"order-123","currency_code":"USDT","amount_minor":1000}

GET /balance-payments/order-123

POST /balance-payments/order-123/adjust
Idempotency-Key: order-123-adjust-1
{"amount_minor":1200}

POST /balance-payments/order-123/settle
Idempotency-Key: order-123-settle-1
{"amount_minor":1200}

Reserve before providing the service; adjust only an unsettled reservation. Settlement sets the cumulative net amount, captures funds and releases the unused reserve. Zero releases or refunds the entire amount. After settlement the amount may only decrease; refunds require available funds on the application owner's account. Balances, ledger entries and each command reply commit atomically. Use a new key for each distinct command and retain the same key/body after a lost response. Read access is isolated by merchant, client and environment. Reservations do not expire automatically. Reconnect the same merchant/client after revocation to finish an outstanding payment.

GEThttps://lirpay.org/api/v2/integration/balances

List every initialized currency balance.

API key or OAuth tokenbalances:read

{
  "balances": [
    {
      "currency_code": "USDT",
      "available_minor": 125050,
      "available": "1250.50",
      "pending_minor": 3000,
      "pending": "30.00",
      "reserved_minor": 3000,
      "reserved": "30.00",
      "decimals": 2
    }
  ],
  "mode": "live"
}

GEThttps://lirpay.org/api/v2/integration/balances/{currency}

Read one initialized currency balance.

API key or OAuth tokenbalances:read

Parameter	Type	In	Required	Description
currency	string	path	yes	Uppercase currency code such as USDT.

GEThttps://lirpay.org/api/v2/integration/ledger-entries

List balance movements with currency, type, and date filters.

API key or OAuth tokenbalances:read

Parameter	Type	In	Required	Description
currency	string	query	no	Filter by currency code.
type	string	query	no	Filter by credit, debit, fee, swap_in, swap_out, or manual_adjustment.
created_from	RFC3339	query	no	Include records created at or after this timestamp.
created_to	RFC3339	query	no	Include records created at or before this timestamp.
page	integer	query	no	Page number. Defaults to 1.
limit	integer	query	no	Items per page. Maximum 100.

GEThttps://lirpay.org/api/v2/integration/ledger-entries/{id}

Read one ledger movement.

API key or OAuth tokenbalances:read

Parameter	Type	In	Required	Description
id	string	path	yes	Financial operation ID, for example LIR89924A8DCE6E. Use the id returned by the API.

{
  "ledger_entry": {
    "id": "LIR07A52D047339",
    "currency_code": "USDT",
    "type": "debit",
    "amount_minor": 5000,
    "amount": "50.00",
    "fee_minor": 300,
    "fee": "3.00",
    "decimals": 2,
    "status": "completed"
  }
}