Skip to main content

Class: OrderBookApi

The CoW Protocol OrderBook API client.

This is the main entry point for interacting with the CoW Protocol OrderBook API. The main advantage of using this client is the batteries-included approach to interacting with the API. It handles:

  • Environment configuration (mainnet, staging, etc.)
  • Rate limiting
  • Retries
  • Backoff
  • Error handling
  • Request signing
  • Request validation

Example

import { OrderBookApi, OrderSigningUtils, SupportedChainId } from '@cowprotocol/cow-sdk'
import { Web3Provider } from '@ethersproject/providers'

const account = 'YOUR_WALLET_ADDRESS'
const chainId = 100 // Gnosis chain
const provider = new Web3Provider(window.ethereum)
const signer = provider.getSigner()

const quoteRequest = {
sellToken: '0x6a023ccd1ff6f2045c3309768ead9e68f978f6e1', // WETH gnosis chain
buyToken: '0x9c58bacc331c9aa871afd802db6379a98e80cedb', // GNO gnosis chain
from: account,
receiver: account,
sellAmountBeforeFee: (0.4 * 10 ** 18).toString(), // 0.4 WETH
kind: OrderQuoteSide.kind.SELL,
}

const orderBookApi = new OrderBookApi({ chainId: SupportedChainId.GNOSIS_CHAIN })

async function main() {
const { quote } = await orderBookApi.getQuote(quoteRequest)

const orderSigningResult = await OrderSigningUtils.signOrder(quote, chainId, signer)

const orderId = await orderBookApi.sendOrder({ ...quote, ...orderSigningResult })

const order = await orderBookApi.getOrder(orderId)

const trades = await orderBookApi.getTrades({ orderId })

const orderCancellationSigningResult = await OrderSigningUtils.signOrderCancellations([orderId], chainId, signer)

const cancellationResult = await orderBookApi.sendSignedOrderCancellations({...orderCancellationSigningResult, orderUids: [orderId] })

console.log('Results: ', { orderId, order, trades, orderCancellationSigningResult, cancellationResult })
}

See

Constructors

constructor

new OrderBookApi(context?): OrderBookApi

Creates a new instance of the CoW Protocol OrderBook API client.

Parameters

NameTypeDescription
contextPartial<ApiContext>The API context to use. If not provided, the default context will be used.

Returns

OrderBookApi

Defined in

external/cow-sdk/src/order-book/api.ts:138

Properties

context

context: ApiContext

Defined in

external/cow-sdk/src/order-book/api.ts:130


rateLimiter

Private rateLimiter: RateLimiter

Defined in

external/cow-sdk/src/order-book/api.ts:132

Methods

fetch

fetch<T>(params, contextOverride?): Promise<T>

Make a request to the API.

Type parameters

Name
T

Parameters

NameTypeDescription
paramsFetchParamsThe parameters for the request.
contextOverridePartial<ApiContext>Optional context override for this request.

Returns

Promise<T>

The response from the API.

Defined in

external/cow-sdk/src/order-book/api.ts:411


getApiBaseUrls

getApiBaseUrls(env): ApiBaseUrls

Get the base URLs for the API endpoints given the environment.

Parameters

NameTypeDescription
envCowEnvThe environment to get the base URLs for.

Returns

ApiBaseUrls

The base URLs for the API endpoints.

Defined in

external/cow-sdk/src/order-book/api.ts:399


getAppData

getAppData(appDataHash, contextOverride?): Promise<AppDataObject>

Retrieve the full app data for a given app data hash.

Parameters

NameTypeDescription
appDataHashstringbytes32 hash of the app data
contextOverridePartial<ApiContext>Optional context override for this request.

Returns

Promise<AppDataObject>

Full app data that was uploaded

Defined in

external/cow-sdk/src/order-book/api.ts:329


getContextWithOverride

getContextWithOverride(contextOverride?): ApiContext

Apply an override to the context for a request.

Parameters

NameTypeDescription
contextOverridePartial<ApiContext>Optional context override for this request.

Returns

ApiContext

New context with the override applied.

Defined in

external/cow-sdk/src/order-book/api.ts:390


getNativePrice

getNativePrice(tokenAddress, contextOverride?): Promise<NativePriceResponse>

Get the native price of a token.

NOTE: The native price is the price of the token in the native currency of the chain. For example, on Ethereum this would be the price of the token in ETH.

Parameters

NameTypeDescription
tokenAddressstringThe address of the ERC-20 token.
contextOverridePartial<ApiContext>Optional context override for this request.

Returns

Promise<NativePriceResponse>

The native price of the token.

Defined in

external/cow-sdk/src/order-book/api.ts:309


getOrder

getOrder(orderUid, contextOverride?): Promise<EnrichedOrder>

Get an order by its unique identifier, orderUid.

Parameters

NameTypeDescription
orderUidstringThe unique identifier of the order.
contextOverridePartial<ApiContext>Optional context override for this request.

Returns

Promise<EnrichedOrder>

The order matching the request.

Defined in

external/cow-sdk/src/order-book/api.ts:224


getOrderLink(orderUid, contextOverride?): string

Generate an API endpoint for an order by its unique identifier, orderUid.

Parameters

NameTypeDescription
orderUidstringThe unique identifier of the order.
contextOverride?Partial<ApiContext>Optional context override for this request.

Returns

string

The API endpoint to get the order.

Defined in

external/cow-sdk/src/order-book/api.ts:380


getOrderMultiEnv

getOrderMultiEnv(orderUid, contextOverride?): Promise<EnrichedOrder>

Attempt to get an order by its unique identifier, orderUid, from multiple environments.

NOTE: The environment refers to either prod or staging. This allows a conveience method to attempt to get an order from both environments, in the event that the order is not found in the environment specified in the context.

