Delegation Accounts

Delegation Accounts (also called Partner Delegation) lets your Customers buy and sell crypto using fiat balances that you hold and manage, instead of pre-funding a settlement account at Lirium.

With the standard integration, you call Lirium and Lirium keeps the Customer's balances. With Delegation Accounts the direction is inverted for the fiat side: Lirium calls a small set of endpoints that you implement, and your service moves money between the Customer's account and your settlement account whenever an order is placed.

Lirium continues to hold the crypto and to run the buy/sell flow in its WebApp. You remain the source of truth for the Customer's fiat balances.

📘

When to use this product

Use Delegation Accounts when the Customer's fiat funds already live in your platform (for example, an ARS account in your core banking system) and you want crypto buy/sell to debit and credit those balances directly, without pre-funding Lirium.

How it works

There are two sides to the integration:

The roles involved:

• Banking Partner (BP) — you. You hold the Customer's fiat accounts and a settlement account, and you implement the Delegation Endpoints.
• Customer — your end user, identified by a customer_id.
• Lirium — the platform. It holds the crypto, drives the WebApp, and calls your Delegation Endpoints to read balances and settle orders.

Setup

1. Key pair

Lirium provisions a public/private key pair for your account. Lirium keeps the private key and uses it to sign every request it sends to your Delegation Endpoints. You read the public key to verify those requests:

GET /partner/delegation

{
  "enabled": true,
  "public_key": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0K...",
  "created_at": "2025-07-15T15:34:52.663452+00:00"
}

The public_key is base64 encoded — decode it before using it to verify signatures. See Get Delegation Public Key.

2. IP allowlist

Lirium shares the list of source IP addresses its services use to reach your endpoints. Your service must reject any request to the Delegation Endpoints that does not originate from one of these addresses.

Customer session

Each Customer that opens the crypto view goes through a short login handshake before Lirium starts operating against your endpoints.

1. Generate an access_id. Create a session identifier on your side and link it to the Customer. This value becomes the iss claim of the JWT Lirium later uses to call your endpoints, so it must uniquely map back to the Customer.

2. Create the login. Call POST /customers/{customer_id}/logins with the access_id:

   JSON

   { "access_id": "5f3c1a2b9d7e4c8a" }

   Lirium responds with a login id and code:

   JSON

   { "id": "a1b2c3d4e5f6", "code": "123456" }

3. Open the WebApp. Redirect the Customer (or open a webview) to:

   https://{partner}.app.lirium.com?i={id}&c={code}

   Replace {id} and {code} with the values from the response and {partner} with your assigned subdomain.

Authenticating Lirium's requests

Every request Lirium sends to your Delegation Endpoints is authenticated with a JWT:

• The token's iss claim is the access_id of the Customer's session — use it to resolve which Customer the request is for.
• It is signed with Lirium's private key using RS512. Verify it with the base64-decoded public_key from GET /partner/delegation.
• It is sent in the Authorization: Bearer <jwt> header.

Your endpoint must:

1. Confirm the source IP is on the allowlist.
2. Verify the JWT signature with the delegation public key.
3. Resolve the Customer from the iss (access_id) claim.

⚠️

Verify both the IP and the signature

Reject the request if the source IP is not on the allowlist or the JWT signature does not verify. Both checks are required — neither is sufficient on its own.

See the Delegation Accounts Integration recipe (under Recipes) for a worked example.

Order settlement

When a Customer buys or sells crypto, Lirium reads balances and rates from your endpoints, quotes the operation, and then asks you to move the fiat with POST /order. The operation field states the direction of the fiat transfer:

Each order carries a lirium_id — the ID of the order in Lirium. Treat it as an idempotency key: if you receive the same lirium_id twice (for example on a retry), return the result of the original transfer instead of moving money again.

Buy example

For a Customer buying BTC 0.001 with their ARS account:

1. Lirium calls GET /accounts to load the Customer's balances and GET /rates for the ARS/USD rate.
2. Lirium calls POST /quote to price the operation. Your service returns the ARS amount for the requested USD settlement.
3. Lirium calls POST /order with operation: "debit" — you debit the Customer's ARS account and credit your settlement account in USD.
4. Lirium debits your settlement (USD) balance and credits BTC to the Customer.

Sell example

For a Customer selling BTC 0.0005 into their ARS account, the flow mirrors the buy but with operation: "credit": you debit your settlement account and credit the Customer's ARS account, while Lirium debits the Customer's crypto and credits your settlement balance.

The full request/response contract for GET /accounts, GET /rates, POST /quote, and POST /order is documented in Delegation Endpoints.