Polymarket Builder Program: códigos de builder, atribución y un flujo de integración reproducible

Qué atribuye realmente el Builder Program

El Polymarket Builder Program es una capa de atribución y reparto de ingresos sobre el libro de órdenes central de Polymarket (CLOB). Un builder es cualquier aplicación, bot o enrutador de órdenes que envía órdenes a Polymarket en nombre de los usuarios. Cuando esas órdenes se emparejan, el código de builder adjunto a la orden permite a Polymarket acreditar el volumen a un perfil de builder. Sin ese código, la misma operación se ejecuta igual, pero no se registra ninguna atribución de builder.

La consecuencia práctica es que la atribución es una propiedad de la carga útil de la orden y de la ruta de firma, no de la marca de tu interfaz. Un usuario puede operar a través de tu UI y aun así generar cero volumen de builder si la orden se firma o se envía sin los campos de builder. A la inversa, un enrutador sin interfaz puede acumular volumen atribuido siempre que adjunte el código correctamente.

Este artículo se centra en la mecánica de integración y la metodología de verificación. Para la elección concreta de un endpoint RPC de Polygon para leer el estado de la cadena y enviar transacciones, utiliza la guía de endpoints del RPC Assistant en lugar de codificar un endpoint público.

• Código de builder: identifica la aplicación o el enrutador que recibe la atribución.
• Credenciales de builder: clave API, secreto y passphrase emitidos para tu perfil de builder.
• Cartera proxy: una cartera de contrato (comúnmente una Gnosis Safe) que custodia el colateral y las aprobaciones de tokens.
• Cliente CLOB: firma y envía órdenes, incluidos los campos de atribución de builder.
• Builder Relayer: envía operaciones sin gas de la cartera proxy en tu nombre.

Requisitos previos y supuestos antes de empezar

Necesitas un perfil de builder de Polymarket con credenciales API, un endpoint RPC de Polygon mainnet que controles y una estrategia de firma para la cartera proxy. Los ejemplos siguientes asumen una integración del lado del servidor en la que las credenciales de builder nunca llegan al navegador. Si estás creando una aplicación para consumidores, combínalo con un proveedor de cartera integrada para que los usuarios obtengan una cartera sin gestionar frases semilla.

También deberías decidir desde el principio si vas a operar tu propio flujo de despliegue de cartera proxy o si vas a confiar en una Safe existente. La ruta del relayer es cómoda pero introduce una dependencia de la disponibilidad del relayer y del manejo correcto del nonce. Trata el relayer como infraestructura con sus propios modos de fallo, no como un botón mágico sin gas.

Para conocer las expectativas de fiabilidad a nivel de nodo cuando tu enrutador envía muchas transacciones, revisa las opciones de nodo dedicado y el modelo de precios de RPC para dimensionar el rendimiento antes del lanzamiento.

• Clave API, secreto y passphrase del builder almacenados solo en el servidor.
• Una URL RPC de Polygon mainnet con límites de tasa suficientes para tu volumen de órdenes.
• Una cartera proxy financiada y las aprobaciones de tokens completadas para los contratos de exchange correspondientes.
• Un pipeline de registro que registre los ID de orden, el código de builder y el estado de emparejamiento.

Modelo mental: cómo fluye la atribución de builder a través de una orden

Una orden atribuida pasa por cuatro etapas. Primero, tu aplicación construye una orden con mercado, lado, precio, tamaño y metadatos de builder. Segundo, el cliente CLOB firma la orden utilizando la autoridad de firma de la cartera proxy. Tercero, la orden se envía al motor de emparejamiento de Polymarket. Cuarto, si la orden se empareja, la ejecución se registra contra tu perfil de builder.

La idea clave es que la atribución se evalúa en el momento del emparejamiento, no en el momento del envío. Una orden que queda sin ejecutar y luego se cancela no produce volumen atribuido. Por eso los builders que enrutan órdenes ejecutables ven la atribución más rápido que los builders que publican liquidez pasiva, y por eso tu procedimiento de verificación debe comprobar las ejecuciones en lugar de los envíos.

Una segunda idea es que las comisiones del builder y las de la plataforma son independientes. Tu comisión de builder se suma a la tarifa propia de Polymarket, por lo que debes modelar el coste total que pagan tus usuarios. No asumas que tu comisión de builder sustituye a la comisión de la plataforma.

Diagnóstico ejecutable: confirma tus credenciales y la ruta RPC

Antes de escribir la lógica de órdenes, confirma que tus credenciales de builder se autentican y que tu endpoint RPC puede leer el estado de la cartera proxy. El siguiente fragmento de Python utiliza variables de entorno y valores de marcador de posición; sustitúyelos por los tuyos. No coloca ninguna orden, por lo que es seguro ejecutarlo con credenciales de producción.

El script comprueba tres cosas: que el endpoint RPC responde con el número de bloque actual, que la cartera proxy tiene un saldo nativo distinto de cero para gas si no utilizas el relayer, y que tus credenciales de builder están presentes en el entorno. Un fallo en cualquier paso te indica qué capa corregir antes de tocar la construcción de órdenes.

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))

Esqueleto de integración: adjuntar un código de builder a una orden

