Pendle SDK Boros

Overview

Below is the documentation for the SDK. For more details about the overall architecture, contracts, API, and more, please refer to the documentation folder.

The repository is organized as follows:

• documentation:
  • lite-paper: lite paper for how boros works
  • contracts-docs: contains the documentation to deep dive into the contracts, the overall architecture, and terminology
  • API.docs.md: API documentation
  • SDK.docs.md: SDK documentation
  • example: example code for the SDK
• src: contains the source code of the SDK

You can start with the lite paper to understand the overall architecture and mechanics of the platform.

Then you can go to the API docs to understand the API and parameters. After that, you can refer to SDK docs and example to see how to use the SDK.

Installation

To use the SDK, you can install it using yarn. Our SDK is yet to be published to npm, so you need to config private credentials to install it. Can have a look at .yarnrc.yml for more details.

export PENDLE_SDK_BOROS_NPM_AUTH_TOKEN=<your-npm-auth-token>
# config your .yarnrc.yml follow our .yarnrc.yml file
# then install the package
yarn add @pendle/sdk-boros

Initialization

constructor(walletClient: WalletClient, root: Address, accountId: number)

The Exchange class requires three parameters for initialization:

• walletClient: A viem WalletClient instance for signing transactions
• root: The wallet address (Address type from viem)
• accountId: The numerical ID of the account to interact with

Example:

import { createWalletClient, http } from 'viem';
import { Exchange } from 'pendle-sdk-boros';

const account = privateKeyToAccount(PRIVATE_KEY);

const walletClient = createWalletClient({
  transport: http(RPC_URL),
  account: account,
});

const exchange = new Exchange(
  walletClient,
  '0xYourWalletAddress',
  0 // accountId
);

Example Flow: Creating an Agent and Placing an Order

Below is a complete example showing how to create an agent, approve it, and place an order:

import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { Exchange, Agent, Side, TimeInForce, MarketAccLib } from 'pendle-sdk-boros';

// Setup wallet client
const PRIVATE_KEY = '0xYourPrivateKey';
const RPC_URL = 'https://your-rpc-endpoint.com';
const account = privateKeyToAccount(PRIVATE_KEY);
const accountId = 0;

const walletClient = createWalletClient({
  transport: http(RPC_URL),
  account: account,
});

async function placeOrderExample() {
  const exchange = new Exchange(
    walletClient,
    account.address,
    accountId
  );
  
  const agent = await Agent.create(walletClient);
  
  const approvalTx = await exchange.approveAgent(agent);
  console.log('Agent approved:', approvalTx);
  const tokenId = 0;
  const marketId = 0;

  const marketAcc = MarketAccLib.pack(account.address, accountId, tokenId, marketId)
  
  const orderResult = await exchange.placeOrder({
    marketAcc: marketAcc,
    marketAddress: '0xMarketAddress',
    ammAddresses: ['0xAmmAddress1'],
    side: Side.LONG,
    size: 100000000000000000000n, // 100 tokens with 18 decimals
    limitTick: 1000,
    tif: TimeInForce.GOOD_TIL_CANCELLED,
    useOrderBook: true
  });
  
  console.log('Order placed:', orderResult);
  
  return orderResult;
}

placeOrderExample()
  .then(result => console.log('Example completed successfully'))
  .catch(error => console.error('Error in example:', error));

This example demonstrates the complete flow from initializing the Exchange class to successfully placing an order. The agent creation and approval steps are required before you can place orders on the platform.

Order Management

Place Order

async placeOrder(params: PlaceOrderParams): Promise<{
  executeResponse: any;
  result: { order: any };
}>

Places a new order on the exchange.

Parameters:

• marketAcc: Use MarketAccLib to pack
• marketAddress: Address of the market
• ammAddresses: Array of AMM addresses
• side: Trade side (Enum: Side)
• size: Order size as bigint
• limitTick: The tick price limit
• tif: Time-in-force setting enum (GOOD_TIL_CANCELLED = 0, IMMEDIATE_OR_CANCEL = 1, FILL_OR_KILL = 2, POST_ONLY = 3)
• useOrderBook: Boolean indicating whether to use the order book

Example:

const result = await exchange.placeOrder({
  marketAcc: '0xMarketAccHex',
  marketAddress: '0xMarketAddress',
  ammAddresses: ['0xAmmAddress1', '0xAmmAddress2'],
  side: Side.LONG,
  size: 100000000000000000000n, // 100 tokens with 18 decimals
  limitTick: 1000,
  tif: TimeInForce.GOOD_TIL_CANCELLED,
  useOrderBook: true
});

Bulk Place Orders

