Polymarket Builder Program: Builder Codes, Attribution, and a Reproducible Integration Workflow

What the Builder Program Actually Attributes

The Polymarket Builder Program is an attribution and revenue-share layer on top of Polymarket's central limit order book (CLOB). A builder is any application, bot, or order router that sends orders to Polymarket on behalf of users. When those orders match, the builder code attached to the order lets Polymarket credit the volume to a builder profile. Without that code, the same trade still executes, but no builder attribution is recorded.

The practical consequence is that attribution is a property of the order payload and the signing path, not of your frontend branding. A user can trade through your UI and still generate zero builder volume if the order is signed or submitted without the builder fields. Conversely, a headless router with no UI can accrue attributed volume as long as it attaches the code correctly.

This article focuses on the integration mechanics and verification methodology. For the concrete choice of a Polygon RPC endpoint to read chain state and submit transactions, use the RPC Assistant endpoint guidance rather than hard-coding a public endpoint.

• Builder code: identifies the application or router receiving attribution.
• Builder credentials: API key, secret, and passphrase issued for your builder profile.
• Proxy wallet: a contract wallet (commonly a Gnosis Safe) that holds collateral and token approvals.
• CLOB client: signs and submits orders, including builder attribution fields.
• Builder Relayer: submits gasless proxy-wallet operations on your behalf.

Prerequisites and Assumptions Before You Start

You need a Polymarket builder profile with API credentials, a Polygon mainnet RPC endpoint you control, and a signing strategy for the proxy wallet. The examples below assume a server-side integration where builder credentials never reach the browser. If you are building a consumer app, pair this with an embedded-wallet provider so users get a wallet without managing seed phrases.

You should also decide early whether you will operate your own proxy wallet deployment flow or rely on an existing Safe. The relayer path is convenient but introduces a dependency on relayer availability and on correct nonce handling. Treat the relayer as infrastructure with its own failure modes, not as a magic gasless button.

For node-level reliability expectations when your router submits many transactions, review the dedicated node options and the RPC pricing model so you can size throughput before launch.

• Builder API key, secret, and passphrase stored server-side only.
• A Polygon mainnet RPC URL with sufficient rate limits for your order volume.
• A funded proxy wallet and completed token approvals for the relevant exchange contracts.
• A logging pipeline that records order IDs, builder code, and match status.

Mental Model: How Builder Attribution Flows Through an Order

An attributed order passes through four stages. First, your application constructs an order with market, side, price, size, and builder metadata. Second, the CLOB client signs the order using the proxy wallet's signing authority. Third, the order is submitted to Polymarket's matching engine. Fourth, if the order matches, the fill is recorded against your builder profile.

The critical insight is that attribution is evaluated at match time, not at submission time. An order that rests unfilled and is later cancelled produces no attributed volume. This is why builders who route marketable orders see attribution faster than builders who post passive liquidity, and why your verification procedure must check fills rather than submissions.

A second insight is that builder fees and platform fees are separate. Your builder fee is additive to Polymarket's own fee schedule, so you must model the total cost your users pay. Do not assume your builder fee replaces the platform fee.

Runnable Diagnostic: Confirm Your Credentials and RPC Path

Before writing order logic, confirm that your builder credentials authenticate and that your RPC endpoint can read the proxy wallet's state. The following Python snippet uses environment variables and placeholder values; replace them with your own. It does not place an order, so it is safe to run against production credentials.

The script checks three things: that the RPC endpoint responds with the current block number, that the proxy wallet has a non-zero native balance for gas if you are not using the relayer, and that your builder credentials are present in the environment. A failure at any step tells you which layer to fix before touching order construction.

import os, json, urllib.request

RPC_URL = os.environ["RPC_URL"]
PROXY_WALLET = os.environ["PROXY_WALLET"]

required = ["POLYMARKET_BUILDER_API_KEY", "POLYMARKET_BUILDER_SECRET", "POLYMARKET_BUILDER_PASSPHRASE"]
missing = [k for k in required if not os.environ.get(k)]
print("missing builder credentials:", missing)

def rpc(method, params):
    body = json.dumps({"jsonrpc": "2.0", "id": 1, "method": method, "params": params}).encode()
    req = urllib.request.Request(RPC_URL, data=body, headers={"Content-Type": "application/json"})
    with urllib.request.urlopen(req, timeout=10) as resp:
        return json.loads(resp.read())