La API exacta del cliente cambia con el tiempo, así que trata lo siguiente como una plantilla estructural en lugar de un script de producción para copiar y pegar. Las partes importantes son la separación de responsabilidades: las credenciales se cargan en el servidor, el cliente se inicializa con la cartera proxy y las credenciales de builder, y la carga útil de la orden lleva los campos de atribución de builder.

En la práctica utilizarás las bibliotecas de cliente publicadas por Polymarket. La plantilla siguiente muestra la forma de la inicialización y la llamada de envío de órdenes para que puedas mapearla a la versión actual de la biblioteca. Mantén el endpoint de firma detrás de tu propio servidor para que el secreto del builder nunca se exponga al cliente.

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 }));

Procedimiento de verificación y tabla de resultados

La atribución solo es real cuando aparece una ejecución emparejada contra tu perfil de builder. Crea un bucle de verificación que envíe una orden pequeña y deliberadamente ejecutable, espere el emparejamiento y luego concilie tres registros: tu propio registro de órdenes, la respuesta del CLOB y la vista del panel de builder o de la API del volumen atribuido. Ejecuta este bucle después de cada actualización del cliente y después de cualquier cambio en tu ruta de firma.

Registra los siguientes campos para cada orden de prueba para que puedas comparar ejecuciones a lo largo del tiempo. No inventes valores esperados; completa la tabla con tus propios resultados observados y guarda las respuestas sin procesar junto a ella.

Una ejecución correcta muestra una ejecución emparejada y un delta positivo correspondiente en el volumen atribuido dentro de la ventana de reporte del programa. Una ejecución fallida muestra una ejecución emparejada sin delta de atribución, lo que casi siempre significa que los campos de builder se perdieron en algún punto entre la construcción de la orden y la firma.

Solución de problemas comunes de atribución y relay

La mayoría de los fallos de integración se engloban en un pequeño número de categorías. Recórrelas en orden, porque un fallo en una capa anterior se manifestará como si fuera una posterior.

Si las órdenes se rechazan antes del emparejamiento, comprueba primero las aprobaciones de tokens. La cartera proxy debe aprobar el colateral y los contratos de exchange correspondientes; una aprobación faltante produce un revert que parece un error de orden. Si las órdenes se envían pero nunca se atribuyen, inspecciona la carga útil firmada y confirma que el código de builder sobrevivió a la serialización. Si el relayer rechaza una operación de la cartera proxy, comprueba el orden de los nonces y si una operación anterior sigue pendiente.

• Aprobaciones de tokens faltantes o desactualizadas para los contratos de exchange.
• Credenciales de builder cargadas en el navegador en lugar del servidor, lo que provoca un fallback silencioso a órdenes sin atribución.
• Colisiones de nonce del relayer cuando se envían varias operaciones de forma concurrente.
• Limitación de tasa del RPC durante el envío de órdenes de alto volumen, lo que produce tiempos de espera que parecen fallos de emparejamiento.
• Usar un endpoint RPC de testnet contra contratos de mainnet, o viceversa.

Limitaciones, compensaciones y lo que el programa no garantiza

El Builder Program atribuye volumen emparejado; no garantiza ingresos. Tus ganancias dependen de las tasas de comisión que configures, de la cuota de volumen atribuido en cualquier pool de recompensas y del comportamiento de tus usuarios. Las clasificaciones públicas muestran que el volumen está muy concentrado entre un pequeño número de builders, así que planifica una rampa larga en lugar de pagos inmediatos.

También existe una compensación operativa entre la ruta del relayer y las transacciones enviadas por ti mismo. El relayer simplifica la gestión del gas pero añade una dependencia y una restricción de ordenación de nonces. El envío propio te da más control pero requiere que financies y monitorices la cartera proxy. Ninguna de las dos rutas elimina la necesidad de un acceso RPC fiable; ambas fallan de la misma manera cuando la capa de nodo es inestable.

Por último, los términos del programa, los límites de comisiones y la mecánica de recompensas pueden cambiar. Trata cualquier tasa específica que leas como una instantánea y vuelve a comprobar la documentación oficial del programa antes de publicar precios a tus usuarios.

Próximos pasos: de una integración funcional a una operación fiable

Una vez que una sola orden atribuida se verifica de extremo a extremo, refuerza la ruta. Añade registro estructurado en torno a la construcción de órdenes, la firma, el envío y la conciliación de ejecuciones. Añade alertas cuando los deltas de atribución caigan a cero mientras el volumen de órdenes siga siendo positivo, porque ese patrón suele indicar una regresión silenciosa de credenciales o de carga útil.

Luego dimensiona tu infraestructura. Revisa las guías de redes para las cadenas que toca tu integración y la guía de endpoints RPC para saber cómo evaluar proveedores en latencia y consistencia. Si esperas un flujo de órdenes sostenido, compara las opciones de nodo dedicado con los endpoints compartidos antes de tu primer día de alto volumen.

Para los equipos que construyen herramientas adyacentes, la comparativa de proveedores RPC de Hyperliquid y la guía de endpoints multicadena ilustran los mismos principios de fiabilidad aplicados a otros venues de trading.