Endpoint de geobloqueo de Polymarket: pruebas, interpretación y aplicación de controles de acceso

Qué responde realmente el endpoint de geobloqueo

La ruta GET https://polymarket.com/api/geoblock es una verificación pública y no autenticada. No requiere clave de API, firma ni cuerpo de solicitud. Su función es indicar al llamador si la dirección IP que realizó la solicitud se considera bloqueada para la plataforma internacional de Polymarket, y devolver el código de país que la plataforma asoció con esa IP.

Ese alcance es deliberadamente limitado. El endpoint describe la IP solicitante, no su billetera, no sus credenciales de API y no el estado de cumplimiento del libro de órdenes. Es el mismo tipo de verificación que utiliza un frontend para decidir si mostrar una interfaz de trading. Tratar esto como una autorización de trading es la fuente más común de confusión: los desarrolladores ven blocked: false, luego reciben un 403 al enviar una orden y concluyen que el endpoint está roto. No está roto; está respondiendo una pregunta diferente a la que asumieron.

Esta guía cubre la mecánica de la solicitud, los campos de respuesta, un procedimiento de prueba reproducible en dos etapas y los modos de fallo que se interponen entre la verificación de geobloqueo y una orden exitosa. No publica una lista de países permitidos, porque esas listas cambian y el propio endpoint es la señal autoritativa en vivo para la IP desde la que está llamando.

• Público y no autenticado: sin clave de API, sin firma HMAC, sin billetera.
• Ámbito de IP: la respuesta depende de la IP de salida de la máquina que realiza la llamada.
• Informativo para el frontend y verificaciones previas; la ruta de órdenes del CLOB aplica sus propias reglas por separado.
• El código de país en la respuesta refleja la geolocalización de la IP, no los datos KYC de la cuenta.

Supuestos y requisitos previos

Los procedimientos a continuación asumen que puede realizar solicitudes HTTPS salientes desde el mismo host que enviará órdenes. Esa última cláusula es importante: si prueba desde una laptop y opera desde un servidor en la nube, está probando una IP diferente y posiblemente un país diferente. Ejecute cada verificación desde la ruta de salida de producción, o al menos desde un host con la misma salida de red.

Necesita un cliente HTTP funcional (curl, Python 3 con requests, o Node 18+ con fetch integrado), y para la prueba de la etapa de orden necesita credenciales válidas de la API del CLOB y una billetera financiada y aprobada. Si solo desea la respuesta de geobloqueo, no se requieren credenciales en absoluto. Para el lado blockchain de una pila de trading, el endpoint RPC que utilice para lecturas de Polygon y envío de transacciones es una dependencia separada; consulte la guía de endpoints RPC multicadena y la guía de endpoints RPC para saber cómo elegir y probar uno.

Modelo mental: dos puertas, no una

Piense en el acceso a Polymarket como dos puertas en serie. La primera puerta es la verificación pública de geobloqueo, que es económica, almacenable en caché y basada en IP. La segunda puerta es la capa de cumplimiento frente a los endpoints de trading del CLOB, que evalúa la solicitud de orden en sí. La segunda puerta puede ser más estricta que la primera: puede usar un conjunto de jurisdicciones más restrictivo, inteligencia de IP adicional como la clasificación de alojamiento versus residencial o indicadores de proxy, y contexto vinculado a la clave de API o a la billetera.

Una analogía útil es un edificio con un torniquete en el vestíbulo y un piso de trading cerrado con llave. El endpoint de geobloqueo le dice si el torniquete se abre para su IP. No dice nada sobre si la puerta del piso se abrirá para sus credenciales y su orden. Ambas puertas deben pasar, y fallan con síntomas diferentes: la primera puerta devuelve un cuerpo JSON con un booleano, la segunda típicamente devuelve un HTTP 403 con un mensaje de error sobre trading restringido en su región.

Por eso la arquitectura correcta es una verificación previa más una prueba de envío real, no solo la verificación previa. La verificación previa es rápida y gratuita y pertenece a sus diagnósticos de inicio y a cualquier banner de disponibilidad para el usuario. La prueba de envío es lo único que demuestra que la ruta completa funciona.

Llamada al endpoint con curl

La invocación más simple es un GET simple sin encabezados más allá de los que su cliente HTTP envía por defecto. Inspeccione tanto el código de estado como el cuerpo, porque un proxy o portal cautivo puede devolver un 200 con HTML que no es el JSON de geobloqueo.

La opción -i imprime los encabezados de respuesta para que pueda confirmar el tipo de contenido, y --max-time evita que una conexión colgada detenga un script de inicio. Si su infraestructura enruta a través de un proxy HTTP, agregue --proxy explícitamente para que la solicitud salga desde la IP que desea probar.

curl -sS -i --max-time 10 \
  -H 'Accept: application/json' \
  https://polymarket.com/api/geoblock

# Expected shape (values depend on your egress IP):
# HTTP/2 200
# content-type: application/json
#
# {"blocked": false, "country": "XX"}

Verificaciones programáticas en Python y JavaScript

Envuelva la llamada en una función pequeña que devuelva un resultado estructurado en lugar de una cadena sin procesar. La función debe distinguir tres resultados: una respuesta JSON válida, una respuesta que no sea 200 y un cuerpo que no se pueda analizar. Colapsar esos casos en un solo booleano oculta exactamente los fallos que necesitará depurar más adelante.

La versión de Python a continuación usa requests con un tiempo de espera y valida la presencia de la clave blocked. La versión de JavaScript usa el fetch integrado disponible en Node 18 y posteriores, por lo que no tiene dependencias. Ambas registran el código de país para que pueda confirmar que la IP de salida está donde cree que está.

import requests

GEOBLOCK_URL = "https://polymarket.com/api/geoblock"

def check_geoblock(timeout=10):
    try:
        resp = requests.get(GEOBLOCK_URL, headers={"Accept": "application/json"}, timeout=timeout)
    except requests.RequestException as exc:
        return {"ok": False, "reason": f"transport error: {exc}"}

    if resp.status_code != 200:
        return {"ok": False, "reason": f"http {resp.status_code}", "body": resp.text[:200]}

    try:
        data = resp.json()
    except ValueError:
        return {"ok": False, "reason": "non-json body", "body": resp.text[:200]}

    if "blocked" not in data:
        return {"ok": False, "reason": "missing blocked field", "data": data}

    return {"ok": True, "blocked": bool(data["blocked"]), "country": data.get("country")}

if __name__ == "__main__":
    print(check_geoblock())

# --- JavaScript (Node 18+) ---
# const res = await fetch("https://polymarket.com/api/geoblock", {
#   headers: { Accept: "application/json" },
#   signal: AbortSignal.timeout(10000),
# });
# const data = await res.json();
# console.log({ status: res.status, blocked: data.blocked, country: data.country });

Procedimiento de verificación en dos etapas con una tabla de resultados

Ejecute el siguiente procedimiento desde el host de salida de producción y registre cada fila en una tabla. No complete los valores esperados de memoria; el objetivo es capturar lo que su infraestructura devuelve realmente y compararlo con lo que su aplicación asume.

La etapa uno es el GET de geobloqueo. La etapa dos es un envío de orden mínimo y autenticado a través del cliente CLOB, usando un tamaño deliberadamente pequeño para que una colocación exitosa sea fácil de cancelar. Si la etapa dos no es apropiada para su entorno, sustituya una lectura autenticada que ejercite las mismas credenciales, como una consulta de saldo u órdenes abiertas, y anote en la tabla que la ruta de órdenes queda sin verificar.

Las columnas de la tabla a continuación son el mínimo necesario para diagnosticar una discrepancia. La columna IP de salida es esencial: si dos filas muestran IP diferentes, está comparando entornos diferentes y los resultados no son comparables.

