feat: add API endpoints for partners (cowprotocol#809)

ahhda · web-flow · commit 59900e854a33 · 2026-03-04T14:29:14.000+05:00
diff --git a/packages/config/src/types/configs.ts b/packages/config/src/types/configs.ts
@@ -66,11 +66,13 @@ export type ApiBaseUrls = Record<SupportedChainId, string>
  * @property {SupportedChainId} chainId The `chainId`` corresponding to this CoW Protocol API instance.
  * @property {CowEnv} env The environment that this context corresponds to.
  * @property {ApiBaseUrls} [baseUrls] URls that may be used to connect to this context.
+ * @property {string} [apiKey] API key for Partner API (partners.cow.fi). When set, requests use the partner gateway and include X-API-Key header.
  */
 export interface ApiContext {
   chainId: SupportedChainId
   env: CowEnv
   baseUrls?: ApiBaseUrls
+  apiKey?: string
   limiterOpts?: RateLimiterOpts
   backoffOpts?: BackoffOptions
 }
diff --git a/packages/contracts-ts/src/api.ts b/packages/contracts-ts/src/api.ts
@@ -10,19 +10,27 @@ export enum Environment {
 
 export const LIMIT_CONCURRENT_REQUESTS = 5
 
-export function apiUrl(environment: Environment, network: string): string {
+const PARTNER_PROD_BASE_URL = 'https://partners.cow.fi'
+const PARTNER_DEV_BASE_URL = 'https://partners.barn.cow.fi'
+
+export function apiUrl(environment: Environment, network: string, apiKey?: string): string {
+  let baseUrl: string
   switch (environment) {
     case Environment.Dev:
-      return `https://barn.api.cow.fi/${network}`
+      baseUrl = apiKey ? PARTNER_DEV_BASE_URL : 'https://barn.api.cow.fi'
+      break
     case Environment.Prod:
-      return `https://api.cow.fi/${network}`
+      baseUrl = apiKey ? PARTNER_PROD_BASE_URL : 'https://api.cow.fi'
+      break
     default:
       throw new Error('Invalid environment')
   }
+  return `${baseUrl}/${network}`
 }
 
 export interface ApiCall {
   baseUrl: string
+  apiKey?: string
 }
 
 export interface EstimateTradeAmountQuery {
@@ -126,9 +134,18 @@ function apiSigningScheme(scheme: SigningScheme): string {
   }
 }
 
