Boros Open API

This guide walks you through integrating with the Boros trading platform via the REST API. For exact request/response schemas and parameter details, see the interactive API docs.

For key concepts and terminology, see the Glossary.

Example Repository: https://github.com/pendle-finance/boros-api-examples

Base URLs

Service	Base URL	Purpose
Open API	`https://api-boros.pendle.finance/apis/v1/`	Market data, calldata generation, account queries (new redesigned mount).
Open API (legacy, deprecated)	`https://api.boros.finance/open-api/v1/` (or `/v2/`) — interactive docs at `https://api.boros.finance/open-api/docs`	Deprecated mount, kept for older clients only. Use the new mount above for everything.
Send Txs Bot	`https://api.boros.finance/send-txs-bot/v2/` (programmatic) or `/v3/` (browser session)	Submitting signed transactions on-chain.
Stop Order	`https://api.boros.finance/stop-order/v1/` to `/v4/`	Conditional TP/SL order management.

备注

Use the redesigned Open API at api-boros.pendle.finance/apis/ — interactive docs: api-boros.pendle.finance/apis/docs. The old api.boros.finance/open-api/ mount (and its /open-api/docs page) is deprecated: still served for older clients, but no new endpoints are added there.

API Services

Open API (Primary)

The main API for querying data and generating transaction calldata.

Interactive docs: https://api-boros.pendle.finance/apis/docs

Send Txs Bot (Transaction Submission)

Receives signed calldata from agents and broadcasts transactions on-chain. You never call smart contracts directly — the bot submits them on your behalf and charges gas fees from your gas balance.

Interactive docs: https://api.boros.finance/send-txs-bot/docs

Stop Order Service

Manages conditional stop orders (take-profit / stop-loss). These orders live off-chain and are triggered automatically when the market APR crosses a threshold. See Stop Orders below for details.

Interactive docs: https://api.boros.finance/stop-order/docs

Integration Workflows

1. First-Time Setup

Before trading, you need to set up an agent and fund your accounts.

┌─────────────────────────────────────────────────────┐
│  1. Generate an agent key pair                      │
│  2. GET  /calldata/approve-agent → calldata         │
│  3. Sign & submit approval tx (from root wallet)    │
│  4. GET  /calldata/deposit → calldata               │
│  5. Sign & submit deposit tx (from root wallet)     │
│  6. Top up gas balance for agent tx fees             │
└─────────────────────────────────────────────────────┘

Steps 2-5 are "sensitive" actions — they require the root wallet signature and are submitted directly to the blockchain, not through the Send Txs Bot. The calldata endpoints return a to address (the Router contract) and the encoded calldata to include in your transaction.

See Agent Trading for the full agent setup guide.

2. Placing a Trade (Agent Flow)

Once your agent is approved, this is the typical order placement flow:

┌──────────────────────────────────────────────────────────────┐
│  1. GET  /markets/{marketId}              → market info      │
│  2. GET  /simulations/place-order         → preview trade    │
│  3. POST /calldata/place-orders           → calldata[]       │
│  4. Sign each calldata with agent key                        │
│  5. POST /send-txs-bot/v2/agent/bulk-direct-call → tx hash  │
│  6. Subscribe to WebSocket account channel for fill updates  │
└──────────────────────────────────────────────────────────────┘

Step 2 (simulation) is optional but recommended — it previews the margin impact, estimated fees, and validates constraints before generating calldata.

Step 3 returns one calldata per entry in orderRequests[]. A bulk request of N orders returns N calldatas; you must sign and submit all of them. The new Open API mount does not auto-prepend an exit-market calldata — if you need to enter or exit markets, call POST /calldata-builder/agent/enter-markets (or .../exit-markets) explicitly. The first time a (root, accountId) trades on a given market, you must call enter-markets first or the place call will revert.

Step 5 sends the signed calldata(s) to the Send Txs Bot. bulk-direct-call accepts one or more signed calldatas in a single request; use it for any batch. direct-call is only kept for the single-calldata case. The response includes a transaction status and hash.

skipReceipt parameter

When submitting via the Send Txs Bot, you can set skipReceipt=true to get the txHash returned immediately without waiting for block inclusion. With skipReceipt=false (default), the bot waits for the transaction to be included in a block and returns the full status and any error message. Use skipReceipt=true for lower latency when you can track the transaction status yourself.

Calldata and requireSuccess

