Boros API Best Practices

This guide provides recommendations and common patterns for integrating with the Boros API efficiently.

---

Bulk Order Placement

When placing multiple orders simultaneously, always use the bulk order endpoint instead of making multiple single order requests.

Why Use Bulk Orders?

Approach	Gas Cost	Atomicity	Network Overhead
Multiple single orders	High (N transactions)	None (partial failures possible)	High
Bulk orders	Low (1 transaction)	Atomic (all or nothing)	Low

Benefits

1. Lower Gas Fees — Multiple operations batched into a single transaction
2. Atomic Execution — All operations execute together, eliminating partial execution risks
3. Better Performance — Reduces network overhead and speeds up execution
4. Complex Strategies — Combine cancellations and new orders in one operation

注意

Unlike single order placement (placeSingleOrder), bulk orders do NOT match with the AMM. They are placed directly into the order book. If you need to take liquidity from both the order book and the AMM, use single order placement with IOC or FOK time-in-force.

Examples

• Bulk Place Orders Example
• Place Orders API

---

Transaction Submission

direct-call vs bulk-direct-call

The Send Txs Bot provides two submission endpoints:

Endpoint	Use case
POST /v2/agent/direct-call	Submit a single calldata
POST /v2/agent/bulk-direct-call	Submit one or more calldatas with sequential execution

v2 vs v3 Send Txs Bot

Both v2 and v3 expose bulk-direct-call, but they have different request schemas:

• v2 (BulkAgentExecuteDto) — no session required. Use this for programmatic / API integrations.
• v3 (BulkAgentExecuteV2Dto) — requires a mandatory agentSession field (HTTP-only cookie / CSRF token). Use this for browser-based UIs only.

Unless you are building a browser UI with session management, always use v2.

When to use bulk-direct-call: Whenever you have more than one calldata to submit in a single batch — for example, the N calldatas returned by a bulk POST /calldata/place-orders, or a cancel-and-replace pair where you want them to execute in order. bulk-direct-call accepts an array of signed calldatas and executes them sequentially.

Market entry on the new mount

The new Open API at https://api-boros.pendle.finance/apis/ does not auto-prepend an exit-market or enter-market calldata. If you need to enter a market before trading, call POST /calldata-builder/agent/enter-markets explicitly and include its calldata in the same bulk-direct-call batch (or submit it earlier).

The legacy autoExitMarket parameter only applies to the deprecated mount at https://api.boros.finance/open-api/v1/calldata/place-order (singular). On the new plural endpoint, market entry/exit is your responsibility.

skipReceipt Parameter

Controls whether the Send Txs Bot waits for block confirmation:

• skipReceipt=false (default): Waits for the transaction to be included in a block, then returns status and error fields. Higher latency but gives immediate confirmation.
• skipReceipt=true: Returns the txHash immediately after broadcasting. Lower latency but you must track the transaction status yourself.

---

Market Management

Exit Unused Markets

If you have entered markets that are no longer in use, exit them to reduce gas costs on future operations.

When you enter a market, the system tracks your participation for margin calculations. Each entered market adds overhead to the margin tracker, making it more expensive in gas for every subsequent transaction.

Important limitations:

• Maximum 10 entered markets per marketAcc (market account). This limit is per combination of (address, accountId, tokenId) — i.e., per collateral type.
• Maximum active limit orders per marketAcc per market (configurable per market via maxOpenOrders, typically 100)
• Entering more markets = heavier margin calculations = higher gas costs

提示

If you trade many markets over time (e.g., weekly expiry markets), you will hit the 10-market limit. You must exit expired/matured markets to free up slots for new ones. Call POST /calldata-builder/agent/exit-markets with the matured marketIds and submit the calldata via the Send Txs Bot.

Exiting unused markets helps:

• Reduce gas consumption on all subsequent transactions
• Free up slots for new markets (10 market limit)
• Improve transaction performance

When to Exit Markets

• After closing all positions in a market
• When you no longer plan to trade a specific market
• During account cleanup/maintenance
• Before market expiry (for dated markets)

To exit a market, you must first:

1. Close all positions (zero position size)
2. Cancel all open orders
3. Have no pending settlements

Isolated-Only Markets

Some markets are isolated-only, meaning they cannot be traded from a cross-margin account. For these markets:

1. Deposit to the isolated account — You must transfer collateral specifically to the isolated market account, not the cross-margin account
2. Use the correct marketAcc — Pack the marketAcc with the specific marketId instead of CROSS_MARKET_ID