-async function call<T>(route: string, baseUrl: string, init?: RequestInit): Promise<T> {
+async function call<T>(
+  route: string,
+  baseUrl: string,
+  init?: RequestInit,
+  apiKey?: string,
+): Promise<T> {
   const url = `${baseUrl}/api/v1/${route}`
-  const response = await fetch(url, init)
+  const headers: Record<string, string> = {
+    ...((init?.headers as Record<string, string>) ?? {}),
+    ...(apiKey ? { 'X-API-Key': apiKey } : {}),
+  }
+  const response = await fetch(url, { ...init, headers })
   const body = await response.text()
   if (!response.ok) {
     const error: CallError = new Error(
@@ -150,6 +167,7 @@ async function estimateTradeAmount({
   kind,
   amount,
   baseUrl,
+  apiKey,
 }: EstimateTradeAmountQuery & ApiCall): Promise<BigIntish> {
   const side: BuyAmountAfterFee | SellAmountAfterFee =
     kind == OrderKind.SELL
@@ -162,7 +180,7 @@ async function estimateTradeAmount({
           buyAmountAfterFee: amount,
         }
   const { quote } = await getQuote(
-    { baseUrl },
+    { baseUrl, apiKey },
     {
       from: '0x0000000000000000000000000000000000000000',
       sellToken,
@@ -182,10 +200,19 @@ async function estimateTradeAmount({
   return getGlobalAdapter().utils.toBigIntish(estimatedAmount)
 }
 
-async function placeOrder({ order, signature, baseUrl, from }: PlaceOrderQuery & ApiCall): Promise<string> {
+async function placeOrder({
+  order,
+  signature,
+  baseUrl,
+  from,
+  apiKey,
+}: PlaceOrderQuery & ApiCall): Promise<string> {
   const normalizedOrder = normalizeOrder(order)
   const adapter = getGlobalAdapter()
-  return await call('orders', baseUrl, {
+  return await call(
+    'orders',
+    baseUrl,
+    {
     method: 'post',
     body: JSON.stringify({
       sellToken: normalizedOrder.sellToken,
@@ -203,15 +230,24 @@ async function placeOrder({ order, signature, baseUrl, from }: PlaceOrderQuery &
       from,
     }),
     headers: { 'Content-Type': 'application/json' },
-  })
+  },
+    apiKey,
+  )
 }
 
-async function getExecutedSellAmount({ uid, baseUrl }: GetExecutedSellAmountQuery & ApiCall): Promise<BigIntish> {
-  const response: OrderDetailResponse = await call(`orders/${uid}`, baseUrl)
+async function getExecutedSellAmount({
+  uid,
+  baseUrl,
+  apiKey,
+}: GetExecutedSellAmountQuery & ApiCall): Promise<BigIntish> {
+  const response: OrderDetailResponse = await call(`orders/${uid}`, baseUrl, undefined, apiKey)
   return getGlobalAdapter().utils.toBigIntish(response.executedSellAmount)
 }
 
-async function getQuote({ baseUrl }: ApiCall, quote: QuoteQuery): Promise<GetQuoteResponse> {
+async function getQuote(
+  { baseUrl, apiKey }: ApiCall,
+  quote: QuoteQuery,
+): Promise<GetQuoteResponse> {
   // Convert BigNumber into JSON strings (native serialisation is a hex object)
   if ((<SellAmountBeforeFee>quote).sellAmountBeforeFee) {
     ;(<SellAmountBeforeFee>quote).sellAmountBeforeFee = String((<SellAmountBeforeFee>quote).sellAmountBeforeFee)
@@ -222,30 +258,35 @@ async function getQuote({ baseUrl }: ApiCall, quote: QuoteQuery): Promise<GetQuo
   if ((<BuyAmountAfterFee>quote).buyAmountAfterFee) {
     ;(<BuyAmountAfterFee>quote).buyAmountAfterFee = String((<BuyAmountAfterFee>quote).buyAmountAfterFee)
   }
-  return call('quote', baseUrl, {
-    method: 'post',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(quote),
-  })
+  return call(
+    'quote',
+    baseUrl,
+    {
+      method: 'post',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(quote),
+    },
+    apiKey,
+  )
 }
 
 export class Api {
   network: string
   baseUrl: string
+  apiKey?: string
 
-  constructor(network: string, baseUrlOrEnv: string | Environment) {
+  constructor(network: string, baseUrlOrEnv: string | Environment, apiKey?: string) {
     this.network = network
-    let baseUrl
+    this.apiKey = apiKey
     if (typeof baseUrlOrEnv === 'string') {
-      baseUrl = baseUrlOrEnv
+      this.baseUrl = baseUrlOrEnv
     } else {
-      baseUrl = apiUrl(baseUrlOrEnv, network)
+      this.baseUrl = apiUrl(baseUrlOrEnv, network, apiKey)
     }
-    this.baseUrl = baseUrl
   }
 
   private apiCallParams() {
-    return { network: this.network, baseUrl: this.baseUrl }
+    return { network: this.network, baseUrl: this.baseUrl, apiKey: this.apiKey }
   }
 
   async estimateTradeAmount(query: EstimateTradeAmountQuery): Promise<BigIntish> {
diff --git a/packages/order-book/README.md b/packages/order-book/README.md
@@ -121,6 +121,39 @@ const orderBookApi = new OrderBookApi({
 })
 ```
 
+### Partner API (Authenticated Access)
+
+Partners can use the Partner API for authenticated, rate-limited access with higher request quotas. Provide your API key and the SDK will automatically route requests through the partner gateway and attach the `X-API-Key` header.
+
+| Environment | Partner API Base URL |
+|-------------|---------------------|
+| Production  | `https://partners.cow.fi` |
+| Staging     | `https://partners.barn.cow.fi` |
+
+```typescript
+const orderBookApi = new OrderBookApi({
+  chainId: SupportedChainId.MAINNET,
+  apiKey: 'your-partner-api-key',
+})
+```
+
+To use the Partner API with the Trading SDK, pass a configured `OrderBookApi` instance:
+
+```typescript
+import { TradingSdk } from '@cowprotocol/sdk-trading'
+
+const orderBookApi = new OrderBookApi({
+  chainId: SupportedChainId.MAINNET,
+  apiKey: 'your-partner-api-key',
+})
+
+const sdk = new TradingSdk(
+  { chainId: SupportedChainId.MAINNET, appCode: 'YOUR_APP_CODE' },
+  { orderBookApi },
+  adapter,
+)
+```
+
 ### Rate Limiting Configuration
 
 ```typescript
diff --git a/packages/order-book/src/api.ts b/packages/order-book/src/api.ts
@@ -3,7 +3,6 @@ import { RateLimiter } from 'limiter'
 import {
   ApiBaseUrls,
   ApiContext,
-  CowEnv,
   DEFAULT_COW_API_CONTEXT,
   ENVS_LIST,
   PartialApiContext,
@@ -33,6 +32,8 @@ import { EnrichedOrder } from './types'
 
 const PROD_BASE_URL = 'https://api.cow.fi'
 const STAGING_BASE_URL = 'https://barn.api.cow.fi'
+const PARTNER_PROD_BASE_URL = 'https://partners.cow.fi'
+const PARTNER_STAGING_BASE_URL = 'https://partners.barn.cow.fi'
 
 /**
  * An object containing *production* environment base URLs for each supported `chainId`.
@@ -71,6 +72,46 @@ export const ORDER_BOOK_STAGING_CONFIG: ApiBaseUrls = {
   [SupportedChainId.INK]: `${STAGING_BASE_URL}/ink`,
 }
 
+/**
+ * An object containing *partner production* environment base URLs for each supported `chainId`.
+ * Used when apiKey is set; requests include X-API-Key header.
+ * @see {@link https://partners.cow.fi}
+ */
+export const ORDER_BOOK_PARTNER_PROD_CONFIG: ApiBaseUrls = {
+  [SupportedChainId.MAINNET]: `${PARTNER_PROD_BASE_URL}/mainnet`,
+  [SupportedChainId.GNOSIS_CHAIN]: `${PARTNER_PROD_BASE_URL}/xdai`,
+  [SupportedChainId.ARBITRUM_ONE]: `${PARTNER_PROD_BASE_URL}/arbitrum_one`,
+  [SupportedChainId.BASE]: `${PARTNER_PROD_BASE_URL}/base`,
+  [SupportedChainId.SEPOLIA]: `${PARTNER_PROD_BASE_URL}/sepolia`,
+  [SupportedChainId.POLYGON]: `${PARTNER_PROD_BASE_URL}/polygon`,
+  [SupportedChainId.AVALANCHE]: `${PARTNER_PROD_BASE_URL}/avalanche`,
+  [SupportedChainId.LENS]: `${PARTNER_PROD_BASE_URL}/lens`,
+  [SupportedChainId.BNB]: `${PARTNER_PROD_BASE_URL}/bnb`,
+  [SupportedChainId.LINEA]: `${PARTNER_PROD_BASE_URL}/linea`,
+  [SupportedChainId.PLASMA]: `${PARTNER_PROD_BASE_URL}/plasma`,
+  [SupportedChainId.INK]: `${PARTNER_PROD_BASE_URL}/ink`,
+}
+
+/**
+ * An object containing *partner staging* environment base URLs for each supported `chainId`.
+ * Used when apiKey is set and env is staging; requests include X-API-Key header.
+ * @see {@link https://partners.barn.cow.fi}
+ */
+export const ORDER_BOOK_PARTNER_STAGING_CONFIG: ApiBaseUrls = {
+  [SupportedChainId.MAINNET]: `${PARTNER_STAGING_BASE_URL}/mainnet`,
+  [SupportedChainId.GNOSIS_CHAIN]: `${PARTNER_STAGING_BASE_URL}/xdai`,
+  [SupportedChainId.ARBITRUM_ONE]: `${PARTNER_STAGING_BASE_URL}/arbitrum_one`,
+  [SupportedChainId.BASE]: `${PARTNER_STAGING_BASE_URL}/base`,
+  [SupportedChainId.SEPOLIA]: `${PARTNER_STAGING_BASE_URL}/sepolia`,
+  [SupportedChainId.POLYGON]: `${PARTNER_STAGING_BASE_URL}/polygon`,
+  [SupportedChainId.AVALANCHE]: `${PARTNER_STAGING_BASE_URL}/avalanche`,
+  [SupportedChainId.LENS]: `${PARTNER_STAGING_BASE_URL}/lens`,
+  [SupportedChainId.BNB]: `${PARTNER_STAGING_BASE_URL}/bnb`,
+  [SupportedChainId.LINEA]: `${PARTNER_STAGING_BASE_URL}/linea`,
+  [SupportedChainId.PLASMA]: `${PARTNER_STAGING_BASE_URL}/plasma`,
+  [SupportedChainId.INK]: `${PARTNER_STAGING_BASE_URL}/ink`,
+}
+
 function cleanObjectFromUndefinedValues(obj: Record<string, string>): typeof obj {
   return Object.keys(obj).reduce(
     (acc, key) => {
@@ -419,8 +460,8 @@ export class OrderBookApi {
    * @returns The API endpoint to get the order.
    */
   getOrderLink(orderUid: UID, contextOverride?: PartialApiContext): string {
-    const { chainId, env } = this.getContextWithOverride(contextOverride)
-    return this.getApiBaseUrls(env)[chainId] + `/api/v1/orders/${orderUid}`
+    const context = this.getContextWithOverride(contextOverride ?? {})
+    return this.getApiBaseUrls(context)[context.chainId] + `/api/v1/orders/${orderUid}`
   }
 
   /**
@@ -433,14 +474,17 @@ export class OrderBookApi {
   }
 
   /**
-   * Get the base URLs for the API endpoints given the environment.
-   * @param env The environment to get the base URLs for.
+   * Get the base URLs for the API endpoints given the context.
+   * Uses partner URLs when apiKey is set (and no custom baseUrls override).
+   * @param context The merged API context for the request.
    * @returns The base URLs for the API endpoints.
    */
-  private getApiBaseUrls(env: CowEnv): ApiBaseUrls {
-    if (this.context.baseUrls) return this.context.baseUrls
-
-    return env === 'prod' ? ORDER_BOOK_PROD_CONFIG : ORDER_BOOK_STAGING_CONFIG
+  private getApiBaseUrls(context: ApiContext): ApiBaseUrls {
+    if (context.baseUrls) return context.baseUrls
+    if (context.apiKey) {
+      return context.env === 'prod' ? ORDER_BOOK_PARTNER_PROD_CONFIG : ORDER_BOOK_PARTNER_STAGING_CONFIG
+    }
+    return context.env === 'prod' ? ORDER_BOOK_PROD_CONFIG : ORDER_BOOK_STAGING_CONFIG
   }
 
   /**
@@ -450,13 +494,15 @@ export class OrderBookApi {
    * @returns The response from the API.
    */
   private fetch<T>(params: FetchParams, contextOverride: PartialApiContext = {}): Promise<T> {
-    const { chainId, env, backoffOpts: _backoffOpts } = this.getContextWithOverride(contextOverride)
-    const baseUrl = this.getApiBaseUrls(env)[chainId]
+    const context = this.getContextWithOverride(contextOverride)
+    const { chainId, backoffOpts: _backoffOpts, apiKey } = context
+    const baseUrl = this.getApiBaseUrls(context)[chainId]
     const backoffOpts = _backoffOpts || DEFAULT_BACKOFF_OPTIONS
     const rateLimiter = contextOverride.limiterOpts ? new RateLimiter(contextOverride.limiterOpts) : this.rateLimiter
+    const additionalHeaders = apiKey ? { 'X-API-Key': apiKey } : undefined
 
     log(`Fetching OrderBook API: ${baseUrl}${params.path}. Params: ${JSON.stringify(params, jsonWithBigintReplacer)}`)
 
-    return request(baseUrl, params, rateLimiter, backoffOpts)
+    return request(baseUrl, params, rateLimiter, backoffOpts, additionalHeaders)
   }
 }
diff --git a/packages/order-book/src/request.ts b/packages/order-book/src/request.ts
@@ -101,6 +101,7 @@ const getResponseBody = async (response: Response): Promise<unknown> => {
  * @param body The body of the request.
  * @param rateLimiter The rate limiter to use.
  * @param backoffOpts The backoff options to use.
+ * @param additionalHeaders Optional additional headers (e.g. X-API-Key for Partner API).
  * @returns The response of the request.
  * @throws If the API returns an error or if the request fails.
  */
@@ -109,11 +110,13 @@ export async function request<T>(
   { path, query, method, body }: FetchParams,
   rateLimiter: RateLimiter,
   backoffOpts: BackoffOptions,
+  additionalHeaders?: Record<string, string>,
 ): Promise<T> {
   const queryString = query ? '?' + query : ''
   const headers = {
     Accept: 'application/json',
     'Content-Type': 'application/json',
+    ...additionalHeaders,
   }
   const url = `${baseUrl}${path}${queryString}`
   const bodyContent = (() => {
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
@@ -278,6 +278,23 @@ await sdk.getQuote(parameters, {
 > **Tip:** Use `utmContent` for graffiti without affecting your `appCode`. The `appCode` parameter tracks your integration on [CoW Protocol's Dune dashboards](https://dune.com/cowprotocol/cowswap), while `utmContent` is available for custom identifiers or experimentation - all while attributing your volume to SDK integrators' collective impact.
 
 
+## Partner API
+
+Partners can use authenticated API access with higher rate limits via the Partner API gateway. Pass your API key when creating an `OrderBookApi` instance:
+
+```typescript
+import { OrderBookApi, SupportedChainId } from '@cowprotocol/cow-sdk'
+
+const orderBookApi = new OrderBookApi({
+  chainId: SupportedChainId.MAINNET,
+  apiKey: 'your-partner-api-key',
+})
+```
+
+By default, the SDK routes requests through `partners.cow.fi` (prod) or `partners.barn.cow.fi` (staging) and includes the `X-API-Key` header. If you provide custom `baseUrls`, those take precedence over the default partner hosts, but the `X-API-Key` header is still sent with every request.
+
+See the [OrderBookApi documentation](https://github.com/cowprotocol/cow-sdk/tree/main/packages/order-book/README.md#partner-api-authenticated-access) for more details, including usage with the Trading SDK.
+
 ## Adapters
 
 The CoW SDK supports multiple blockchain adapters to work with different Web3 libraries. You need to install and configure one of the following adapters:
