xStocks

📘

Recipe

Buy and Sell xStocks walks through a buy, a partial sell and a full-balance sell end to end.

An xStock is a token that represents a share of a company listed in the United States, backed by the real share held in custody.

xStocks work like any crypto: they come in available_assets, they are priced by Exchange Rates, and they are bought, sold and swapped with the same orders. There are only two differences, covered below: the multiplier and the minimum amount.

Available assets

The xStocks enabled for your domain are agreed during onboarding. They show up in the available_assets list of Partner Details with type: "xstock":

"available_assets": [
  {
    "id": "AAPLx",
    "name": "Apple xStock",
    "type": "xstock",
    "decimal_places": 8,
    "allowed_operations": ["buy", "sell"]
  }
]

The multiplier

The multiplier is a display value for your frontend. It tells you how many shares back each token, and it changes with the splits and other corporate actions of the stock. Get it from Get xStock Multipliers.

share price = token price ÷ multiplier
shares      = tokens × multiplier

If AAPLx costs 234.8877 in your settlement currency and its multiplier is 1.0026642075893797, the share value is 234.2636, and 100 tokens are 100.26642076 shares.

• Always show the token (AAPLx), never the company name ("Apple"). The Customer trades and holds tokens, not shares.
• Use the multiplier to show how many shares the Customer's tokens correspond to, and to show the price as share value, so it can be compared against the stock market.
• Orders and balances are always in tokens.

Minimum amount per operation

Every xStock operation must be worth at least 1 USD. The minimum is the same for every xStock.

You don't need to validate it yourself: create the order and read the response.

full_amount_required makes sure no dust is left behind: sell or swap the whole balance instead. Send asset.full_amount: true with no amount, and Lirium takes the whole balance for you.

{
  "reference_id": "sell-all-20260925-001",
  "operation": "sell",
  "asset": {
    "currency": "AAPLx",
    "full_amount": true
  },
  "sell": {
    "settlement": {
      "currency": "USD"
    }
  }
}

Offer "sell all" as an explicit option in your app, and use it when you get full_amount_required.