• | Verificación | Comando o llamada | Estado observado | Cuerpo observado | IP de salida | País | Interpretación |
• | GET de geobloqueo | curl a /api/geoblock | (registrar) | (registrar) | (registrar) | (registrar) | blocked:false significa que la primera puerta pasó para esta IP |
• | Lectura autenticada | saldo del CLOB u órdenes abiertas | (registrar) | (registrar) | (registrar) | (registrar) | Demuestra que las credenciales y la firma son válidas |
• | Orden mínima | POST /order del CLOB, tamaño mínimo | (registrar) | (registrar) | (registrar) | (registrar) | Demuestra que la segunda puerta pasó para esta IP y cuenta |
• | Repetir desde un segundo host | las mismas tres llamadas | (registrar) | (registrar) | (registrar) | (registrar) | Las diferencias aíslan efectos a nivel de IP |

Lectura de la respuesta y confirmación de la IP de salida

Una respuesta saludable es HTTP 200 con un objeto JSON que contiene un campo booleano blocked y un campo country con un código de dos letras. El valor de país es la geolocalización que la plataforma hace de su IP, por lo que también es una verificación útil de su ruta de red. Si cree que está saliendo desde una región y el endpoint informa otra, investigue su NAT, proxy o el enrutamiento de su proveedor de nube antes de investigar Polymarket.

La verificación es sencilla: el valor blocked debe ser consistente en llamadas repetidas desde el mismo host dentro de una ventana corta, y el valor country debe coincidir con la región que su proveedor de nube asigna a ese rango de IP. Si alguno es inestable, probablemente tenga un grupo de salida rotativo o un proxy que balancea carga entre regiones. Esa inestabilidad también afectará la colocación de órdenes, así que corríjala en la capa de red en lugar de reintentar en el código de la aplicación.

Para las lecturas de blockchain que acompañan a un bot de trading, confirme su ruta RPC de forma independiente. Un endpoint dedicado de Polygon de un proveedor como el servicio de nodos dedicados de OnFinality elimina una variable de la pila, y puede comparar planes en la página de precios de RPC.

Por qué una verificación de geobloqueo exitosa aún puede terminar en un 403

El patrón más reportado es una respuesta blocked: false seguida de un 403 al enviar la orden con un mensaje de que el trading está restringido en la región del llamador. Las causas se agrupan en cuatro categorías, y cada una tiene una solución diferente.

Primero, conjuntos de jurisdicciones diferentes. La capa de cumplimiento de trading puede restringir un país que la verificación pública no marca, o puede aplicar semántica de solo cierre que permite lecturas pero no nuevas órdenes. Segundo, inteligencia de IP. Los rangos de proveedores de alojamiento, las salidas de VPN y los indicadores de proxy pueden tratarse de manera diferente a las IP residenciales incluso cuando el país coincide. Tercero, contexto de cuenta y clave. Una clave de API creada bajo una región, o una billetera con un historial asociado a una región restringida, puede llevar indicadores que la verificación de IP nunca ve. Cuarto, la orden en sí. El tipo de firma, la dirección del financiador y los problemas de asignación producen errores que se ven similares en los registros pero no son fallos de geobloqueo.

La disciplina de diagnóstico es cambiar una variable a la vez. Confirme la IP de salida, luego confirme las credenciales con una lectura autenticada, luego envíe una orden mínima. Si la lectura tiene éxito y la orden falla con un mensaje de región, el problema es la segunda puerta, no su código de firma.

• Mensaje de región en POST /order con GETs exitosos: sospeche de la capa de cumplimiento de trading, no de la autenticación.
• Fallos intermitentes: sospeche de IP de salida rotativas o de un grupo de proxies que abarca regiones.
• Errores consistentes 401 o de firma: corrija las credenciales antes de volver a probar el geobloqueo.
• Cambio repentino sin despliegue de código: vuelva a ejecutar la tabla; las listas de jurisdicciones y las clasificaciones de IP cambian.

Aplicación de la verificación dentro de su propia aplicación

Si está construyendo una integración que expone el trading de Polymarket, replique el patrón de la plataforma: llame al endpoint de geobloqueo del lado del servidor, desde la misma salida que su envío de órdenes, y condicione la interfaz de trading al resultado. No lo llame desde el navegador, porque la IP del navegador es la del usuario, no la de su servidor, y ambas pueden diferir de maneras que producen un comportamiento confuso.