block = rpc("eth_blockNumber", [])
balance = rpc("eth_getBalance", [PROXY_WALLET, "latest"])
print("block:", int(block["result"], 16))
print("proxy native balance wei:", int(balance["result"], 16))

Integration Skeleton: Attaching a Builder Code to an Order

The exact client API changes over time, so treat the following as a structural template rather than a copy-paste production script. The important parts are the separation of concerns: credentials are loaded server-side, the client is initialized with the proxy wallet and builder credentials, and the order payload carries the builder attribution fields.

In practice you will use Polymarket's published client libraries. The template below shows the shape of the initialization and the order submission call so you can map it onto the current library version. Keep the signing endpoint behind your own server so the builder secret is never exposed to the client.

import { ClobClient } from "@polymarket/clob-client";

const client = new ClobClient({
  host: process.env.CLOB_HOST,
  chainId: 137,
  signer: proxyWalletSigner,
  creds: {
    key: process.env.POLYMARKET_BUILDER_API_KEY,
    secret: process.env.POLYMARKET_BUILDER_SECRET,
    passphrase: process.env.POLYMARKET_BUILDER_PASSPHRASE,
  },
  builderCode: process.env.POLYMARKET_BUILDER_CODE,
});

const order = await client.createOrder({
  tokenID: process.env.TOKEN_ID,
  price: 0.42,
  size: 10,
  side: "BUY",
});

const response = await client.postOrder(order);
console.log(JSON.stringify({ orderId: response.orderID, builderCode: process.env.POLYMARKET_BUILDER_CODE }));

Verification Procedure and Results Table

Attribution is only real when a matched fill appears against your builder profile. Build a verification loop that submits a small, deliberately marketable order, waits for the match, and then reconciles three records: your own order log, the CLOB response, and the builder dashboard or API view of attributed volume. Run this loop after every client upgrade and after any change to your signing path.

Record the following fields for each test order so you can compare runs over time. Do not invent expected values; fill the table with your own observed results and keep the raw responses alongside it.

A passing run shows a matched fill and a corresponding positive delta in attributed volume within the program's reporting window. A failing run shows a matched fill with no attribution delta, which almost always means the builder fields were dropped somewhere between order construction and signing.

Troubleshooting Common Attribution and Relay Failures

Most integration failures fall into a small number of categories. Work through them in order, because a failure at an earlier layer will masquerade as a later one.

If orders are rejected before matching, check token approvals first. The proxy wallet must approve the collateral and the relevant exchange contracts; a missing approval produces a revert that looks like an order error. If orders submit but never attribute, inspect the signed payload and confirm the builder code survived serialization. If the relayer rejects a proxy-wallet operation, check nonce ordering and whether a previous operation is still pending.

• Missing or stale token approvals for the exchange contracts.
• Builder credentials loaded in the browser instead of the server, causing silent fallback to unattributed orders.
• Relayer nonce collisions when multiple operations are submitted concurrently.
• RPC rate limiting during high-volume order submission, producing timeouts that look like matching failures.
• Using a testnet RPC endpoint against mainnet contracts, or vice versa.

Limitations, Tradeoffs, and What the Program Does Not Guarantee

The Builder Program attributes matched volume; it does not guarantee revenue. Your earnings depend on the fee rates you configure, the share of attributed volume in any reward pool, and the behavior of your users. Public leaderboards show that volume is highly concentrated among a small number of builders, so plan for a long ramp rather than immediate payouts.

There is also an operational tradeoff between the relayer path and self-submitted transactions. The relayer simplifies gas management but adds a dependency and a nonce-ordering constraint. Self-submission gives you more control but requires you to fund and monitor the proxy wallet. Neither path removes the need for reliable RPC access; both fail in the same way when the node layer is unstable.

Finally, program terms, fee caps, and reward mechanics can change. Treat any specific rate you read as a snapshot and re-check the official program documentation before you publish pricing to your users.

Next Steps: From Working Integration to Reliable Operation

Once a single attributed order verifies end to end, harden the path. Add structured logging around order construction, signing, submission, and fill reconciliation. Add alerting on attribution deltas that fall to zero while order volume remains positive, because that pattern usually indicates a silent credential or payload regression.

Then size your infrastructure. Review the network guides for the chains your integration touches and the RPC endpoint guide for how to evaluate providers on latency and consistency. If you expect sustained order flow, compare dedicated node options against shared endpoints before your first high-volume day.

For teams building adjacent tooling, the Hyperliquid RPC provider comparison and the multi-chain endpoint guide illustrate the same reliability principles applied to other trading venues.