The calldata endpoints return a list of calldatas that execute the intended action. These calldatas should be sent to the bulk-direct-call endpoint of the Send Txs Bot.

When submitting via bulk-direct-call, use the requireSuccess parameter to control atomicity:

requireSuccess=true (recommended for cancel-and-replace pairs) — The bot simulates the whole batch first; if any call would revert, the entire batch is aborted before any tx is sent on-chain. Use this when later calldatas in the batch only make sense if earlier ones succeeded (e.g., cancel an order, then place its replacement).
requireSuccess=false — Each calldata is executed independently; some may succeed while others fail. Useful for place-orders when you want to place multiple orders and don't need them to be atomic (e.g., if one order fails due to insufficient margin, the others can still go through).

3. Closing a Position

┌──────────────────────────────────────────────────────────────┐
│  1. POST /accounts/market-acc-infos       → current position │
│  2. GET  /simulations/close-active-position → preview close  │
│  3. POST /calldata/place-orders           → counter-order    │
│  4. Sign & submit via Send Txs Bot                           │
└──────────────────────────────────────────────────────────────┘

Closing a position internally creates a counter-order (opposite side, same size). The simulation endpoint handles this logic for you.

4. Withdrawing Funds

Withdrawals follow a request → cooldown → finalize pattern:

┌──────────────────────────────────────────────────────────────┐
│  1. GET  /calldata/withdraw-request       → request calldata │
│  2. Sign & submit withdrawal request (root wallet)           │
│  3. Wait for cooldown period                                 │
│  4. Finalize withdrawal on MarketHub contract                │
│                                                              │
│  To cancel: GET /calldata/withdraw-cancel → cancel calldata  │
└──────────────────────────────────────────────────────────────┘

Withdrawal requests and cancellations are sensitive actions signed by the root wallet.

5. Setting Up Stop Orders (TP/SL)

Stop orders are conditional orders that execute automatically when the market APR hits your target:

┌──────────────────────────────────────────────────────────────┐
│  1. GET  /stop-order/v1/orders/tpsl/prepare → order params   │
│  2. POST /stop-order/v2/orders/place        → place order    │
│                                                              │
│  To cancel: DELETE /stop-order/v3/orders/cancel              │
└──────────────────────────────────────────────────────────────┘

The prepare endpoint generates the order parameters (including the calldata that will be executed when triggered). The place endpoint submits the signed conditional order. See Stop Orders for details.

Sensitive vs Non-Sensitive Actions

Understanding this distinction is critical for integration:

Type	Signed by	Submitted via	Examples
Sensitive	Root wallet	Direct to blockchain	Deposit, withdraw, approve/revoke agent
Non-sensitive	Agent key	Send Txs Bot	Place orders, cancel orders, cash transfer, enter/exit markets

Sensitive actions require the root wallet's private key and are submitted as regular Ethereum transactions. Non-sensitive actions are signed by the agent and submitted through the Send Txs Bot service, which handles gas and on-chain submission.

Endpoint Categories

Assets

Query available collateral tokens with metadata and current prices.

Endpoint	Description
`GET /assets/all`	List all supported collateral assets

Markets

Query market configurations, order books, and trade history.

Endpoint	Description
`GET /markets`	List all markets with current state and pricing. Includes `isWhitelisted` field.
`GET /markets/{marketId}`	Get a single market's details
`GET /markets/order-books`	Aggregated order book by tick size. (Deprecated — use v2)
`GET /v2/markets/order-books`	Order book with optional AMM liquidity. Response includes `syncStatus` (`blockNumber` + `timestamp`).
`GET /markets/market-trades`	Recent executed trades
`GET /markets/chart`	OHLCV candlestick data

Accounts

Query and manage user account state.

Endpoint	Description
`POST /accounts/market-acc-infos`	Positions, margins, balances for market accounts. See details below.
`GET /accounts/entered-markets`	Markets entered by a cross-margin account
`GET /accounts/active-positions`	All active positions for a user. See details below.
`GET /accounts/latest-settlements`	Latest settlement per market position. See details below.
`GET /accounts/limit-orders`	Active/inactive limit orders. (Deprecated — use v2)
`GET /accounts/transactions`	Trade history. (Deprecated — use v2)
`GET /accounts/settlements`	Funding rate settlement history
`GET /accounts/transfer-logs`	Deposit/withdrawal transfer logs. (Deprecated — use v2)
`GET /accounts/gas-balance`	Current gas balance
`GET /accounts/gas-consumption-history`	Gas usage history. (Deprecated — use v2)
`GET /accounts/settings`	User account settings
`POST /accounts/settings`	Update settings (agent-signed)