Almacene el resultado en caché brevemente, del orden de minutos, con clave por IP de salida. La verificación es económica pero no gratuita, y una llamada por solicitud agrega latencia a cada carga de página. Más importante aún, trate el valor en caché como informativo: deje siempre que el envío de la orden sea la autoridad final, y muestre al usuario el mensaje de error de la plataforma en lugar de un fallo genérico.

El patrón de integración de referencia publicado por las propias herramientas de Polymarket sigue esta forma, y la referencia de integración de billetera segura es una lectura útil para el flujo de billetera y aprobación circundante. Para la capa RPC subyacente, el servicio de API de OnFinality y la lista de redes compatibles describen lo que está disponible sin comprometerse con un endpoint específico aquí.

// Server-side gate. Run on the same egress as order submission.
const GEOBLOCK_URL = "https://polymarket.com/api/geoblock";
const cache = new Map(); // key: egress label, value: { at, result }

async function geoblockFor(egressLabel, ttlMs = 120_000) {
  const hit = cache.get(egressLabel);
  if (hit && Date.now() - hit.at < ttlMs) return hit.result;

  const res = await fetch(GEOBLOCK_URL, {
    headers: { Accept: "application/json" },
    signal: AbortSignal.timeout(10_000),
  });
  if (!res.ok) throw new Error(`geoblock http ${res.status}`);

  const data = await res.json();
  const result = { blocked: Boolean(data.blocked), country: data.country ?? null };
  cache.set(egressLabel, { at: Date.now(), result });
  return result;
}

// Usage: gate the UI, but never treat this as order authorization.
const gate = await geoblockFor("prod-egress-a");
console.log(gate.blocked ? "show read-only view" : "allow trading UI");

Limitaciones y compensaciones

El endpoint de geobloqueo es una señal de conveniencia, no un contrato. La forma de su respuesta podría cambiar, su mapeo de países se deriva de la geolocalización de IP y por lo tanto hereda los errores de esos datos, y no puede ver restricciones a nivel de cuenta u orden. Construir una decisión de cumplimiento únicamente sobre este endpoint producirá tanto falsos positivos (bloquear usuarios que la capa de trading aceptaría) como falsos negativos (permitir usuarios que la capa de trading rechazará).

También existe una compensación entre latencia y fiabilidad al llamarlo en cada solicitud. Un caché corto reduce la carga pero amplía la ventana en la que se muestra una respuesta obsoleta. Para una interfaz de trading, el patrón más seguro es un banner informativo en caché más una ruta de error autoritativa en el envío. Finalmente, el endpoint no dice nada sobre la plataforma regulada de EE. UU., que es un producto separado con su propia documentación y modelo de autenticación; no asuma que la respuesta de geobloqueo internacional se aplica allí.

Si su aplicación depende de acceso a Polygon de baja latencia para el flujo circundante de billetera y liquidación, la elección del endpoint importa más que la llamada de geobloqueo en sí. La comparación de proveedores de baja latencia para Hyperliquid ilustra el enfoque de medición para infraestructura de trading sensible a la latencia, y el mismo método se aplica a cualquier cadena que utilice.

Próximos pasos para una integración en producción

Convierta el procedimiento de dos etapas en una autoprueba de inicio que se ejecute en cada despliegue y escriba su resultado en sus registros con la IP de salida adjunta. Ese único hábito convierte la mayoría de los incidentes relacionados con regiones de sesiones de depuración de varias horas en una búsqueda de una línea en los registros. Acompáñelo con una alerta si la respuesta de geobloqueo cambia para una salida estable, ya que eso generalmente indica un cambio de red de su lado o un cambio de jurisdicción del lado de la plataforma.

Para la elección concreta del endpoint RPC detrás de su pila de trading, use el Asistente de RPC en lugar de codificar un proveedor de un artículo; la comparación de las mejores API RPC de Ethereum y la guía de proveedores para proyectos Web3 describen los criterios de evaluación, y la guía de endpoints RPC cubre los patrones de solicitud que reutilizará. Mantenga la verificación de geobloqueo, la lectura autenticada y la prueba de orden mínima como tres señales separadas registradas de forma independiente, y siempre sabrá qué puerta falló.