import { MarketAccLib } from "@pendle/boros-sdk-public";

// For isolated-only markets, use the specific marketId
const isolatedMarketAcc = MarketAccLib.pack(
  walletAddress,
  accountId,
  tokenId,
  marketId  // Use the specific market ID, NOT CROSS_MARKET_ID
);

To fund an isolated account, either:

• Direct deposit: Deposit directly to the isolated market using the marketId in the deposit calldata
• Cash transfer: Transfer from cross-margin to isolated using the /calldata/cash-transfer endpoint with isDeposit: true

Example: Top Up Isolated Account

---

Gas Usage and Estimation

Monitor Gas Balance

Boros uses a gas account system for executing agent-signed transactions. Always monitor your gas balance to avoid failed transactions.

Key endpoints:

• GET /accounts/gas-balance — Check current balance
• GET /accounts/gas-consumption-history — Review usage patterns
• GET /calldata/vault-pay-treasury — Top up gas balance (sensitive, root-signed)

Arbitrum Gas Spikes

Arbitrum gas prices can spike significantly during high network activity. Consider:

1. Monitor gas prices before submitting transactions
2. Maintain buffer in your gas account for unexpected spikes
3. Check gas consumption history to understand your usage patterns

Example: Top Up Gas Account

---

Error Handling

Error Response Formats

The Open API uses a structured error format:

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

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

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

Handling Common Errors

Error	Cause	Solution
Insufficient margin	Not enough collateral for the position	Deposit more, reduce size, or close other positions
Agent expired	Agent approval has expired	Re-approve agent via GET /calldata/approve-agent
Invalid signature	Signature doesn't match the expected signer	Verify you're signing with the correct agent key
Market not entered	Trying to trade on a market you haven't entered	Call POST /calldata-builder/agent/enter-markets first, then place
Order limit reached	Exceeded maxOpenOrders for the market	Cancel some existing orders before placing new ones
Market limit reached	Over 10 entered markets	Exit unused markets to free up slots

Retry Strategy

• Don't retry immediately on validation errors (bad parameters, insufficient margin) — fix the root cause
• Retry with backoff on transient errors (network timeouts, 503s)
• Check transaction status before retrying submissions to the Send Txs Bot — the original may have succeeded

Recovering from Network Errors (Trace + Nonce)

When a Send Txs Bot submission times out or returns a network error, you can't tell whether the bot received the request. Use the trace endpoint (POST /send-txs-bot/v1/agent/dedicated/trace) to disambiguate before retrying.

Recommended pattern:

1. After a network error/timeout, poll the trace endpoint with the agent address and the nonce of the calldata you submitted.
2. If the request can be traced, the bot received it — wait for the on-chain result instead of retrying.
3. If it cannot be traced after 2–3 seconds, assume the bot never received it and retry safely.

Trace records are retained for 24 hours.

Why retry is safe

The Send Txs Bot rejects any calldata signed with a nonce ≤ your largest previously-seen nonce — and this guarantee includes nonces from calldata that failed simulation. So if the original submission had actually succeeded, the retry would be rejected by the backend rather than re-executed. You cannot double-submit by retrying.

---

Simulation Before Execution

Always use the simulation endpoints before executing trades, especially for:

• Large orders — preview margin impact and fees
• Close positions — verify the counter-order parameters
• Deposits/withdrawals — check that the operation won't cause under-margining

Simulations are free (no gas) and return the projected account state. The key simulation endpoints:

Endpoint	Use case
GET /simulations/place-order	Preview order placement
GET /simulations/close-active-position	Preview closing a position
GET /simulations/deposit	Preview deposit effect
GET /simulations/withdraw	Preview withdrawal effect
GET /simulations/cash-transfer	Preview cross ↔ isolated transfer

---

Real-Time Data

Market Data Latency

Not all REST endpoints have the same latency characteristics. For latency-sensitive indicators, use the correct endpoint:

Data	Best endpoint	Latency
midApr, bestBid, bestAsk, ammImpliedApr, markApr	GET /open-api/v1/markets/{marketId}	Real-time
Order book depth	GET /open-api/v2/markets/order-books?marketId={marketId}	< 1 second
AMM state	GET /core/amm/{ammId}	< 1 second
Market list / overview	GET /open-api/v1/markets	May have several seconds of delay

提示

For market making or any use case requiring live mid/mark rates, always use the single market endpoint (GET /open-api/v1/markets/{marketId}) rather than the bulk markets list. The bulk endpoint may have a delay of several seconds on sensitive indicators.