async bulkPlaceOrders(orderRequests: PlaceOrderParams[]): Promise<Array<{
  executeResponse: any;
  result: { order: any };
}>>

Places multiple orders in a single transaction.

Parameters:

• orderRequests: Array of PlaceOrderParams objects

Example:

const results = await exchange.bulkPlaceOrders([
  {
    marketAcc: '0xMarketAccHex1',
    marketAddress: '0xMarketAddress1',
    ammAddresses: ['0xAmmAddress1'],
    side: Side.LONG,
    size: 100000000000000000000n,
    limitTick: 1000,
    tif: TimeInForce.GOOD_TIL_CANCELLED,
    useOrderBook: true
  },
  {
    marketAcc: '0xMarketAccHex2',
    marketAddress: '0xMarketAddress2',
    ammAddresses: ['0xAmmAddress2'],
    side: Side.SHORT,
    size: 50000000000000000000n,
    limitTick: 950,
    tif: TimeInForce.POST_ONLY,
    useOrderBook: true
  }
]);

Modify Order

async modifyOrder(params: ModifyOrderParams): Promise<{
  executeResponse: any;
  result: { order: any };
}>

Modifies an existing order.

Parameters:

• orderId: ID of the order to modify
• marketAcc: Hexadecimal market account identifier
• marketAddress: Address of the market
• size: New order size as bigint
• limitTick: New tick price limit
• tif: New time-in-force setting

Example:

const result = await exchange.modifyOrder({
  orderId: '123456789',
  marketAcc: '0xMarketAccHex',
  marketAddress: '0xMarketAddress',
  size: 150000000000000000000n, // 150 tokens with 18 decimals
  limitTick: 1050,
  tif: TimeInForce.GOOD_TIL_CANCELLED
});

Bulk Modify Orders

async bulkModifyOrder(orderRequests: ModifyOrderParams[]): Promise<Array<{
  executeResponse: any;
  result: { order: any };
}>>

Modifies multiple orders.

Parameters:

• orderRequests: Array of ModifyOrderParams objects

Cancel Orders

async cancelOrders(params: CancelOrdersParams): Promise<{
  executeResponse: any;
  result: { cancelledOrders: any };
}>

Cancels one or more orders.

Parameters:

• marketAcc: Use MarketAccLib to get
• marketAddress: Address of the market
• cancelAll: Boolean indicating whether to cancel all orders
• orderIds: Array of order IDs to cancel (used when cancelAll is false)

Example:

// Cancel specific orders
const result = await exchange.cancelOrders({
  marketAcc: '0xMarketAccHex',
  marketAddress: '0xMarketAddress',
  cancelAll: false,
  orderIds: ['123456789', '987654321']
});

// Cancel all orders
const result = await exchange.cancelOrders({
  marketAcc: '0xMarketAccHex',
  marketAddress: '0xMarketAddress',
  cancelAll: true,
  orderIds: []
});

Bulk Cancel Orders

async bulkCancelOrders(cancelOrderRequests: CancelOrdersParams[]): Promise<Array<{
  executeResponse: any;
  result: { cancelledOrders: any };
}>>

Cancels multiple orders from different markets.

Parameters:

• cancelOrderRequests: Array of CancelOrdersParams objects

Agent Management

Approve Agent

async approveAgent(agent?: Agent): Promise<any>

Approves an agent for transaction signing.

Parameters:

• agent: Optional Agent instance. If not provided, a new agent will be created.

Example:

// Approve a new agent
const agentApproval = await exchange.approveAgent();

// Approve a specific agent
import { Agent } from 'pendle-sdk-boros';
const customAgent = await Agent.create(walletClient);
const agentApproval = await exchange.approveAgent(customAgent.agent);

Funds Management

Deposit

async deposit(params: DepositParams): Promise<any>

Deposits funds into the exchange.

Parameters:

• userAddress: Address of the user
• collateralAddress: Address of the collateral token
• amount: Amount to deposit as bigint

Example:

const receipt = await exchange.deposit({
  userAddress: '0xYourWalletAddress',
  collateralAddress: '0xTokenAddress',
  amount: 1000000000000000000n // 1 token with 18 decimals
});

Withdraw

async withdraw(params: WithdrawParams): Promise<any>

Withdraws funds from the exchange.

Parameters:

• userAddress: Address of the user
• collateralAddress: Address of the collateral token
• amount: Amount to withdraw as bigint

Example:

const receipt = await exchange.withdraw({
  userAddress: '0xYourWalletAddress',
  collateralAddress: '0xTokenAddress',
  amount: 1000000000000000000n // 1 token with 18 decimals
});

Cash Transfer

async cashTransfer(params: CashTransferParams): Promise<any>

Transfers cash between markets.

Parameters:

• marketId: ID of the market
• isDeposit: true if transferring from vault to marketId
• amount: Amount to transfer as bigint

Example:

const response = await exchange.cashTransfer({
  marketId: 1,
  isDeposit: true,
  amount: 1000000000000000000n // 1 token with 18 decimals
});

Position Management

Close Active Positions

async closeActivePositions(params: CloseActivePositionsParams): Promise<any>

Closes active positions.

Parameters:

• marketAcc: Hexadecimal market account identifier
• marketAddress: Address of the market
• type: Type of closing ("market" or "limit")
• size: Size to close as bigint
• rate: Optional rate for limit closings

Example:

// Close with market order
const response = await exchange.closeActivePositions({
  marketAcc: '0xMarketAccHex',
  marketAddress: '0xMarketAddress',
  type: "market",
  size: 100000000000000000000n // 100 tokens with 18 decimals
});

// Close with limit order
const response = await exchange.closeActivePositions({
  marketAcc: '0xMarketAccHex',
  marketAddress: '0xMarketAddress',
  type: "limit",
  size: 100000000000000000000n,
  rate: 0.05 // 5% rate
});

Settings Management

Update Settings

async updateSettings(params: UpdateSettingsParams): Promise<any>

Updates account settings.

Parameters:

• marketAcc: Hexadecimal market account identifier
• marketAddress: Address of the market
• leverage: Leverage value
• signature: Signature as hexadecimal
• agent: Agent address as hexadecimal
• timestamp: Timestamp

Example:

const response = await exchange.updateSettings({
  marketAcc: '0xMarketAccHex',
  marketAddress: '0xMarketAddress',
  leverage: 5, // 5x leverage
  signature: '0xSignatureHex',
  agent: '0xAgentAddress',
  timestamp: Math.floor(Date.now() / 1000)
});

Data Retrieval

Get Markets

async getMarkets(params: GetMarketsParams): Promise<any>

Retrieves market data.

Parameters:

• skip: Optional number of records to skip
• limit: Optional limit on the number of records
• isWhitelisted: Optional filter for whitelisted markets

Example:

const markets = await exchange.getMarkets({
  skip: 0,
  limit: 10,
  isWhitelisted: true
});

Get Order Book

async getOrderBook(params: GetOrderBookParams): Promise<any>

Retrieves the order book for a market.

Parameters:

• marketAddress: Address of the market
• tickSize: Tick size (0.00001, 0.0001, 0.001, 0.01, or 0.1)

Example:

const orderBook = await exchange.getOrderBook({
  marketAddress: '0xMarketAddress',
  tickSize: 0.001
});

Get PnL Limit Orders

async getPnlLimitOrders(params: GetPnlLimitOrdersParams): Promise<any>

Retrieves PnL (Profit and Loss) limit orders.

Parameters:

• skip: Optional number of records to skip
• limit: Optional limit on the number of records
• isActive: Optional filter for active orders
• marketAddress: Optional filter for a specific market
• orderBy: Optional field to order by ('timeClosed', 'positionSize', 'avgFixedApr', 'avgUnderlyingApr', 'pnl')

Example:

const pnlOrders = await exchange.getPnlLimitOrders({
  skip: 0,
  limit: 10,
  isActive: true,
  marketAddress: '0xMarketAddress',
  orderBy: 'pnl'
});

Get Collaterals

async getCollaterals(): Promise<any>

Retrieves collateral information for the current user and account.

Example:

const collaterals = await exchange.getCollaterals();

Get Active Positions

async getActivePositions(params: GetActivePositionsParams): Promise<any>

Retrieves active positions.

Parameters:

• marketAddress: Optional filter for a specific market

Example:

// Get all active positions
const allPositions = await exchange.getActivePositions({});

// Get active positions for a specific market
const marketPositions = await exchange.getActivePositions({
  marketAddress: '0xMarketAddress'
});

Get Closed Positions

async getClosedPositions(params: GetClosedPositionsParams): Promise<any>

Retrieves closed positions.

Parameters:

• marketAddress: Optional filter for a specific market
• skip: Optional number of records to skip
• limit: Optional limit on the number of records
• orderBy: Optional field to order by ('timeClosed', 'positionSize', 'avgFixedApr', 'avgUnderlyingApr', 'pnl')

Example:

const closedPositions = await exchange.getClosedPositions({
  marketAddress: '0xMarketAddress',
  skip: 0,
  limit: 10,
  orderBy: 'timeClosed'
});