Market Acc Infos

POST /accounts/market-acc-infos — Returns detailed account information for one or more market accounts. Accepts an array of up to 100 marketAccs in the request body.

Response fields (per market account):

Field	Type	Description
`totalCash`	string	Total cash balance (bigint string in settlement token)
`netBalance`	string	Equity = totalCash + sum of all position values
`positions`	array	List of active positions (size, rate, entry block, etc.)
`initialMargin`	string	Raw initial margin (pre-scaling, before the per-account IM Factor is applied)
`initialMarginWithLeverage`	string	Initial margin with the per-account IM Factor applied (the actual collateral consumed)
`availableInitialMargin`	string	Remaining margin available for new positions
`availableMaintMargin`	string	Remaining margin before liquidation (health ratio = 1.0 when zero)

Response includes syncStatus (blockNumber + timestamp).

Naming legacy

The field name initialMarginWithLeverage predates Boros's UI redesign — the on-chain IM Factor (sometimes called kIM or IMRatio) used to be surfaced to users as "leverage", but the UI no longer exposes a leverage knob. The API field name is unchanged for backwards compatibility; semantically it is just "initial margin after the IM Factor is applied". Traders now see Rate Sensitivity and Daily Volatility instead.

Active Positions

GET /accounts/active-positions — Returns all active (non-zero size) positions for a user's account. Query params: userAddress, accountId.

Response fields (per position):

Field	Type	Description
`marketId`	number	Market identifier
`marketAcc`	MarketAcc	Packed account position identifier
`isCross`	boolean	Whether the position uses cross-margin mode
`fixedApr`	number	The fixed APR of the position (e.g. `0.05` = 5%)
`signedSize`	string	Bigint string of signed position size (negative = short)
`side`	Side	`0` = Long, `1` = Short
`cumulativePnl`	string	Bigint string of all-time cumulative trade PnL
`isMatured`	boolean	Whether the market has reached its maturity date

Response includes syncStatus (blockNumber + timestamp).

Latest Settlements

GET /accounts/latest-settlements — Returns the most recent settlement for each market that a user's account has participated in. Query params: userAddress, accountId.

Response fields (per settlement):

Field	Type	Description
`marketId`	number	Market identifier
`marketAcc`	MarketAcc	Packed account position identifier
`isCross`	boolean	Whether the position uses cross-margin mode
`isMatured`	boolean	Whether the market has reached maturity
`timestamp`	number	Timestamp of the latest settlement
`side`	Side	Position side at time of settlement (`0` = Long, `1` = Short)
`positionSize`	string	Bigint string of position size at settlement
`yieldPaid`	string	Bigint string of yield paid in the latest settlement period
`yieldReceived`	string	Bigint string of yield received in the latest settlement period
`settlement`	string	Net settlement = yieldReceived − yieldPaid
`settlementRate`	number	Annualized settlement rate of the latest period (e.g. `0.05` = 5%)
`cumulativeSettlementPnl`	string	All-time cumulative settlement PnL
`sinceOpenSettlementPnl`	string	Cumulative settlement PnL since position was opened

Response includes syncStatus (blockNumber + timestamp).

V2 Accounts (Cursor-Based Pagination)

The v2 endpoints replace the v1 offset-based pagination (skip/limit/total) with cursor-based pagination using a resumeToken. This is significantly more efficient for large datasets.

How it works:

Make the initial request with limit (no resumeToken)
The response includes a resumeToken string — pass it as a query parameter on the next request to get the next page
When resumeToken is null, there are no more pages

All v2 responses also include a syncStatus field (blockNumber + timestamp) indicating how up-to-date the backend data is.

Endpoint	Description
`GET /v2/accounts/limit-orders`	Limit orders sorted by last updated. Supports `marketId`, `isActive`, `orderType` filters. Max `limit`: 2000.
`GET /v2/accounts/all-limit-orders`	All limit orders sorted by placed order. Guarantees no missed orders during pagination — use this for syncing/indexing.
`GET /v2/accounts/transactions`	Trade history with cursor pagination. Supports `fromBlockNumber`, `toBlockNumber`, `isLimitOrderTrade` filters. Max `limit`: 2000.
`GET /v2/accounts/transfer-logs`	Deposit/withdrawal logs with cursor pagination. Max `limit`: 100.
`GET /v2/accounts/gas-consumption-history`	Gas usage history with cursor pagination. Max `limit`: 100.