Parameters

NameTypeDescription
orderUidstringThe unique identifier of the order.
contextOverridePartial<ApiContext>Optional context override for this request.

Returns

Promise<EnrichedOrder>

The order matching the request.

Throws

If the order is not found in any of the environments.

Defined in

external/cow-sdk/src/order-book/api.ts:241


getOrders

getOrders(request, contextOverride?): Promise<EnrichedOrder[]>

Get a list of orders for a given owner.

Parameters

NameTypeDescription
requestGetOrdersRequestThe request parameters with request.offset = 0 and request.limit = 1000 by default.
contextOverridePartial<ApiContext>Optional context override for this request.

Returns

Promise<EnrichedOrder[]>

A list of orders matching the request.

See

Defined in

external/cow-sdk/src/order-book/api.ts:186


getQuote

getQuote(requestBody, contextOverride?): Promise<OrderQuoteResponse>

Get a quote for an order. This allows for the calculation of the total cost of an order, including fees, before signing and submitting.

Parameters

NameTypeDescription
requestBodyOrderQuoteRequestThe parameters for the order quote request.
contextOverridePartial<ApiContext>Optional context override for this request.

Returns

Promise<OrderQuoteResponse>

A hydrated order matching the request ready to be signed.

Defined in

external/cow-sdk/src/order-book/api.ts:269


getSolverCompetition

getSolverCompetition(auctionId, contextOverride?): Promise<SolverCompetitionResponse>

Given an auction id or tx hash, get the details of the solver competition for that auction.

Parameters

NameTypeDescription
auctionIdnumber-
contextOverride?Partial<ApiContext>Optional context override for this request.

Returns

Promise<SolverCompetitionResponse>

An object containing the solver competition details

Defined in

external/cow-sdk/src/order-book/api.ts:351

getSolverCompetition(txHash, contextOverride?): Promise<SolverCompetitionResponse>

Given an auction id or tx hash, get the details of the solver competition for that auction.

Parameters

NameTypeDescription
txHashstring-
contextOverride?Partial<ApiContext>Optional context override for this request.

Returns

Promise<SolverCompetitionResponse>

An object containing the solver competition details

Defined in

external/cow-sdk/src/order-book/api.ts:353


getTotalSurplus

getTotalSurplus(address, contextOverride?): Promise<TotalSurplus>

Given a user's address, get the total surplus that they have earned.

Parameters

NameTypeDescription
addressstringThe user's address
contextOverridePartial<ApiContext>Optional context override for this request.

Returns

Promise<TotalSurplus>

Calculated user's surplus

Defined in

external/cow-sdk/src/order-book/api.ts:319


getTrades

getTrades(request, contextOverride?): Promise<Trade[]>

Get all the trades for either an owner OR orderUid.

Given that an order may be partially fillable, it is possible that a discrete order (orderUid) may have multiple trades. Therefore, this method returns a list of trades, either for all the orders of a given owner, or for a discrete order (orderUid).

Parameters

NameTypeDescription
requestObjectEither an owner or an orderUid MUST be specified.
request.orderUid?string-
request.owner?string-
contextOverridePartial<ApiContext>Optional context override for this request.

Returns

Promise<Trade[]>

A list of trades matching the request.

Defined in

external/cow-sdk/src/order-book/api.ts:163


getTxOrders

getTxOrders(txHash, contextOverride?): Promise<EnrichedOrder[]>

Get a list of orders from a given settlement transaction hash.

Parameters

NameTypeDescription
txHashstringThe transaction hash.
contextOverridePartial<ApiContext>Optional context override for this request.

Returns

Promise<EnrichedOrder[]>

A list of orders matching the request.

See

EnrichedOrder

Defined in

external/cow-sdk/src/order-book/api.ts:209


getVersion

getVersion(contextOverride?): Promise<string>

Get the version of the API.

Parameters

NameTypeDescription
contextOverridePartial<ApiContext>Optional context override for this request.

Returns

Promise<string>

The version of the API.

See

https://api.cow.fi/docs/#/default/get_api_v1_version

Defined in

external/cow-sdk/src/order-book/api.ts:149


sendOrder

sendOrder(requestBody, contextOverride?): Promise<string>

Submit an order to the order book.

Parameters

NameTypeDescription
requestBodyOrderCreationThe signed order to be submitted.
contextOverridePartial<ApiContext>Optional context override for this request.

Returns

Promise<string>

The unique identifier of the order.

Defined in

external/cow-sdk/src/order-book/api.ts:296


sendSignedOrderCancellations

sendSignedOrderCancellations(requestBody, contextOverride?): Promise<void>

Cancel one or more orders.

NOTE: Cancellation is on a best-effort basis. Orders that are already in the process of being settled (ie. transaction has been submitted to chain by the solver) cannot not be cancelled. CAUTION: This method can only be used to cancel orders that were signed using EIP-712 or eth_sign (EIP-191).

Parameters

NameTypeDescription
requestBodyOrderCancellationsOrders to be cancelled and signed instructions to cancel them.
contextOverridePartial<ApiContext>Optional context override for this request.

Returns

Promise<void>

A list of order unique identifiers that were successfully cancelled.

Defined in

external/cow-sdk/src/order-book/api.ts:283


uploadAppData

uploadAppData(appDataHash, fullAppData, contextOverride?): Promise<AppDataObject>

Upload the full app data that corresponds to a given app data hash.

Parameters

NameTypeDescription
appDataHashstringbytes32 hash of the app data
fullAppDatastringFull app data to be uploaded
contextOverridePartial<ApiContext>Optional context override for this request.

Returns

Promise<AppDataObject>

The string encoding of the full app data that was uploaded.

Defined in

external/cow-sdk/src/order-book/api.ts:340