Merge pull request #228 from pendle-finance/longhv/working1403

docs: Boros API & WebSocket — v2 pagination, collateral, new endpoints

Author: nerax1s

docs/boros-dev-docs/Backend/3. api.mdx

@@ -90,6 +90,7 @@ Once your agent is approved, this is the typical order placement flow:
 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.
 :::
 
+
 ### 3. Closing a Position
 
 ```text
@@ -176,10 +177,10 @@ Query and manage user account state.
 
 | Endpoint | Description |
 |----------|-------------|
-| `POST /accounts/market-acc-infos` | Positions, margins, balances for market accounts |
+| `POST /accounts/market-acc-infos` | Positions, margins, balances for market accounts. See [details below](#market-acc-infos). |
 | `GET /accounts/entered-markets` | Markets entered by a cross-margin account |
-| `GET /accounts/active-positions` | All active positions for a user |
-| `GET /accounts/latest-settlements` | Latest settlement info per position |
+| `GET /accounts/active-positions` | All active positions for a user. See [details below](#active-positions). |
+| `GET /accounts/latest-settlements` | Latest settlement per market position. See [details below](#latest-settlements). |
 | `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 |
@@ -189,9 +190,70 @@ Query and manage user account state.
 | `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 without leverage |
+| `initialMarginWithLeverage` | string | Initial margin with leverage applied |
+| `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`).
+
+#### 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 — no `countDocuments()` overhead and no performance degradation on later pages.
+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:**
 1. Make the initial request with `limit` (no `resumeToken`)
@@ -235,8 +297,10 @@ Generate transaction calldata for on-chain operations.
 | 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 /send-txs-bot/v1/agent/cash-swap` | Swap collateral between different token types (agent-signed, EIP-712). Requires `fromTokenId`, `fromMarketId`, `toTokenId`, `toMarketId`, `unscaledSpent`, `minUnscaledReceived`, and `nonce`. |
 | `GET /calldata/enter-exit-markets` | Enter or exit markets |
 | `GET /calldata/pay-treasury` | Pay accrued treasury fees |
 | `GET /calldata/add-liquidity-single-cash-to-amm` | Add AMM liquidity |
@@ -254,6 +318,7 @@ Preview operations before executing them. All simulation endpoints return the pr
 | `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 |
+| `GET /simulations/cash-swap` | Preview collateral swap between token types. Returns `fromAccState` and `toAccState` with pre/post simulation. Requires `userAddress`, `accountId`, `fromTokenId`, `fromMarketId`, `toTokenId`, `toMarketId`, `unscaledSpent`, `estimatedReceived`. |
 
 ### Funding Rate
 Access funding rate data and settlement history.