Which limit-orders endpoint to use?

/v2/accounts/limit-orders — sorted by last updated (eventIndex). Best for showing recent activity in a UI. Note: orders updated during pagination may shift position, so you might miss or duplicate some entries.
/v2/accounts/all-limit-orders — sorted by immutable placed timestamp (placedEventIndex). Guarantees stable pagination — use this for syncing all orders.

New response fields on limit orders:

placedTxHash — the transaction hash where the order was originally placed

Calldata Generation

Generate transaction calldata for on-chain operations.

Sensitive (root-signed, direct to chain):

Endpoint	Description
`GET /calldata/deposit`	Deposit collateral to margin account
`GET /calldata/withdraw-request`	Request withdrawal
`GET /calldata/withdraw-cancel`	Cancel pending withdrawal
`GET /calldata/approve-agent`	Approve an agent
`GET /calldata/revoke-agent`	Revoke an agent
`GET /calldata/vault-pay-treasury`	Pay treasury from vault

Non-sensitive (agent-signed, via Send Txs Bot):

Endpoint	Description
`POST /calldata/place-orders`	Place one or more limit orders
`POST /calldata/place-orders-with-rate`	Place orders with an explicit desired rate (instead of slippage)
`GET /calldata/cancel-order`	Cancel orders
`GET /calldata/cash-transfer`	Transfer between cross and isolated accounts
`POST /calldata-builder/agent/enter-markets`	Enter one or more markets (call this before the first trade on a `(root, accountId, marketId)`). Body: `{ accountId, marketIds: number[] }`.
`POST /calldata-builder/agent/exit-markets`	Exit one or more markets to free entered-market slots. Body: `{ accountId, marketIds: number[] }`. Requires zero position size, no open orders, no pending settlements.
`GET /calldata/enter-exit-markets`	(Legacy combined endpoint. Still served. Prefer the split endpoints above.)
`GET /calldata/pay-treasury`	Pay accrued treasury fees
`GET /calldata/add-liquidity-single-cash-to-amm`	Add AMM liquidity
`GET /calldata/remove-liquidity-single-cash-from-amm`	Remove AMM liquidity

Simulations

Preview operations before executing them. All simulation endpoints return the projected account state after the operation.

Endpoint	Description
`GET /simulations/deposit`	Preview deposit effect on account
`GET /simulations/withdraw`	Preview withdrawal effect on account
`GET /simulations/cash-transfer`	Preview cross ↔ isolated transfer
`GET /simulations/place-order`	Preview order placement with fees
`GET /simulations/close-active-position`	Preview closing a position
`GET /simulations/add-liquidity-single-cash`	Preview adding AMM liquidity
`GET /simulations/remove-liquidity-single-cash`	Preview removing AMM liquidity

Funding Rate

Access funding rate data and settlement history.

Endpoint	Description
`GET /funding-rate/all-funding-rate-symbols`	Available funding rate symbols
`POST /funding-rate/settlement-summary`	Historical settlement summaries

Indicators

Time-series market data — underlying APR, future premium, fear & greed index, asset price, and UFR moving averages. See Indicators for the indicator letter codes and CSV export semantics.

Endpoint	Description
`GET /v1/indicators`	Fetch one or more indicators by letter code (`u`, `fp`, `fgi`, `ap`, `udma:<periods>`). 1 CU per indicator.
`GET /v1/indicators/export`	Export OHLCV + selected indicators as CSV (rate-limited 3 req/min/IP, 20 CU).

Incentives

Maker rewards and AMM rewards. See Incentives for the underlying mechanics.

Endpoint	Description
`GET /v1/incentives/maker-incentives/campaigns/{marketId}`	PENDLE maker-incentive campaign for a market (add-liquidity + filled-volume).
`GET /v1/incentives/amm-incentives`	Per-user AMM rewards (swap fees + Pendle incentives) — accrued, unclaimed, and per-market breakdown.

Market Account Helpers

Pack / unpack the marketAcc identifier without using the SDK.

Endpoint	Description
`GET /v1/market-acc/encode`	Pack `(root, accountId, tokenId, marketId)` into the 26-byte / 54-char hex `marketAcc`.
`GET /v1/market-acc/decode`	Unpack a `marketAcc` into `{ root, accountId, tokenId, marketId, isCross }`.

Agents

Manage agent authorization.

