Polymarket Relayer Client Tutorial

Esta guía muestra cómo usar el Polymarket Relayer Client en TypeScript para construir flujos gasless: despliegue de wallets, manejo de aprobaciones ERC-20, operaciones CTF de split/merge/redeem y colocación de órdenes en el CLOB. Si quieres una integración gasless y funcional con Polymarket, el Polymarket Relayer Client es el SDK orientado a desarrolladores que usarás primero.

Puntos clave

• El Polymarket Relayer Client proporciona SDKs en TypeScript y Python para manejar despliegue de wallets, aprobaciones, operaciones CTF y colocación de órdenes a través del Relayer.
• Las transacciones en Polymarket son gasless para los usuarios finales: el Relayer sponsorea el gas y abstrae el despliegue de wallets y las aprobaciones.
• Los flujos comunes son: onboarding de wallet → comprobación/aprobación → split (mint) de un set completo → crear orden (limit o FAK) → merge/redeem tras resolución.
• Diseña siempre teniendo en cuenta los riesgos de resolución y liquidación: disputas en UMA, fills parciales/deslizamiento y tiempos son consideraciones reales.

A quién va dirigida esta guía

Eres un desarrollador que construye integraciones, bots o componentes de UX que colocan operaciones en el CLOB de Polymarket e interactúan con el CTF. Debes estar cómodo con TypeScript, wallets EVM (MetaMask, Rabby, etc.) y conceptos básicos de web3.

Resumen rápido de lo que cubre el SDK

• Onboarding de wallet: desplegar Proxy wallets en el primer uso o usar un Gnosis Safe si está disponible.
• Gestión de aprobaciones ERC-20 para pUSD y otros tokens usados en split/merge.
• Operaciones CTF: split, merge, redeem de tokens de resultado (ERC-1155).
• Colocación y cancelación de órdenes contra el CLOB a través del Relayer.
• Cabeceras de atribución de Builder cuando actúas como Builder (ver docs del Builder Program).

Nota: Polymarket usa Polygon (chain ID 137) y el activo de liquidación para trading es pUSD (wrapped USDC de Polymarket). Todas las transacciones de usuario son gasless vía el Relayer.

Instalación y primeros pasos

Instala el paquete TypeScript y un paquete estándar de proveedor web3. Los nombres exactos de los paquetes pueden variar por release; los ejemplos abajo usan la ruta de importación canónica común en SDKs del relayer. Si los nombres de paquete difieren en tu proyecto, consulta el README del SDK.

Shell

npm install @polymarket/relayer-client ethers

Inicialización básica (TypeScript)

import { RelayerClient } from '@polymarket/relayer-client';
import { ethers } from 'ethers';

// Use a wallet provider exposed in the browser (MetaMask, Rabby, etc.)
const provider = new ethers.providers.Web3Provider((window as any).ethereum);
const signer = provider.getSigner();

const relayer = new RelayerClient({
  signer,
  network: 'polygon', // Polymarket runs on Polygon (chainId 137)
});

Notas sobre el ejemplo anterior: el constructor de RelayerClient y el objeto de opciones son ilustrativos. Comprueba el README del SDK para la firma exacta del constructor y las opciones disponibles.

Onboarding: despliegue de wallet y aprobaciones

Polymarket soporta dos modelos de wallet: Gnosis Safes pre-desplegados y Proxy wallets que se auto-despliegan en la primera transacción. El SDK del Relayer maneja ambos flujos y sponsorea el gas de despliegue.

Pasos comunes de onboarding que deberías implementar en la UX:

1. Detectar si el usuario ya tiene un Proxy o un Safe. Si no, llamar al helper del SDK deploy-on-first-use.
2. Asegurarte de que el usuario tenga pUSD en su wallet. Si no, indícale cómo bridgear o depositar (ver la guía de financiación de Polymarket).
3. Comprobar el estado de aprobación ERC-20 para pUSD y solicitar una aprobación gasless vía el Relayer si es necesario.

Ejemplo: comprobar y solicitar aprobación (TypeScript)

// Pseudocode — adapt to SDK methods
const pUsdAddress = '0x...'; // use SDK constant if provided
const allowance = await relayer.checkAllowance(pUsdAddress);
if (allowance.lt(requiredAmount)) {
  await relayer.requestApproval(pUsdAddress, requiredAmount);
}

Debido a que el Relayer sponsorea el gas, la llamada de aprobación se envía a través del Relayer en lugar de que el usuario firme una transacción on-chain con gas.

Flujos CTF: split, merge, redeem

El Conditional Token Framework (CTF) es cómo Polymarket representa resultados (tokens ERC-1155). Secuencia típica cuando quieres comprar un set completo:

• split: quemar pUSD y mintear un set completo de tokens de resultado
• después de tradear, merge: convertir los tokens de resultado sobrantes de nuevo a una posición común
• redeem: tras la resolución, quemar los tokens ganadores por $1.00 cada uno

Ejemplo de split (TypeScript)

// Pseudocode using the Relayer SDK
const conditionId = '0x...';
const amount = ethers.utils.parseUnits('1.0', 6); // pUSD has 6 decimals
await relayer.split(conditionId, amount);

El SDK gestionará las aprobaciones necesarias y el envío al relayer. Tras el split, recibirás tokens ERC-1155 de resultado en el Proxy o Safe del usuario.

Colocación de órdenes en el CLOB

El CLOB expone colocación de órdenes y lecturas de orderbook. El Relayer Client enruta la colocación de órdenes a través del Relayer, manejando cabeceras de atribución de Builder si eres Builder.

