Skip to main content

​
Authentication

The CoW Protocol BFF API is designed to be accessible without traditional API key authentication for most read operations. However, certain operations require cryptographic signatures to verify ownership.

​
Public Endpoints

Most API endpoints are publicly accessible without authentication:
  • Token information and pricing
  • Market data and slippage calculations
  • Pool and yield information
  • Transaction simulation
  • Account balance queries
  • Affiliate statistics (read-only)
These endpoints can be accessed directly with HTTP requests: 
curl https://api.cow.fi/1/tokens/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/usdPrice

​
Signature-Based Authentication

​
Affiliate Program Registration

Creating an affiliate code requires EIP-712 signature verification to prove wallet ownership. This ensures that only the wallet owner can bind an affiliate code to their address.

​
EIP-712 Typed Data Structure

When registering an affiliate code, you must sign the following typed data: Domain: 
{
  "name": "CoW Swap Affiliate",
  "version": "1"
}
Types: 
{
  "AffiliateCode": [
    { "name": "walletAddress", "type": "address" },
    { "name": "code", "type": "string" },
    { "name": "chainId", "type": "uint256" }
  ]
}
Message: 
{
  "walletAddress": "0x...",
  "code": "YOUR-CODE",
  "chainId": 1
}

​
Signature Generation Example

Using ethers.js v6: 
import { ethers } from 'ethers';

const domain = {
  name: 'CoW Swap Affiliate',
  version: '1'
};

const types = {
  AffiliateCode: [
    { name: 'walletAddress', type: 'address' },
    { name: 'code', type: 'string' },
    { name: 'chainId', type: 'uint256' }
  ]
};

const message = {
  walletAddress: '0x1234...', // Your wallet address
  code: 'MYCODE',
  chainId: 1
};

const signer = await provider.getSigner();
const signature = await signer.signTypedData(domain, types, message);

​
Signature Verification

The API verifies signatures using the following process:
  1. EOA (Externally Owned Account): Standard ECDSA signature verification
  2. Smart Contract Wallets: ERC-1271 signature verification
The signature is verified on Ethereum Mainnet (chainId: 1) for all affiliate registrations, regardless of the chain where trades occur.

​
Making Authenticated Requests

To register an affiliate code, include the signature in the request body: 
curl -X POST https://api.cow.fi/affiliate/0x1234.../  \
  -H "Content-Type: application/json" \
  -d '{
    "walletAddress": "0x1234...",
    "code": "MYCODE",
    "signedMessage": "0xabcd..."
  }'

​
CORS Policy

The API supports Cross-Origin Resource Sharing (CORS) for browser-based applications: 
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Cache-Control

​
Error Responses

​
401 Unauthorized

Returned when signature verification fails: 
{
  "message": "Affiliate has invalid signature"
}

​
400 Bad Request

Returned when wallet address mismatch occurs: 
{
  "message": "Affiliate wallet address mismatch"
}

​
409 Conflict

Returned when attempting to register an affiliate code that already exists: 
{
  "message": "Affiliate code already taken"
}

​
Security Considerations

​
Signature Replay Protection

The API stores signed messages to prevent replay attacks. Each signature can only be used once to register an affiliate code.

​
Chain ID Validation

All affiliate signatures are verified on Ethereum Mainnet (chainId: 1). This prevents cross-chain replay attacks and ensures consistency.

​
Address Normalization

All Ethereum addresses are normalized to lowercase to prevent case-sensitivity issues during verification.

​
Rate Limiting

While the API doesn’t require API keys, reasonable rate limits are enforced to prevent abuse:
  • Read operations: Higher limits with caching
  • Write operations: Lower limits to prevent spam
  • SSE connections: Limited concurrent connections per IP

​
Best Practices

  1. Cache responses: Respect Cache-Control headers to reduce load
  2. Use appropriate chains: Query data from the correct network
  3. Handle errors gracefully: Implement retry logic with exponential backoff
  4. Validate inputs: Ensure addresses and parameters are properly formatted
  5. Secure signatures: Never share private keys or expose signing mechanisms

​
Environment Variables

Some features require configuration via environment variables:
  • CMS_ENABLED: Enable/disable affiliate program features
  • DUNE_API_KEY: Enable/disable statistics endpoints
  • DATABASE_URL: Required for balance tracking and notifications
Public API endpoints will return appropriate error messages if required services are unavailable.
Last modified on March 4, 2026