> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/cowprotocol/cow-sdk/llms.txt
> Use this file to discover all available pages before exploring further.
# OrderBookApi
> Direct API client for CoW Protocol OrderBook endpoints
## Overview
The `OrderBookApi` class provides direct access to the CoW Protocol OrderBook API. It handles quotes, order submission, order retrieval, cancellations, and trading data with built-in rate limiting, retries, and error handling.
## Installation
```bash theme={null}
npm install @cowprotocol/sdk-order-book
# or
pnpm add @cowprotocol/sdk-order-book
# or
yarn add @cowprotocol/sdk-order-book
```
## Constructor
```typescript theme={null}
new OrderBookApi(context?: PartialApiContext)
```
API configuration options
Chain ID (e.g., 1 for Mainnet, 100 for Gnosis Chain)
Environment to use
Partner API key for authenticated access with higher rate limits
Custom API endpoint URLs per chain
Rate limiter configuration
Exponential backoff configuration for retries
## Basic Setup
```typescript theme={null}
import { OrderBookApi, SupportedChainId } from '@cowprotocol/sdk-order-book'
const orderBookApi = new OrderBookApi({
chainId: SupportedChainId.MAINNET,
env: 'prod',
})
```
## Quote Methods
### getQuote
Get a quote for an order before signing and submitting.
```typescript theme={null}
async getQuote(
requestBody: OrderQuoteRequest,
contextOverride?: PartialApiContext
): Promise
```
Quote request parameters
Sell token address
Buy token address
User address
Receiver address (can be same as from)
Order kind
Sell amount (for sell orders)
Buy amount (for buy orders)
Allow partial fills
Signing scheme (eip712, ethsign, presign, eip1271)
Order expiration timestamp
App data hash (bytes32)
Quote price quality
Hydrated quote ready for signing
Quote details with all order parameters
User address
Quote expiration time
Quote ID
#### Example
```typescript theme={null}
const quoteRequest = {
sellToken: '0xA0b86a33E6417b528874E10EB3a95beb4F25A0E3', // GNO
buyToken: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH
from: '0x123...',
receiver: '0x123...',
sellAmountBeforeFee: '1000000000000000000', // 1 GNO
kind: 'sell',
}
const { quote } = await orderBookApi.getQuote(quoteRequest)
console.log('Quote:', quote)
```
## Order Management Methods
### sendOrder
Submit a signed order to the order book.
```typescript theme={null}
async sendOrder(
requestBody: OrderCreation,
contextOverride?: PartialApiContext
): Promise
```
Signed order data
Sell token address
Buy token address
Sell amount
Buy amount
Expiration timestamp
App data hash
Fee amount
Order kind
Partially fillable flag
Order signature
Signing scheme used
Order creator address
Unique order identifier
#### Example
```typescript theme={null}
import { OrderSigningUtils } from '@cowprotocol/sdk-order-signing'
// After getting a quote and signing it
const signingResult = await OrderSigningUtils.signOrder(
quote,
chainId,
signer
)
const orderId = await orderBookApi.sendOrder({
...quote,
...signingResult,
})
console.log('Order submitted:', orderId)
```
***
### getOrder
Retrieve order details by UID.
```typescript theme={null}
async getOrder(
orderUid: string,
contextOverride?: PartialApiContext
): Promise
```
Unique order identifier
Complete order information
Order unique identifier
Sell token address
Buy token address
Sell amount
Buy amount
Order status (open, fulfilled, cancelled, expired)
Order creation timestamp
Order owner address
#### Example
```typescript theme={null}
const order = await orderBookApi.getOrder(
'0xd64389693b6cf89ad6c140a113b10df08073e5ef...'
)
console.log('Order status:', order.status)
console.log('Sell amount:', order.sellAmount)
```
***
### getOrders
Get all orders for a specific owner.
```typescript theme={null}
async getOrders(
request: GetOrdersRequest,
contextOverride?: PartialApiContext
): Promise>
```
Query parameters
Owner address
Pagination offset
Maximum orders to return
List of orders
#### Example
```typescript theme={null}
const orders = await orderBookApi.getOrders({
owner: '0x123...',
limit: 10,
offset: 0,
})
console.log(`Found ${orders.length} orders`)
orders.forEach(order => {
console.log(`Order ${order.uid}: ${order.status}`)
})
```
***
### getOrderMultiEnv
Attempt to get an order from multiple environments (prod/staging).
```typescript theme={null}
async getOrderMultiEnv(
orderUid: string,
contextOverride?: PartialApiContext
): Promise
```
Order UID
Order found in any environment
#### Example
```typescript theme={null}
// Will check prod first, then staging
const order = await orderBookApi.getOrderMultiEnv(
'0xd64389693b6cf89ad6c140a113b10df08073e5ef...'
)
```
***
### sendSignedOrderCancellations
Cancel one or more orders (off-chain).
```typescript theme={null}
async sendSignedOrderCancellations(
requestBody: OrderCancellations,
contextOverride?: PartialApiContext
): Promise
```
Signed cancellation request
Array of order UIDs to cancel
Cancellation signature
Signing scheme
This is a "soft cancel" and may not prevent execution if the order is already being processed.
#### Example
```typescript theme={null}
import { OrderSigningUtils } from '@cowprotocol/sdk-order-signing'
const orderUids = ['0xd64389...', '0xa12345...']
const cancellationSigning = await OrderSigningUtils.signOrderCancellations(
orderUids,
chainId,
signer
)
await orderBookApi.sendSignedOrderCancellations({
...cancellationSigning,
orderUids,
})
console.log('Orders cancelled')
```
## Trading Data Methods
### getTrades
Get all trades for an owner or order.
```typescript theme={null}
async getTrades(
request: GetTradesRequest,
contextOverride?: PartialApiContext
): Promise>
```
Query parameters (must specify owner OR orderUid)
Owner address
Order UID
Pagination offset
Maximum trades to return
List of trades
#### Example
```typescript theme={null}
// Get all trades for an owner
const trades = await orderBookApi.getTrades({
owner: '0x123...',
limit: 20,
})
// Get trades for a specific order
const orderTrades = await orderBookApi.getTrades({
orderUid: '0xd64389...',
})
console.log(`Found ${trades.length} trades`)
```
***
### getTxOrders
Get all orders from a settlement transaction.
```typescript theme={null}
async getTxOrders(
txHash: string,
contextOverride?: PartialApiContext
): Promise>
```
Settlement transaction hash
Orders settled in the transaction
#### Example
```typescript theme={null}
const orders = await orderBookApi.getTxOrders(
'0xabc123...'
)
console.log(`Transaction included ${orders.length} orders`)
```
## Price & Data Methods
### getNativePrice
Get the native price of a token.
```typescript theme={null}
async getNativePrice(
tokenAddress: string,
contextOverride?: PartialApiContext
): Promise
```
ERC-20 token address
Native price (e.g., ETH price on Ethereum)
#### Example
```typescript theme={null}
const price = await orderBookApi.getNativePrice(
'0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' // USDC
)
console.log('Native price:', price)
```
***
### getTotalSurplus
Get total surplus earned by a user.
```typescript theme={null}
async getTotalSurplus(
address: string,
contextOverride?: PartialApiContext
): Promise
```
User address
Total surplus information
#### Example
```typescript theme={null}
const surplus = await orderBookApi.getTotalSurplus('0x123...')
console.log('Total surplus:', surplus)
```
## App Data Methods
### getAppData
Retrieve full app data for a given hash.
```typescript theme={null}
async getAppData(
appDataHash: string,
contextOverride?: PartialApiContext
): Promise
```
App data hash (bytes32)
Full app data content
#### Example
```typescript theme={null}
const appData = await orderBookApi.getAppData(
'0x0000000000000000000000000000000000000000000000000000000000000000'
)
console.log('App data:', appData)
```
***
### uploadAppData
Upload app data to the OrderBook.
```typescript theme={null}
async uploadAppData(
appDataHash: string,
fullAppData: string,
contextOverride?: PartialApiContext
): Promise
```
App data hash (bytes32)
Full app data content (JSON string)
Uploaded app data
#### Example
```typescript theme={null}
const fullAppData = JSON.stringify({
version: '1.0.0',
appCode: 'My App',
metadata: {},
})
const result = await orderBookApi.uploadAppData(
appDataHash,
fullAppData
)
```
## Competition & Analytics Methods
### getSolverCompetition
Get solver competition details for an auction.
```typescript theme={null}
async getSolverCompetition(
auctionIdOrTxHash: number | string,
contextOverride?: PartialApiContext
): Promise
```
Auction ID or transaction hash
Solver competition data
#### Example
```typescript theme={null}
// By auction ID
const competition = await orderBookApi.getSolverCompetition(12345)
// By transaction hash
const competition2 = await orderBookApi.getSolverCompetition('0xabc...')
```
***
### getOrderCompetitionStatus
Get competition status while order is open.
```typescript theme={null}
async getOrderCompetitionStatus(
orderUid: string,
contextOverride?: PartialApiContext
): Promise
```
Order UID
Competition status
## Utility Methods
### getVersion
Get API version.
```typescript theme={null}
async getVersion(
contextOverride?: PartialApiContext
): Promise
```
API version string
***
### getOrderLink
Generate API endpoint URL for an order.
```typescript theme={null}
getOrderLink(
orderUid: string,
contextOverride?: PartialApiContext
): string
```
Order UID
Full API URL to get the order
#### Example
```typescript theme={null}
const url = orderBookApi.getOrderLink('0xd64389...')
console.log('Order URL:', url)
```
## Partner API Usage
For authenticated access with higher rate limits:
```typescript theme={null}
const orderBookApi = new OrderBookApi({
chainId: SupportedChainId.MAINNET,
apiKey: 'your-partner-api-key',
env: 'prod',
})
```
This automatically routes requests through:
* Production: `https://partners.cow.fi`
* Staging: `https://partners.barn.cow.fi`
## Custom Configuration
### Rate Limiting
```typescript theme={null}
import { RateLimiterOpts } from 'limiter'
const limiterOpts: RateLimiterOpts = {
tokensPerInterval: 5,
interval: 'second',
}
const orderBookApi = new OrderBookApi({
chainId: SupportedChainId.MAINNET,
limiterOpts,
})
```
### Retry Configuration
```typescript theme={null}
import { BackoffOptions } from 'exponential-backoff'
const backoffOpts: BackoffOptions = {
numOfAttempts: 5,
maxDelay: Infinity,
jitter: 'none',
}
const orderBookApi = new OrderBookApi({
chainId: SupportedChainId.MAINNET,
backoffOpts,
})
```
### Custom Endpoints
```typescript theme={null}
const orderBookApi = new OrderBookApi({
chainId: SupportedChainId.MAINNET,
baseUrls: {
[SupportedChainId.MAINNET]: 'https://your-custom-endpoint.com',
},
})
```
## Error Handling
```typescript theme={null}
import { OrderBookApiError } from '@cowprotocol/sdk-order-book'
try {
const order = await orderBookApi.getOrder(orderUid)
} catch (error) {
if (error instanceof OrderBookApiError) {
console.error('API error:', error.response.status, error.message)
} else {
console.error('Unexpected error:', error)
}
}
```
## See Also
* [TradingSdk](/api/trading-sdk) - High-level trading interface
* [OrderSigningUtils](/api/order-signing-utils) - Order signing utilities
* [MetadataApi](/api/metadata-api) - Order metadata management