Endpoint	Description
`GET /agents/expiry-time`	Check agent expiry time

Events

Query protocol events.

Endpoint	Description
`GET /events/liquidation-events`	Liquidation event history

Charts

Charting data for trading UIs.

Endpoint	Description
`GET /charts/ohlcv`	OHLCV candlestick data

Leaderboard

Query trading leaderboard data.

Endpoint	Description
`GET /leaderboard`	Trading leaderboard with rankings
`GET /leaderboard/search`	Search for a specific user on the leaderboard

Transaction Status (Send Txs Bot)

Query transaction status with detailed on-chain event data.

Endpoint	Description
`POST /send-txs-bot/v2/agent/dedicated/tx-status`	Transaction status with block info
`POST /send-txs-bot/v2/agent/dedicated/tx-status-with-events`	Transaction status with parsed limit order events (placed, cancelled, market order executed). Each status item includes `limitOrdersPlaced` (orderIds + sizes), `limitOrdersCancelled` (orderIds), and `marketOrdersExecuted` (orderId, side, size).
`POST /send-txs-bot/v1/agent/dedicated/trace`	Trace a submitted request by `agent` address + calldata `nonce` to check whether the Send Txs Bot received it. Useful for resolving ambiguity after network errors/timeouts. Records are retained for 24 hours. See Recovering from Network Errors for the recommended retry pattern.

Nonce safety guarantee

The Send Txs Bot rejects any calldata signed with a nonce ≤ your largest previously-seen nonce, including nonces from calldata that failed simulation. This makes it safe to retry: a successful original submission will cause the retry to be rejected, so you cannot accidentally double-submit by retrying.

Error Handling

The Open API returns errors in a structured format:

{
  "errorCode": "INVALID_MARKET_ID",
  "message": "Market with ID 999 not found",
  "data": {}
}

The errorCode field is a machine-readable string you can use for programmatic error handling. Common error codes include validation errors (invalid parameters), state errors (insufficient margin), and not-found errors.

The Send Txs Bot and Stop Order services use the legacy format:

{
  "statusCode": 400,
  "message": "Invalid signature"
}

See Best Practices for error handling recommendations.

Rate Limiting

Boros uses a Computing Unit (CU) based rate-limit system — every endpoint advertises a per-call cost, and per-IP budgets apply. See Computing Units for budgets, per-endpoint costs, headers, and API-key tiers.

Code Examples

For complete working examples covering the full integration lifecycle, see:

https://github.com/pendle-finance/boros-api-examples

Key examples:

01-agent.ts — Agent setup and approval
02-deposit.ts to 04-withdraw.ts — Fund management
05-place-order.ts to 08-cancel-order.ts — Order lifecycle
11-bulk-place-orders.ts — Bulk order placement
12-top-up-gas-account.ts — Gas management
13-top-up-isolated-account.ts — Isolated margin funding

Base URLs​

API Services​

Open API (Primary)​

Send Txs Bot (Transaction Submission)​

Stop Order Service​

Integration Workflows​

1. First-Time Setup​

2. Placing a Trade (Agent Flow)​

3. Closing a Position​

4. Withdrawing Funds​

5. Setting Up Stop Orders (TP/SL)​

Sensitive vs Non-Sensitive Actions​

Endpoint Categories​

Assets​

Markets​

Accounts​

Market Acc Infos​

Active Positions​

Latest Settlements​

V2 Accounts (Cursor-Based Pagination)​

Calldata Generation​

Simulations​

Funding Rate​

Indicators​

Incentives​

Market Account Helpers​

Agents​

Events​

Charts​

Leaderboard​

Transaction Status (Send Txs Bot)​

Error Handling​

Rate Limiting​

Code Examples​

Base URLs

API Services

Open API (Primary)

Send Txs Bot (Transaction Submission)

Stop Order Service

Integration Workflows

1. First-Time Setup

2. Placing a Trade (Agent Flow)

3. Closing a Position

4. Withdrawing Funds

5. Setting Up Stop Orders (TP/SL)

Sensitive vs Non-Sensitive Actions

Endpoint Categories

Assets

Markets

Accounts

Market Acc Infos

Active Positions

Latest Settlements

V2 Accounts (Cursor-Based Pagination)

Calldata Generation

Simulations

Funding Rate

Indicators

Incentives

Market Account Helpers

Agents

Events

Charts

Leaderboard

Transaction Status (Send Txs Bot)

Error Handling

Rate Limiting

Code Examples