Glossary
Quick reference for key terms used in the Boros API. For portfolio concepts (Rate Sensitivity, Daily Volatility, margin, PnL, liquidation), see the Boros User Glossary.
Core Concepts
| Term | Description | Where it appears |
|---|---|---|
| Market | A trading market uniquely identified by marketId, with one collateral token and specific parameters. Each market represents a different interest rate swap: different token, different maturity, different reference rate. | GET /markets, GET /markets/{marketId} |
| Asset | Any collateral token in the system, identified by tokenId (e.g., USDT has 6 decimals, BTC has 8). Internally all values are normalized to 18 decimals. | GET /assets/all |
| Root | EVM address (0x-prefixed) serving as the primary trading identity. The root wallet signs sensitive actions (deposit, withdraw, agent approval). | All account endpoints, calldata endpoints |
| Account | Sub-account under a root (IDs 0–255). Account 0 is default for trading; 255 is reserved for AMM. Currently only account 0 is available for external users. | accountId parameter across all endpoints |
| Agent | Wallet authorized to execute non-sensitive trading operations on behalf of a root account. Agents cannot withdraw funds — only place orders, cancel, transfer cash, and enter/exit markets. See Agent Trading. | GET /agents/expiry-time, GET /calldata/approve-agent |
| Account Manager | Delegated wallet that can approve and revoke agents on behalf of a root account. The root sets the account manager via setAccManager. Useful for programmatic agent management without exposing the root key. | GET /calldata/approve-agent |
Market Account (marketAcc) | The 26-byte (54-char hex) identifier that uniquely identifies a margin account. Bit-layout: `root(160) | accountId(8) |
| Decimals | Deposits/withdrawals use native token decimals (e.g., 6 for USDT). All trading values — sizes, balances, prices — use 18 decimals internally. Always convert when bridging between wallet amounts and API values. | All size/amount fields |
| APR Format | All APR values in the API (markApr, midApr, liquidationApr, impliedApr, ammImpliedApr, etc.) are decimal fractions, not percentages. For example, 0.05495 means 5.495%. Multiply by 100 to get the human-readable percentage. All APR fields use the same scaling — there are no exceptions. | All market and account endpoints |
| Scaling Factor | Multiplier used to normalize token amounts to 18-decimal precision internally. Calculated as 10^(18 - tokenDecimals) during token registration (e.g., USDT with 6 decimals has scaling factor 10^12). Tokens with more than 18 decimals are not supported. | GET /assets/all |
| Cooldown | Mandatory waiting period between requesting and finalizing a withdrawal. Protects protocol solvency by preventing instant removal of collateral backing active positions. The global cooldown applies to all users; individual roots may have a personal cooldown override. | Withdrawal endpoints |
| Deposit Box | Deterministic per-user contract for receiving cross-chain deposits and performing token swaps (via DEX routers) before depositing into Boros. Created by DepositBoxFactory from (root, boxId). Managed by Pendle backend — users do not interact with them directly. | Internal (not exposed via API) |
Trading Concepts
| Term | Description | Where it appears |
|---|---|---|
| Order Book | Primary liquidity source with Long/Short sides organized by price ticks. See Order Book Mechanics for matching rules and constraints. | GET /markets/order-books, GET /v2/markets/order-books |
| Order | Trade instruction with orderId, tick (price level), side, size (18 decimals), and tif (time-in-force). Orders can be placed individually or in bulk. | POST /calldata/place-orders, GET /accounts/limit-orders |
| Tick | Integer price level representing an interest rate. Formula: rate = 1.00005^(tick × tickStep) - 1. Higher tick = higher rate. The tick step is market-specific and controls rate granularity. Use SDK helpers to convert between human-readable APR and tick values. | All order-related endpoints, GET /stop-order/v1/orders/tpsl/prepare |
rate vs limitTick | Two ways of specifying the limit price on an order. rate is the human-friendly decimal APR (e.g. 0.05 = 5%) and is rounded to the nearest valid tick by the backend. limitTick is the raw integer tick. The simple place-order endpoint takes rate; the advanced place-orders endpoint accepts either (XOR). | POST /calldata-builder/agent/place-order(s) |
desiredRate vs slippage | Two ways of specifying the execution guard (worst acceptable average fill rate) for the matched portion of an order. desiredRate is an absolute ceiling — the contract reverts with TradeUndesiredRate if signedCost > signedSize × desiredRate. slippage is a relative tolerance from the current mid-rate (e.g. 0.005 = 0.5%); the backend computes desiredRate = midRate ± slippage for you. Exactly one must be supplied on the advanced endpoint; the simple endpoint only exposes slippage. Strongly recommended for FOK / IOC market orders. | POST /calldata-builder/agent/place-order(s) |
| AMM | Automated market maker providing continuous liquidity alongside the order book. The Router routes between AMM and order book for optimal execution. AMM liquidity can be optionally included in order book queries. | GET /v2/markets/order-books, AMM simulation/calldata endpoints |
| OTC Trade | Direct swap between two accounts bypassing the order book, typically routed through the AMM. Has a separate fee rate (otcFee). See Fees. | AMM swap/liquidity endpoints |
| Mark Rate | TWAP of historical order book trades, used as the reference rate for margin, liquidation, and order rate bounds. Distinct from mid rate and AMM implied rate. See TWAP Oracle. | GET /markets/{marketId} (in market state) |
| Mid Rate (midApr) | Midpoint of the best bid and best ask rates: (bestBid + bestAsk) / 2. When the AMM provides the tightest spread, this may equal the AMM implied rate. Can diverge from the mark rate in thin markets. | GET /markets/{marketId} |
| AMM Implied Rate | The current rate implied by the AMM's internal state. Represents the rate at which the AMM would trade. Should normally be near the order book's best bid/ask. The AMM has a min/max APR range — outside this range, it stops serving trades. | GET /markets/{marketId} |
| Implied Rate | Current interest rate implied by order book trading, consisting of the last traded rate and a TWAP component. | GET /markets/{marketId} |
| Rate Floor | Minimum absolute rate used in margin calculations (derived from market.imData.iTickThresh). If an order's rate is below the rate floor, the floor value is used for margin instead. See Margin — Pre-scaling IM. | Market config |
| Settlement | Periodic floating rate payment exchange (typically every 8 hours) using lazy settlement. See Settlement Mechanics. | GET /accounts/settlements, POST /funding-rate/settlement-summary |
| Conditional Order | On-chain order with an off-chain trigger condition, executed by a permissioned validator when conditions are met. Stop orders are built on this. See Conditional Orders. | Stop Order Service endpoints |
| Stop Order | Conditional off-chain order (take-profit or stop-loss) that triggers when market APR crosses a threshold. Managed by the Stop Order Service. See Stop Orders. | GET /stop-order/v1/orders/tpsl/prepare, POST /stop-order/v2/orders/place |
Margin Concepts
| Term | Description | Where it appears |
|---|---|---|
| Cross Margin | Shares collateral across all entered markets. Unrealized profit in one market can offset losses in another. Use CROSS_MARKET_ID (16777215) when packing marketAcc. | POST /accounts/market-acc-infos, GET /calldata/enter-exit-markets |
| Isolated Margin | Constrains collateral to a single market. Liquidation in one market doesn't affect others. Use the specific marketId when packing marketAcc. | GET /calldata/cash-transfer, GET /simulations/deposit |
| Initial Margin | Minimum collateral required to open a new position. Calculated based on position size, rate, and time to maturity. See Margin Mechanics. | GET /simulations/place-order (in projected state) |
| Maintenance Margin | Minimum collateral required to keep positions open. If total value drops below this, the position is eligible for liquidation. | POST /accounts/market-acc-infos (in margin status) |
| Health Ratio | Total Value / Maintenance Margin. Above 1.0 = healthy; ≤ 1.0 = liquidation eligible. Multiple thresholds trigger progressive risk actions. See Margin Mechanics. | POST /accounts/market-acc-infos |
| Liquidation | Forced closure of positions when health ratio ≤ 1.0. Positions are closed at mark rate; a liquidation incentive is paid to the liquidator. See Margin Mechanics. | GET /events/liquidation-events |
| Force Cancel | Automatic cancellation of open orders when an account's health ratio drops below the risky threshold, or when order rates deviate too far from mark rate. See Risk Management. | GET /accounts/limit-orders |
| CLO (Close-Only) | Market status where only position-reducing orders are accepted. See Closing Only Mode. | GET /markets/{marketId} (status field) |
Operational Concepts
| Term | Description | Where it appears |
|---|---|---|
| Computing Unit (CU) | Per-endpoint cost of a request, advertised via the x-computing-unit OpenAPI extension and returned as the x-computing-unit response header. A value like 1+ means dynamic cost — the endpoint charges a minimum for an empty request and scales with work performed (e.g. page size, number of indicators). See Computing Units. | All endpoints (header) |
| Indicator | Compact letter codes for time-series market data: u (underlying APR), fp (future premium), fgi (fear & greed index), ap (asset price), udma:<periods> (X-day UFR moving averages). See Indicators. | GET /v1/indicators, GET /v1/indicators/export |
| Maker Incentive | PENDLE-token rewards distributed to liquidity providers. Two campaigns: Add-Liquidity (rewards for resting orders that sit within an incentiveRange of mid-APR) and Filled-Volume (rewards proportional to the user's maker fill volume in the current epoch). See Incentives. | GET /v1/incentives/maker-incentives/campaigns/{marketId} |
| AMM Incentive | Rewards accrued by AMM liquidity providers — swap fees plus PENDLE incentives — denominated in USD. See Incentives. | GET /v1/incentives/amm-incentives |
Enums
Side
| Value | Name | Description |
|---|---|---|
0 | LONG | Betting on rate increase (pay fixed, receive floating) |
1 | SHORT | Betting on rate decrease (receive fixed, pay floating) |
Time In Force (TIF)
| Value | Name | Best for | Description |
|---|---|---|---|
0 | GOOD_TIL_CANCELLED | Limit orders | Remains on book until filled or canceled |
1 | IMMEDIATE_OR_CANCEL | Market orders | Fills against available liquidity, cancels remainder |
2 | FILL_OR_KILL | All-or-nothing | Must fill entire size immediately or reverts |
3 | ALO | Market making | Post-only (Add Liquidity Only); reverts if it would match existing orders. Guarantees maker-only status. |
4 | SOFT_ALO | Market making | Post-only (soft); skips matching without reverting. Preferred over ALO for no-revert behavior. |
Market Status
PAUSED (0) · CLO (1) · GOOD (2) — See Custom Types for descriptions and state transitions.
Stop Order Type
| Value | Name | Description |
|---|---|---|
2 | TAKE_PROFIT_MARKET | Triggers when market moves in your favor |
3 | STOP_LOSS_MARKET | Triggers when market moves against you |
SDK Helpers
import { MarketAccLib, CROSS_MARKET_ID } from "@pendle/boros-sdk-public";
import { FixedX18, estimateTickForRate, getRateAtTick } from "@pendle/boros-offchain-math";
// Pack market account for API calls
const marketAcc = MarketAccLib.pack(walletAddress, accountId, tokenId, CROSS_MARKET_ID);
// Convert between tick and rate
const tick = estimateTickForRate(FixedX18.fromNumber(0.05), tickStep, false);
const rate = getRateAtTick(tick, tickStep);
// Convert between human-readable numbers and 18-decimal strings
const size = FixedX18.fromNumber(100).value.toString(); // "100000000000000000000"
const amount = FixedX18.fromBigIntString(balanceString).toNumber(); // 100.0
See SDK for the full TypeScript wrapper around these helpers.
Additional Resources
- Boros User Glossary — Portfolio and general trading terms
- OrderBook Mechanics — How the order book works
- AMM Mechanics — How the AMM provides continuous liquidity
- Margin Mechanics — Initial/maintenance margin and liquidation
- Settlement Mechanics — Funding rate payments
- Fee Structure — Position opening, settlement, and entrance fees
- Incentives — Maker incentives and AMM rewards
- Indicators — Indicator letter codes (
u,fp,fgi,ap,udma) - Computing Units — How endpoint cost is computed and reported
- Custom Types — Contract type definitions
- API Reference — All API endpoints and integration workflows