Combined Order Book (AMM + Order Book)

The order book displayed in the Boros UI and returned by GET /v2/markets/order-books (with AMM enabled) is a combined order book that merges:

• Order book liquidity: Discrete maker orders at specific tick levels
• AMM liquidity: Continuous liquidity from the AMM, discretized into tick levels for display

Important: The AMM has a minimum and maximum APR range. When the market rate moves outside this range, the AMM stops providing liquidity. In this case, the combined order book may show a wider spread since only order book liquidity remains.

Note: Some markets may have no AMM at all. In these markets, all liquidity comes from the order book only, and placeSingleOrder behaves the same as bulkOrders (no AMM to route through). Check the market's ammId — if absent or null, there is no AMM.

The AMM implied rate should normally be within the range (bestBid - ε, bestAsk + ε) where ε is a small amount to prevent arbitrage between the AMM and the order book.

Use WebSocket for Streaming

Don't poll REST endpoints for real-time data. Use WebSocket for:

• Order book updates: orderbook:MARKET_ID:TICK_SIZE
• Trade events: market-trade:MARKET_ID
• Market statistics: statistics:MARKET_ID
• Account changes: account:ADDRESS:ACCOUNT_ID

Caching Strategy

Data	Cache duration	Refresh trigger
Assets list	Long (hours)	Rarely changes
Market list	Medium (minutes)	New markets added infrequently
Market state / order book	Don't cache	Use WebSocket
Account positions	Don't cache	Use WebSocket account channel
Gas balance	Short (seconds)	After each transaction

---

Market Maker Order Flow

The calldata endpoints (e.g., POST /calldata/place-orders) return a list of calldatas. You sign each calldata with your agent key, then send them to POST /send-txs-bot/v2/agent/bulk-direct-call.

When submitting, set the requireSuccess parameter to control atomicity:

• requireSuccess=true — All calldatas are placed atomically (all succeed or all revert).
• requireSuccess=false — Each calldata is placed independently; some may succeed while others fail.

Full Flow

┌──────────────────────────────────────────────────────────────────────┐
│  1. POST /calldata/place-orders          → calldatas[]              │
│  2. Sign each calldata with agent key                               │
│  3. POST /send-txs-bot/v2/agent/bulk-direct-call                   │
│     with requireSuccess=true or false    → tx results               │
└──────────────────────────────────────────────────────────────────────┘

requireSuccess Parameter (Send Txs Bot)

The requireSuccess parameter on bulk-direct-call controls whether the calldatas execute atomically:

Value	Behavior	Use case
true (default)	All calldatas succeed together or all revert	Place multiple orders atomically
false	Each calldata executes independently; some may succeed while others fail	Placing multiple independent orders (e.g., market making quotes on both sides)

When to use requireSuccess=false

If you are a market maker placing multiple orders across different markets or at different price levels, use requireSuccess=false. This way, if one order fails (e.g., due to insufficient margin for that specific order), the remaining orders can still be placed successfully.

---

Security

Key Management

• Never expose your root private key in client-side code or logs
• Use the agent system — the agent key has limited permissions and cannot withdraw funds
• Rotate agent keys periodically by revoking the old agent and approving a new one
• Set reasonable expiry times on agent approvals

Transaction Verification

• Always simulate before executing to verify expected outcomes
• Check the to address in calldata responses matches the expected Router contract
• Verify transaction status after submission — don't assume success

---

Summary

Best Practice	Why
Use bulk orders for multiple operations	Lower gas, atomic execution
Use bulk-direct-call whenever you have ≥1 calldata to submit	Sequential ordered execution; supports requireSuccess atomicity
Use requireSuccess=false for independent orders	Lets each order succeed/fail independently (market making)
Call enter-markets explicitly before trading a new market	New Open API mount does not auto-enter; place calls revert otherwise
Exit unused/expired markets via exit-markets (max 10 per account)	Reduce gas overhead, free up slots
Use GET /open-api/v1/markets/{marketId} for real-time rates	Guaranteed real-time midApr, markApr, bestBid, bestAsk
Use correct marketAcc for isolated-only markets	Required for trading isolated-only markets
Monitor gas balance	Avoid failed transactions
Simulate before executing	Preview margin impact and catch errors
Use WebSocket for real-time data	Lower latency, less overhead than polling
Handle errors by format (Open API vs legacy)	Different services use different formats
Never expose root key; use agents	Security best practice

For complete working examples, visit: https://github.com/pendle-finance/boros-api-examples