Skip to main content

​
Overview

The order attribution system allows builders to attach custom headers to their customer orders before posting them to the CLOB. These additional headers enable Polymarket to attribute orders to your specific builder account, providing visibility into which orders originate from your platform.

​
Builder API Credentials

Each builder will receive Builder API Key Credentials that look like this: 
interface BuilderApiKeyCreds {
    key: string;
    secret: string;
    passphrase: string;
}

// Example structure
const builderCreds = {
    key: "xxxxx.....",
    secret: "xxxxx.....",
    passphrase: "xxxxx....."
};
Security Notice: Your Builder API keys must be kept secure. We provide both local and remote signing methods to help you protect these credentials.

​
Signing Methods

There are two methods available for signing orders and adding attribution headers: Remote Signing and Local Signing. Remote signing is the recommended approach for protecting your Builder API credentials. With this method, your credentials never leave your secure server. How it works:
  1. Your customer signs an order payload (ready to be sent to the CLOB)
  2. Instead of sending directly to the CLOB, the signed payload is sent to your builder signing server
  3. Your builder signing server uses your Builder API keys to cryptographically sign the entire payload and adds the authentication headers
  4. The fully signed payload (signed by both your customer and you as the builder) is then sent to the CLOB
Implementation: We provide a complete server implementation in the @polymarket/builder-signing-server repository. 
import { ClobClient } from "@polymarket/clob-client";
import { BuilderConfig } from "@polymarket/builder-signing-sdk";

// Basic remote signing configuration
const builderConfig = new BuilderConfig({
    remoteBuilderConfig: {url: "http://localhost:3000/sign"}
});

// Or with optional authorization token for added security
const builderConfigWithAuth = new BuilderConfig({
    remoteBuilderConfig: {url: "http://localhost:3000/sign", token: "XXXX-XXXX-XXXX"}
});

const clobClient = new ClobClient(
    host,
    chainId,
    wallet,
    creds,
    SignatureType.POLY_PROXY,
    funderAddress,
    undefined,
    false,
    builderConfig // or builderConfigWithAuth
);

// Create and post order - headers are added automatically
const order = await clobClient.createOrder({
    price: 0.40,
    side: Side.BUY,
    size: 5,
    tokenID: "27072675915285915455116137912884489109876947142577610372904917850067886308458"
});

const response = await clobClient.postOrder(order);
Remote Builder Configuration: 
interface RemoteBuilderConfig {
    url: string;              // URL of your signing server
    token?: string;           // Optional authorization token
}
The optional token parameter allows you to add an authorization header to requests sent to your signing server, providing an additional layer of security.

​
Local Signing

If you control the entire order placement flow (including signing for your customers), you can sign orders locally before sending them to the CLOB. How it works:
  1. Your system creates and signs the order on behalf of your customer
  2. Your system uses your Builder API credentials locally to add authentication headers
  3. The complete signed order with builder headers is sent directly to the CLOB
Implementation: 
import { ClobClient } from "@polymarket/clob-client";
import { BuilderConfig, BuilderApiKeyCreds } from "@polymarket/builder-signing-sdk";

// Configure with local builder credentials
const builderCreds: BuilderApiKeyCreds = {
    key: process.env.POLY_BUILDER_API_KEY!,
    secret: process.env.POLY_BUILDER_SECRET!,
    passphrase: process.env.POLY_BUILDER_PASSPHRASE!
};

const builderConfig: BuilderConfig = {
    localBuilderCreds: builderCreds
};

const clobClient = new ClobClient(
    host,
    chainId,
    wallet,
    creds,
    SignatureType.POLY_PROXY,
    funderAddress,
    undefined,
    false,
    builderConfig
);

// Create and post order - headers are added automatically
const order = await clobClient.createOrder({
    price: 0.40,
    side: Side.BUY,
    size: 5,
    tokenID: "27072675915285915455116137912884489109876947142577610372904917850067886308458"
});

const response = await clobClient.postOrder(order);

​
Authentication Headers

The builder signing process adds the following headers to each order request:
  • POLY_BUILDER_API_KEY: Your builder API key
  • POLY_BUILDER_TIMESTAMP: Unix timestamp of when the signature was created
  • POLY_BUILDER_PASSPHRASE: Your builder passphrase
  • POLY_BUILDER_SIGNATURE: HMAC signature of the request
These headers are automatically generated and attached by the SDK - you don’t need to construct them manually.

​
Using Our SDKs

Important: We strongly recommend using our official SDKs and server implementations. You do not need to implement the signing logic yourself.
We provide the following packages to handle all signing and header injection: All examples in this documentation use these official packages to ensure security and reliability.

​
Next Steps