Tipos de orden importantes:

• Órdenes limit: postean en el libro y potencialmente se quedan como maker (las comisiones maker son cero).
• Órdenes de mercado (FAK): el SDK expone helpers para crear órdenes FAK que ejecutan inmediatamente o se cancelan.

Ejemplo: colocar una orden de mercado FAK (TypeScript)

// Conceptual example
const instrumentId = 'POLY_MARKET_INSTRUMENT_ID';
const side = 'buy';
const size = ethers.utils.parseUnits('10', 6);

const result = await relayer.createMarketOrder({
  instrumentId,
  side,
  size,
  slippageTolerance: 0.01, // 1% slippage protection
});

console.log('fill result', result);

Si operas como Builder, incluye cabeceras de atribución o credenciales de Builder según lo requiera el Builder Program. El Builder Program ofrece límites de relayer por nivel y recompensas; obtén credenciales en https://polymarket.com/settings.

Lectura de datos de mercado y el WebSocket

Para lecturas que no impliquen trading, usa las superficies públicas REST y WebSocket de Polymarket:

• Gamma API: https://gamma-api.polymarket.com (markets, events)
• Data API: https://data-api.polymarket.com (positions, trades, open interest)
• CLOB API: https://clob.polymarket.com (orderbook and order placement APIs)
• Market WebSocket: wss://ws-subscriptions-clob.polymarket.com/ws/market para actualizaciones en tiempo real del libro

Cuando te suscribas a feeds WS de mercado, solicita custom_feature_enabled: true para recibir eventos best_bid_ask y limita la suscripción a 500 instrumentos por conexión.

Manejo de errores y trampas comunes

• Fills parciales: las órdenes de mercado (FAK) pueden llenarse parcialmente. Siempre inspecciona el resultado y maneja los remanentes.
• Deslizamiento: protege órdenes de mercado agresivas con límites de slippage. El SDK suele exponer ajustes de slippage en los helpers de mercado.
• Tiempos de resolución y liquidación: las disputas en UMA pueden pausar la liquidación. Diseña UIs y contabilidad para reflejar fondos no liquidados hasta que el redeem se complete.
• Cambios de tick size: el tick size pasa de $0.01 a $0.001 cerca de extremos de precio; maneja los eventos tick_size_change del WebSocket.

Estrategias de testing

• End-to-end en sandbox: ejercita el onboarding completo — despliega Proxy wallet, solicita aprobación, realiza split, coloca una orden y merge/redeem.
• Tests unitarios de wrappers: mockea métodos del relayer para afirmar secuencias correctas de aprobaciones y split.
• Consciencia de rate limits: Gamma /markets tiene límites (300 req / 10 s para /markets) — agrupa y cachea lecturas.

Cómo afecta esto a tu lógica de trading o bot

Usar el Polymarket Relayer Client elimina la necesidad de gestionar gas para los usuarios finales y simplifica el onboarding automatizando despliegues de Proxy y aprobaciones. Para bots, esto significa que puedes concentrarte en la estrategia y en los datos de mercado: el SDK reduce la superficie de integración para ejecutar flujos de split/merge y órdenes. Sin embargo, todavía debes manejar riesgos no relacionados con la ejecución como slippage, fills parciales y disputas del oráculo.

Referencias y siguientes pasos

• URLs base de las API de Polymarket: Gamma (https://gamma-api.polymarket.com), Data (https://data-api.polymarket.com), CLOB (https://clob.polymarket.com)
• Market WebSocket: wss://ws-subscriptions-clob.polymarket.com/ws/market
• Detalles del Builder Program y credenciales en https://polymarket.com/settings

Nota final: Polymarket sponsorea el gas vía el Relayer y proporciona SDKs en TypeScript y Python para simplificar flujos típicos de wallet y CTF. El Polymarket Relayer Client es la vía recomendada para construir integraciones gasless que interactúen con el CLOB y el CTF.

Preguntas frecuentes

¿Qué es el Polymarket Relayer Client?

El Polymarket Relayer Client es el SDK (TypeScript y Python) que enruta las transacciones de usuario a través del Relayer de Polymarket, manejando despliegue de wallets, aprobaciones ERC-20, operaciones CTF y colocación de órdenes para que los usuarios finales experimenten trading gasless.

¿Los usuarios siguen necesitando pUSD para tradear?

Sí. El activo de liquidación de Polymarket es pUSD (wrapped USDC). El Relayer sponsorea el gas, pero los usuarios deben poseer pUSD para realizar operaciones de split y colocar órdenes.

¿Puedo actuar como Builder a través del Relayer Client?

Sí. El Builder Program permite a terceros enrutar órdenes con cabeceras de atribución y ganar builder fees. Obtén credenciales en https://polymarket.com/settings e incluye las cabeceras de Builder según lo requiera el SDK.

¿El Relayer Client maneja aprobaciones y despliegue de wallet automáticamente?

El SDK provee helpers para el despliegue automático de Proxy wallets en el primer uso y para solicitar aprobaciones ERC-20 gasless a través del Relayer, simplificando el onboarding.

¿Dónde puedo leer actualizaciones del orderbook en tiempo real?

Suscríbete al Market WebSocket en wss://ws-subscriptions-clob.polymarket.com/ws/market. Solicita custom_feature_enabled: true para recibir eventos best_bid_ask y ten en cuenta el límite de 500 instrumentos por suscripción.