x402 List

Base URL: https://x402-list.com/api/v1/

Todos los endpoints devuelven JSON. No se requiere autenticación para acceso de lectura. Límite de tasa: 200 solicitudes/min por IP (limitado suavemente por encima de 100). También puedes explorar el directorio de servicios o enviar un nuevo servicio al directorio a través de la interfaz web.

Inicio rápido para agentes

Todo en este directorio está disponible como JSON legible por máquina. Sin JavaScript, sin inicio de sesión, sin SDK requerido.

# List online services sorted by uptime
# (quote the URL: an unquoted & backgrounds the command in most shells)
$ curl 'https://x402-list.com/api/v1/services?status=online&sort=uptime&ref=docs'

# Fetch a specific service with endpoints and pricing
$ curl 'https://x402-list.com/api/v1/services/<slug>?ref=docs'

# Get the OpenAPI 3.1 specification (/openapi.json 301-redirects to /api/v1/openapi.json, so -L is required)
$ curl -L https://x402-list.com/openapi.json

Recursos priorizados para agentes: /openapi.json · /llms.txt · /llms-full.txt (llms.txt ~10KB, leer primero; openapi.json ~210KB; llms-full.txt ~290KB)

Servidor MCP

Un servidor de Protocolo de Contexto de Modelo de primera parte expone esta API a clientes MCP a través de 6 herramientas de solo lectura: x402_search_services, x402_get_service, x402_find_best_service, x402_check_health, x402_facilitator_volumes y x402_change_events, más x402_assess_services (DE PAGO, $0.25 USDC en Base).

Endpoint alojado (HTTP Streamable): https://mcp.x402-list.com/mcp. stdio local vía npm: npx -y x402-list-mcp. Ejemplo de configuración de cliente:

{
  "mcpServers": {
    "x402-list": {
      "command": "npx",
      "args": [
        "-y",
        "x402-list-mcp"
      ]
    }
  }
}

GET /api/v1/services

Devuelve una lista paginada de todos los servicios x402 registrados. Cada elemento también incluye un resumen compacto de assessment, null hasta que el servicio sea evaluado por primera vez. El ejemplo lo trunca a updated_at más el bloque de traction en cadena medido (volumen de 30 días, compradores distintos, concentración del mayor comprador; status lleva el significado de nulo-vs-cero, y caveat reafirma el subconteo conservador en banda). La forma completa del resumen está documentada en openapi.json (esquema AssessmentSummary). En una dirección de pago compartida, las cifras de tracción se atribuyen de forma proporcional (el total de la dirección dividido entre los servicios que la comparten), por lo que el bloque suma correctamente entre servicios; las series diarias de /volume y /buyers permanecen a nivel de dirección, por lo que NO se deben sumar entre servicios con pago compartido. El bloque de tracción también incluye first_settlement_at y totales de todo el tiempo (volume_usd_all_time, atribuido proporcionalmente en un pago compartido como el volumen de 30 días; tx_count_all_time, un conteo completo a nivel de operador que nunca se divide, como tx_count_30d), el median_settlement_usd_30d / max_settlement_usd_30d por liquidación (montos invariantes, nunca divididos), settled_via (los facilitadores que liquidaron este servicio en 30 días, primero por volumen) y shared_with_services (los otros servicios listados que actualmente comparten esta dirección de pago, vacío cuando el pago no es compartido).

Parámetros de consulta

Parámetro	Tipo	Descripción
network	string	Filtrar por abreviatura de red, sin distinción de mayúsculas: BSE, SOL, POL, ARB, BSP, AVX (ver /networks), o all para sin filtro. Nombres completos como base o solana no coinciden: cualquier otro valor devuelve 400 Bad Request
status	string	Filtrar por estado: online, degraded, offline, unknown
verified	boolean	Filtrar por el nivel verificado FORTE: true = una sonda de entrega de pago liquidada en cadena Y entregada, Y la insignia no fue revocada desde entonces por desviación de payTo/esquema; false = todo lo demás. Cambio semántico (treno D3): este filtro anteriormente significaba "responde a un desafío x402 válido y está vivo" (esa señal amplia ahora es payment_ready). Este nivel comienza vacío y crece solo con pagos reales, por lo que verified=true puede legítimamente devolver 0 filas. Aplicado en el servidor, por lo que meta.total cuenta el conjunto filtrado. Cualquier otro valor devuelve 400
payment_ready	boolean	Filtrar por el nivel de preparación de pago BASE: true = el endpoint responde a un desafío 402 x402 válido y está vivo dentro de la ventana de decadencia (un éxito de sonda en los últimos 7 días, o exento de clave API); false = todo lo demás. Esta es la señal amplia de descubrimiento que solía llevar el parámetro verified. Aplicado en el servidor, por lo que meta.total cuenta el conjunto filtrado. Cualquier otro valor devuelve 400
source	string	Filtrar por procedencia (cómo entró el listado al directorio): submitted, imported (cualquier origen importado), imported:bazaar, imported:x402scan o all para sin filtro. Coincide con el campo source en cada elemento. Cualquier otro valor devuelve 400
signable	boolean	Filtrar por la capacidad de firma del último sobre 402 observado: true = no se observó ninguna ruta EVM del servicio sin los parámetros de dominio EIP-712 (extra.name y extra.version) que un cliente x402 estándar requiere para firmar un pago; false = se observó al menos una de esas rutas. Describe el sobre de pago en el cable, no el mérito del servicio. Respaldado por la verificación eip712_domain_extra de la evaluación más reciente, el mismo id que encuentras en assessment.compliance_failed_checks. Un servicio cuya evaluación más reciente aún no ha medido esa verificación (nunca evaluado, evaluado antes de que existiera la verificación, o evaluado sin capturar ningún payload 402) coincide con ninguno de los valores, por lo que omite el parámetro para incluirlo. Aplicado en el servidor, por lo que meta.total cuenta el conjunto filtrado. Cualquier otro valor devuelve 400
category	string	Filtrar por categoría, sin distinción de mayúsculas (ver /categories)
sort	string	Orden de clasificación: newest (predeterminado), uptime, cheapest, endpoints
q	string	Búsqueda de subcadena en nombre, descripción, categoría y URL base. search y query se aceptan como alias; q gana cuando se envía más de uno
page	integer	Número de página (predeterminado: 1)
per_page	integer	Resultados por página, máximo 100 (predeterminado: 25)

Respuesta de ejemplo (?per_page=2)

Las cifras de todo el directorio en este ejemplo se leen en vivo cuando se renderiza esta página, nunca escritas a mano, por lo que no pueden desviarse de lo que devuelve el endpoint anterior.

{
  "data": [
    {
      "slug": "heron",
      "name": "Heron",
      "description": "Measures how visible a website is to AI search engines and returns a structured improvement plan. Per-audit price quoted in USDC on Base.",
      "base_url": "https://heronapp.io",
      "website_url": "https://heronapp.io",
      "category": "AI",
      "source": "submitted",
      "status": "online",
      "verified": false,
      "payment_ready": true,
      "endpoint_count": 1,
      "min_price_usd": 0.25043,
      "networks": [
        "BSE"
      ],
      "networks_caip2": [
        "eip155:8453"
      ],
      "uptime_24h": 100,
      "avg_response_time_ms": 306,
      "last_checked_at": "2026-07-06T10:21:00.405Z",
      "created_at": "2026-07-02T20:13:25.690Z",
      "assessment": null
    },
    {
      "slug": "netintel",
      "name": "NetIntel",
      "description": "Pay-per-call network and domain intelligence API: DNS, SSL/TLS, WHOIS/RDAP, email security, IP reputation, OSINT.",
      "base_url": "https://netintel.dev",
      "website_url": "https://netintel.dev",
      "category": "AI",
      "source": "submitted",
      "status": "online",
      "verified": false,
      "payment_ready": true,
      "endpoint_count": 37,
      "min_price_usd": 0,
      "networks": [
        "BSE"
      ],
      "networks_caip2": [
        "eip155:8453"
      ],
      "uptime_24h": 100,
      "avg_response_time_ms": 77,
      "last_checked_at": "2026-07-06T10:29:02.849Z",
      "created_at": "2026-07-01T13:57:51.651Z",
      "assessment": {
        "updated_at": "2026-07-06T09:00:00.000Z",
        "traction": {
          "status": "measured",
          "volume_usd_30d": 842.15,
          "tx_count_30d": 210,
          "unique_buyers_30d": 34,
          "last_settlement_at": "2026-07-06T08:41:00.000Z",
          "top_buyer_share_30d": 0.22,
          "trend_7d_vs_30d": 0.95,
          "shared_payout": false,
          "shared_with": 0,
          "pro_quota_share": 1,
          "measured_networks": [
            "eip155:8453"
          ],
          "first_settlement_at": "2026-05-14T12:03:00.000Z",
          "volume_usd_all_time": 5123.4,
          "tx_count_all_time": 1290,
          "median_settlement_usd_30d": 3.5,
          "max_settlement_usd_30d": 42,
          "settled_via": [
            "coinbase",
            "mrdn"
          ],
          "settled_via_detail": [
            {
              "id": "coinbase",
              "volume_usd_30d": 980.2,
              "tx_count_30d": 210
            },
            {
              "id": "mrdn",
              "volume_usd_30d": 260.5,
              "tx_count_30d": 65
            }
          ],
          "shared_with_services": [],
          "caveat": "Conservative undercount: only USDC settlements via facilitators we measure are counted. A measured floor, not an estimate.",
          "all_time_caveat": "All-time is floored at the start of our harvest window, not the service full history."
        }
      }
    }
  ],
  "meta": {
    "total": 867,
    "page": 1,
    "per_page": 2,
    "total_pages": 434
  }
}

GET /api/v1/services/:slug

Devuelve detalles completos de un solo servicio, incluido cada endpoint activo con sus precios por red. Los slugs desconocidos devuelven un sobre de error 404 (ver Formato de respuesta a continuación). La respuesta también incluye un objeto assessment respaldado por evidencia, null hasta que el servicio sea evaluado por primera vez. El ejemplo lo trunca a updated_at más el bloque de traction en cadena medido; status distingue un cero medido de un nulo no medido, y caveat reafirma el subconteo conservador en banda. Más allá de las cifras de 30 días, el bloque de tracción incluye first_settlement_at, volume_usd_all_time de todo el tiempo (proporcional en un pago compartido, como el volumen de 30 días) y tx_count_all_time (un conteo completo a nivel de operador que nunca se divide, como tx_count_30d), el median_settlement_usd_30d / max_settlement_usd_30d por liquidación (montos invariantes, nunca divididos), la lista de facilitadores settled_via (primero por volumen) y shared_with_services (los servicios hermanos listados en una dirección de pago compartida). La forma completa respaldada por evidencia (confiabilidad, cumplimiento x402, sitio, dominio, economía, riesgo, síntesis de IA) está documentada en openapi.json (esquema Assessment).

Respuesta de ejemplo (endpoints truncados a 1 entrada)

{
  "data": {
    "slug": "netintel",
    "name": "NetIntel",
    "description": "Pay-per-call network and domain intelligence API: DNS, SSL/TLS, WHOIS/RDAP, email security, IP reputation, OSINT.",
    "base_url": "https://netintel.dev",
    "website_url": "https://netintel.dev",
    "category": "AI",
    "endpoint_count": 1,
    "min_price_usd": 0.03,
    "uptime_24h": 100,
    "source": "submitted",
    "status": "online",
    "verified": false,
    "verified_until": null,
    "payment_ready": true,
    "payment_ready_until": "2026-07-13T10:29:02.852Z",
    "consecutive_failures": 0,
    "check_interval_minutes": 15,
    "last_checked_at": "2026-07-06T10:29:02.852Z",
    "created_at": "2026-07-01T13:57:51.651Z",
    "uptime": {
      "24h": 100,
      "7d": 100,
      "30d": 100,
      "90d": 100
    },
    "avg_response_time_ms": 77,
    "total_checks": 438,
    "networks": [
      "BSE"
    ],
    "networks_caip2": [
      "eip155:8453"
    ],
    "asset": "USDC",
    "endpoints": [
      {
        "id": "a9d34456-f44f-4383-8696-b2acbe46f6bf",
        "method": "GET",
        "path": "/asn-lookup/analyze",
        "description": null,
        "mime_type": null,
        "is_active": true,
        "first_seen_at": "2026-07-01T13:57:51.651Z",
        "last_seen_at": "2026-07-06T10:29:02.775Z",
        "min_price_usd": 0.03,
        "networks": [
          "BSE"
        ],
        "pricing": [
          {
            "scheme": "exact",
            "network": "eip155:8453",
            "network_caip2": "eip155:8453",
            "asset_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
            "asset_address_norm": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
            "asset_name": "USDC",
            "price": "30000",
            "price_usd": "0.0300000000",
            "pay_to": "0xdaDc335482AD545296Fd7b28518A251fFCbEb9Df",
            "max_timeout_seconds": 300
          }
        ]
      }
    ],
    "assessment": {
      "updated_at": "2026-07-06T09:00:00.000Z",
      "traction": {
        "status": "measured",
        "volume_usd_30d": 842.15,
        "tx_count_30d": 210,
        "unique_buyers_30d": 34,
        "last_settlement_at": "2026-07-06T08:41:00.000Z",
        "top_buyer_share_30d": 0.22,
        "trend_7d_vs_30d": 0.95,
        "shared_payout": false,
        "shared_with": 0,
        "pro_quota_share": 1,
        "measured_networks": [
          "eip155:8453"
        ],
        "first_settlement_at": "2026-05-14T12:03:00.000Z",
        "volume_usd_all_time": 5123.4,
        "tx_count_all_time": 1290,
        "median_settlement_usd_30d": 3.5,
        "max_settlement_usd_30d": 42,
        "settled_via": [
          "coinbase",
          "mrdn"
        ],
        "settled_via_detail": [
          {
            "id": "coinbase",
            "volume_usd_30d": 980.2,
            "tx_count_30d": 210
          },
          {
            "id": "mrdn",
            "volume_usd_30d": 260.5,
            "tx_count_30d": 65
          }
        ],
        "shared_with_services": [],
        "caveat": "Conservative undercount: only USDC settlements via facilitators we measure are counted. A measured floor, not an estimate.",
        "all_time_caveat": "All-time is floored at the start of our harvest window, not the service full history."
      }
    }
  }
}

GET /api/v1/services/:slug/uptime

Devuelve resúmenes diarios de tiempo de actividad para el servicio durante el período solicitado, primero los más recientes: una entrada por día con porcentaje de tiempo de actividad, tiempo de respuesta promedio y conteos de verificación.

Parámetros de consulta

Parámetro	Tipo	Descripción
period	string	Ventana de tiempo: 24h, 7d, 30d, 90d (predeterminado: 30d). Cualquier otro valor devuelve 400

Respuesta de ejemplo (?period=7d, truncado a 2 entradas)

{
  "data": [
    {
      "period_start": "2026-07-06T00:00:00.000Z",
      "period_end": "2026-07-07T00:00:00.000Z",
      "uptime_percentage": 100,
      "avg_response_time_ms": 69.76,
      "total_checks": 38,
      "successful_checks": 38
    },
    {
      "period_start": "2026-07-05T00:00:00.000Z",
      "period_end": "2026-07-06T00:00:00.000Z",
      "uptime_percentage": 100,
      "avg_response_time_ms": 71.18,
      "total_checks": 90,
      "successful_checks": 90
    }
  ]
}

GET /api/v1/services/:slug/volume

Devuelve el volumen de liquidación en cadena medido para el servicio a lo largo del tiempo (USD), un punto por día UTC, primero los más antiguos. El volumen se lee directamente en cadena mediante atribución de liquidadores sobre el mapeo payTo del servicio (solo USDC), nunca autoinformado, y es un subconteo conservador: solo se cuentan las liquidaciones que el monitor observó. La serie está honestamente vacía hasta que se observa una liquidación. Los días sin liquidación observada se omiten, por lo que la serie es dispersa (un punto por día UTC liquidado), no una cuadrícula diaria densa. La semántica de estado y nulo-vs-cero se lleva en el bloque assessment.traction del detalle del servicio.

Parámetros de consulta

Parámetro	Tipo	Descripción
period	string	Ventana de tiempo: 24h, 7d, 30d, 90d, all (predeterminado: 90d). all lee el historial completo registrado. Cualquier otro valor devuelve 400

Respuesta de ejemplo (?period=7d, truncado a 2 entradas)

{
  "data": [
    {
      "date": "2026-07-05",
      "volume_usd": 12.47,
      "tx_count": 39
    },
    {
      "date": "2026-07-06",
      "volume_usd": 9.8,
      "tx_count": 31
    }
  ],
  "caveat": "Conservative undercount: only USDC settlements via facilitators we measure are counted. Operator-level (the full payout address), not pro-rata: do not sum across services that share a payout address."
}

GET /api/v1/services/:slug/buyers

Devuelve el conteo medido de compradores distintos en cadena para el servicio a lo largo del tiempo, un punto por día UTC, primero los más antiguos. Los compradores distintos se cuentan directamente de las liquidaciones brutas por día (nunca sumados de un resumen) sobre el mapeo payTo del servicio, solo USDC. Como la serie de volumen, es un subconteo conservador y está honestamente vacía hasta que se observa una liquidación. Los días sin liquidación observada se omiten, por lo que la serie es dispersa (un punto por día UTC liquidado), no una cuadrícula diaria densa.

Parámetros de consulta

Parámetro	Tipo	Descripción
period	string	Ventana de tiempo: 24h, 7d, 30d, 90d, all (predeterminado: 90d). all lee el historial completo registrado. Cualquier otro valor devuelve 400

Respuesta de ejemplo (?period=7d, truncado a 2 entradas)

{
  "data": [
    {
      "date": "2026-07-05",
      "unique_buyers": 7
    },
    {
      "date": "2026-07-06",
      "unique_buyers": 5
    }
  ],
  "caveat": "Conservative undercount: only USDC settlements via facilitators we measure are counted. Operator-level (the full payout address), not pro-rata: do not sum across services that share a payout address."
}

GET /api/v1/services/:slug/price

Devuelve el movimiento de precio 402 capturado para el servicio a lo largo del tiempo (USD), primero los más antiguos, un punto por observación. Los precios se leen del handshake 402 en vivo, nunca autoinformados. Cada punto lleva el endpoint_id, network y asset_address para los que fue registrado: un servicio que cotiza varios endpoints, redes o activos devuelve sus series intercaladas por tiempo, por lo que agrupa en esos tres campos antes de leer una línea de precio individual. La serie no se limita a la fila de precios actual, por lo que es el historial completo de movimiento de precios en lugar de solo el precio en vivo. Está honestamente vacía hasta que se observa un precio.

Parámetros de consulta

Parámetro	Tipo	Descripción
period	string	Ventana de tiempo: 24h, 7d, 30d, 90d, all (predeterminado: 90d). all lee el historial completo registrado. Cualquier otro valor devuelve 400

Respuesta de ejemplo (?period=30d, truncado a 2 entradas)

{
  "data": [
    {
      "recorded_at": "2026-07-02T20:13:25Z",
      "price_usd": 9.25,
      "endpoint_id": "89e66731-aa8e-44ad-9b71-bca738f01876",
      "network": "eip155:8453",
      "asset_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bDA02913"
    },
    {
      "recorded_at": "2026-07-02T20:14:00Z",
      "price_usd": 9.26,
      "endpoint_id": "89e66731-aa8e-44ad-9b71-bca738f01876",
      "network": "eip155:8453",
      "asset_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bDA02913"
    }
  ]
}

GET /api/v1/services/:slug/scores

Devuelve las subpuntuaciones de evaluación medidas para el servicio a lo largo del tiempo, primero los más antiguos, un punto por ejecución de evaluación: la calificación de cumplimiento x402 con sus conteos de verificaciones aprobadas y totales, más las ventanas de confiabilidad (tiempo de actividad 24h y 30d, p95 de respuesta). Estas son solo las subpuntuaciones medidas, no la puntuación compuesta clasificada que publican las páginas de servicio (esa se calcula en vivo sobre el grupo actual por el mismo motor detrás de /api/v1/best), y el punto no lleva ningún campo derivado de IA: cada valor en él es medido. La serie está honestamente vacía hasta que el servicio ha sido evaluado. Lee compliance_passed contra el compliance_total del mismo punto y nunca contra el de hoy: la lista de verificación creció de 11 a 14 verificaciones cuando se agregaron las tres verificaciones de capacidad de firma, por lo que la serie tiene un escalón en esa fecha (visible en el ejemplo a continuación). Los puntos registrados anteriormente mantienen el denominador con el que fueron medidos, porque recalcularlos significaría reescribir una observación después del hecho.

Parámetros de consulta

Parámetro	Tipo	Descripción
period	string	Ventana de tiempo: 24h, 7d, 30d, 90d, all (predeterminado: 90d). all lee el historial completo registrado. Cualquier otro valor devuelve 400

Respuesta de ejemplo (?period=30d, truncada a 2 entradas)

{
  "data": [
    {
      "recorded_at": "2026-07-13T02:14:55.773Z",
      "compliance_grade": "A",
      "compliance_passed": 11,
      "compliance_total": 11,
      "uptime_24h": 100,
      "uptime_30d": 100,
      "response_p95_ms": 1297
    },
    {
      "recorded_at": "2026-07-29T12:05:01.670Z",
      "compliance_grade": "A",
      "compliance_passed": 14,
      "compliance_total": 14,
      "uptime_24h": 100,
      "uptime_30d": 100,
      "response_p95_ms": 1315
    }
  ]
}

GET /api/v1/services/:slug/checks

Devuelve los resultados individuales de comprobaciones de salud de un servicio, de más reciente a más antiguo.

Parámetros de consulta

Parámetro	Tipo	Descripción
limit	integer	Número de resultados, máximo 100 (predeterminado: 20)
offset	integer	Desplazamiento para paginación (predeterminado: 0)

Respuesta de ejemplo (?limit=2)

{
  "data": [
    {
      "id": "aa7af11f-d67b-4b32-9539-79758b3623fa",
      "checked_at": "2026-07-06T10:29:02.849Z",
      "response_time_ms": 72,
      "status_code": 402,
      "is_up": true,
      "error_message": null,
      "endpoints_found": 37
    },
    {
      "id": "00f471af-8b24-44a4-9e44-e99e28800c5b",
      "checked_at": "2026-07-06T10:13:02.631Z",
      "response_time_ms": 66,
      "status_code": 402,
      "is_up": true,
      "error_message": null,
      "endpoints_found": 37
    }
  ],
  "meta": {
    "total": 438
  }
}

GET /api/v1/checks

Fuente en vivo de comprobaciones de salud en todos los servicios, de más reciente a más antiguo. Útil para construir paneles en tiempo real.

Parámetros de consulta

Parámetro	Tipo	Descripción
limit	integer	Número de resultados, máximo 100 (predeterminado: 50)
offset	integer	Desplazamiento para paginación (predeterminado: 0)

Respuesta de ejemplo (?limit=2)

Las cifras generales del directorio en este ejemplo se leen en vivo cuando se renderiza esta página, nunca se escriben a mano, por lo que no pueden desviarse de lo que devuelve el endpoint anterior.

{
  "data": [
    {
      "id": "dfb29787-0fa7-49d7-ba89-6e9ae7ab3925",
      "checked_at": "2026-07-06T10:29:20.071Z",
      "is_up": false,
      "response_time_ms": 2500,
      "status_code": null,
      "endpoints_found": 0,
      "service_name": "Sivut Public Data APIs",
      "service_slug": "sivut-public-data-apis",
      "service_status": "offline"
    },
    {
      "id": "d602008c-e915-4b27-b868-f5d6f6f0a05d",
      "checked_at": "2026-07-06T10:29:02.942Z",
      "is_up": true,
      "response_time_ms": 953,
      "status_code": 402,
      "endpoints_found": 3,
      "service_name": "AsterPay",
      "service_slug": "asterpay",
      "service_status": "online"
    }
  ],
  "meta": {
    "total": 1769268
  }
}

GET /api/v1/changes

Fuente de cambios detectados en el cable x402 en vivo, de más reciente a más antiguo. Cada evento se compara con todo el accepts[] que un servicio devuelve en cada sonda, por lo que una rotación de payTo (dirección de liquidación) a un precio sin cambios aparece aquí aunque el seguimiento solo por precio lo pasaría por alto. Los tipos de eventos son payto_changed, price_changed y schema_changed (endpoints, redes, activos o versión de protocolo añadidos o eliminados). Los eventos se conservan perpetuamente; la ventana solo limita la fuente.

Parámetros de consulta

Parámetro	Tipo	Descripción
service	string	Filtrar a un solo servicio por slug
type	string	Filtrar por tipo de evento: payto_changed, price_changed o schema_changed (cualquier otro valor devuelve 400)
days	integer	Ventana móvil en días, limitada a 1-365 (predeterminado: 90)
page	integer	Número de página (predeterminado: 1)
per_page	integer	Resultados por página, máximo 100 (predeterminado: 25)

Respuesta de ejemplo (?type=payto_changed&per_page=1)

{
  "data": [
    {
      "slug": "acme-generate",
      "name": "Acme Generate",
      "type": "payto_changed",
      "observed_at": "2026-07-24T09:12:00.000Z",
      "summary": {
        "payToAdded": [
          "0x1111111111111111111111111111111111111111"
        ],
        "payToRemoved": [
          "0x2222222222222222222222222222222222222222"
        ]
      },
      "old_snapshot": [
        {
          "endpoint": "GET /v1/generate",
          "scheme": "exact",
          "network": "eip155:8453",
          "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
          "assetName": "USDC",
          "payTo": "0x2222222222222222222222222222222222222222",
          "price": "10000",
          "mimeType": "application/json",
          "x402Version": 2
        }
      ],
      "new_snapshot": [
        {
          "endpoint": "GET /v1/generate",
          "scheme": "exact",
          "network": "eip155:8453",
          "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
          "assetName": "USDC",
          "payTo": "0x1111111111111111111111111111111111111111",
          "price": "10000",
          "mimeType": "application/json",
          "x402Version": 2
        }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 1,
    "total_pages": 1,
    "days": 90
  }
}

GET /api/v1/best

Recomendador. Devuelve el/los mejor(es) servicio(s) x402 para una necesidad declarada en una sola solicitud, sin paginación. Ejecuta la misma clasificación de dos etapas que la herramienta MCP x402_find_best_service, del lado del servidor: (1) cuando se proporciona un q de texto libre, cada candidato se puntúa según qué tan bien coincide tu consulta con sus etiquetas de capacidad y resumen generados por IA, además de su nombre, descripción y categoría; (2) calidad medida en confiabilidad (estado en vivo, tiempo de actividad, tiempo de respuesta), cumplimiento de x402, economía (precio y percentil dentro de la categoría) y riesgo de seguridad, con un peso pequeño (alrededor del 10%) en tracción en cadena. El término de cumplimiento es la proporción de comprobaciones de conformidad deterministas que el servicio aprueba, limitado a 0.6 (el piso de la banda C) cuando al menos una de sus rutas EVM carece de los parámetros de dominio EIP-712 que un cliente x402 estándar necesita para firmar un pago: un hecho sobre el sobre, no un juicio sobre el servicio. Ese límite es lo que movió la puntuación a la generación 2; la generación que este endpoint sirve hoy es 3, leída del propio clasificador, y también condiciona el término de tracción a un piso absoluto de volumen de 30 días, descuenta un pago concentrado en un solo comprador, y puntúa un servicio que no publica payTo como cero en lugar de renormar alrededor de él. Las puntuaciones que almacenaste bajo una generación anterior no son comparables con estas, y meta.ranking_version en cada respuesta es lo que te indica qué generación las produjo. Un servicio marcado determinísticamente como peligroso se elimina y su slug se devuelve en excluded_danger; una advertencia residual se penaliza pero se conserva. Este endpoint es gratuito y se mide como cualquier otra lectura (ver Medición). Los precios están en dólares estadounidenses decimales.

Parámetros de consulta

Parámetro	Tipo	Descripción
q	string	Necesidad de texto libre, comparada con el nombre, descripción, categoría, etiquetas de capacidad IA y resumen de cada servicio
category	string	Categoría deseada (exacta, sin distinguir mayúsculas)
network	string	Nombre o abreviatura de red requerido, p. ej. Base o BSE; un valor fuera del conjunto conocido devuelve 400
max_price_usd	number	Límite en min_price_usd en USD; más barato o igual pasa (un servicio sin precio conocido se excluye)
require_verified	boolean	Si es true, solo los servicios verificados de nivel FORTE son elegibles (treno D3: una sonda de entrega pagada liquidada y entregada; el nivel base listo para pago NO se incluye). Un filtro estricto sobre el grupo elegible, no una entrada de puntuación, por lo que no cambia ranking_version. Acepta true o false
prefer	string	Énfasis para desempate: balanced (predeterminado), cheapest, fastest o most_reliable
limit	integer	Cuántas recomendaciones devolver, limitado a 1-20 (predeterminado: 5)
include_facilitator_context	boolean	Si es true, también devuelve los principales facilitadores por volumen de liquidación de 7 días como contexto de ecosistema separado, no por servicio (acepta true o false)

Respuesta de ejemplo (?q=weather&prefer=cheapest&limit=1)

{
  "data": {
    "recommendations": [
      {
        "rank": 1,
        "slug": "weather-x402",
        "name": "Weather x402",
        "category": "Data",
        "status": "online",
        "verified": true,
        "payment_ready": true,
        "uptime_24h": 100,
        "avg_response_time_ms": 120,
        "min_price_usd": 0.01,
        "price_max_usd": 0.01,
        "category_percentile_max": 10,
        "distinct_price_count": 1,
        "networks": [
          "BSE"
        ],
        "endpoint_count": 2,
        "compliance_grade": "A",
        "compliance_failed_checks": [],
        "risk_level": "clean",
        "capability_tags": {
          "value": [
            "weather",
            "forecast"
          ],
          "confidence": 0.9,
          "source": "ai"
        },
        "traction_status": "measured",
        "volume_usd_30d": 42.5,
        "unique_buyers_30d": 7,
        "shared_payout": false,
        "top_buyer_share_30d": 0.3,
        "score": 0.82,
        "relevance": 1,
        "quality": 0.79,
        "why": "online, verified, 100% 24h uptime, 120ms, $0.01 min price, compliance A"
      }
    ],
    "ranking_basis": "Two stages. (1) RELEVANCE: when a free-text need is given, each candidate is scored on how well your query matches its AI-derived capability tags and summary plus its name/description/category (falls back to plain text match). (2) QUALITY: measured families combined with explicit weights - reliability (live status, uptime, response time), x402 compliance (the share of deterministic conformance checks the service passes, capped at 0.6 out of 1, the floor of the C band, when at least one of its EVM routes is missing the EIP-712 domain parameters a standard x402 client needs in order to sign a payment), economics (price and in-category price percentile), safety risk, and a SMALL ~10% weight on on-chain traction (per-service settlement volume, transaction count and unique buyers, measured over the service's known payTo via recognized settlers as a conservative undercount). Traction never dominates; a service with a shared payTo has only its settlement volume attributed pro-quota (divided across the services sharing that payout address), while transaction count and unique buyers stay whole operator-level figures, and a service on an unmeasured network or a shared member whose probe is failing carries no traction term (the other weights are renormalized). The term also gates on real recent settlement: it scores 0 when there was no settlement in the last 30 UTC days, or when 30d volume is below a $10 floor (sub-floor volume is indistinguishable from dust and never moves rank). Each recommendation also carries top_buyer_share_30d (0-1, the 30d volume share of the largest single buyer); a payout concentrated in one buyer is discounted, up to half the traction term when a single buyer accounts for all of it, since one buyer is one relationship rather than the broad demand the term is meant to reward. AI-derived fields are labeled {value,confidence,source:'ai'} and NEVER override a measured value.",
    "excluded_danger": [],
    "facilitator_context": null
  },
  "meta": {
    "ranking_version": 3
  }
}

GET /api/v1/status

Salud agregada de la plataforma: conteos por estado más una entrada de estado por servicio para cada servicio listado (el arreglo services se trunca a 2 entradas aquí).

Respuesta de ejemplo

Las cifras generales del directorio en este ejemplo se leen en vivo cuando se renderiza esta página, nunca se escriben a mano, por lo que no pueden desviarse de lo que devuelve el endpoint anterior.

{
  "data": {
    "total": 867,
    "online": 663,
    "degraded": 63,
    "offline": 141,
    "unknown": 0,
    "services": [
      {
        "slug": "2s-io",
        "name": "2s.io",
        "status": "online",
        "last_checked_at": "2026-07-06T10:16:01.134Z",
        "consecutive_failures": 0,
        "uptime_24h": 100,
        "avg_response_time_ms": 185.45
      },
      {
        "slug": "aeo-audit-api",
        "name": "AEO Audit API",
        "status": "online",
        "last_checked_at": "2026-07-06T10:25:00.433Z",
        "consecutive_failures": 0,
        "uptime_24h": 100,
        "avg_response_time_ms": 285.53
      }
    ]
  }
}

GET /api/v1/networks

Lista todas las redes blockchain rastreadas por x402 List, con conteos de servicios por red y tiempo de actividad promedio. Los valores de abbreviation son lo que el filtro ?network= en /services acepta. Respuesta truncada a 2 entradas aquí.

Respuesta de ejemplo

Las cifras generales del directorio en este ejemplo se leen en vivo cuando se renderiza esta página, nunca se escriben a mano, por lo que no pueden desviarse de lo que devuelve el endpoint anterior.

{
  "data": [
    {
      "id": "836f6a83-251b-41ba-b44a-c6be54139ebb",
      "caip2_id": "eip155:8453",
      "caip2": "eip155:8453",
      "name": "Base",
      "abbreviation": "BSE",
      "chain_type": "evm",
      "is_mainnet": true,
      "explorer_url": "https://basescan.org",
      "service_count": 819,
      "avg_uptime": 84.8
    },
    {
      "id": "393fd87c-3aa5-4f2e-86c7-52a7623d9d66",
      "caip2_id": "solana:5eykt4usfv8p8njdtrepy1vzqkqzkvdp",
      "caip2": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "name": "Solana",
      "abbreviation": "SOL",
      "chain_type": "svm",
      "is_mainnet": true,
      "explorer_url": "https://solscan.io",
      "service_count": 268,
      "avg_uptime": 89.6
    }
  ],
  "meta": {
    "avg_uptime_method": "per-service mean of the latest daily uptime rollup"
  }
}

GET /api/v1/stats

Estadísticas agregadas de toda la plataforma: totales de servicios y endpoints, promedios de tiempo de actividad, distribución de precios, un desglose por red (truncado a 2 entradas aquí) y un bloque de traction en cadena medido de 30 días agregado entre los servicios listados mediante deduplicación por identidad de liquidación (network, tx_hash, log_index), nunca sumado a partir de las cifras por servicio. Es un piso medido de los últimos 30 días, no un total del ecosistema. El bloque de tracción también lleva coverage_of_measured_flow_pct (el volumen deduplicado listado como proporción del flujo medible por nuestros liquidadores rastreados, no todo el ecosistema) y top_10_services_share_pct (la participación de los 10 principales servicios en ese mismo volumen, una divulgación de concentración); ambos se precalculan por hora y son null hasta la primera actualización. Junto a ellos, measured_flow_freshness indica qué tan fresco sigue siendo ese flujo medido: la antigüedad del cursor de sincronización del liquidador más atrasado, cuántos grupos de sincronización (uno por facilitador, red y token) están congelados más allá del umbral de obsolescencia de dos horas, y cuántos facilitadores tienen al menos un grupo congelado, para que una cifra de cobertura calculada sobre una ingesta congelada pueda distinguirse de una calculada sobre una ingesta en vivo. La frescura se lee por grupo de sincronización y nunca se resume por el grupo más fresco de un facilitador: un facilitador que aún sincroniza una red a tiempo mientras otra está congelada se cuenta como obsoleto aquí. Junto al bloque de tracción, la respuesta también lleva cifras de salud del directorio: verified_count (el nivel FORTE, treno D3: una sonda de entrega pagada liquidada y entregada, el mismo predicado que el filtro ?verified=true; comienza en 0 y crece solo con pagos reales), payment_ready_count (el nivel BASE: responde un desafío x402 válido y está vivo, el mismo predicado que ?payment_ready=true, la señal amplia que verified_count solía llevar), listing_growth (new_7d / new_30d, servicios listados por primera vez en los últimos 7 / 30 días), y facilitator_volume_usd_30d con su facilitator_volume_note (volumen de liquidación agregado de 30 días entre los facilitadores medidos, un superconjunto no deduplicado del flujo de servicios listados; null hasta que existan instantáneas).

Respuesta de ejemplo

Las cifras generales del directorio en este ejemplo se leen en vivo cuando se renderiza esta página, nunca se escriben a mano, por lo que no pueden desviarse de lo que devuelve el endpoint anterior.

{
  "data": {
    "total_services": 867,
    "total_endpoints": 5742,
    "total_networks": 38,
    "total_networks_note": "mainnet networks only; networks[] includes testnets flagged by is_mainnet",
    "avg_uptime_24h": 83.6,
    "avg_uptime_7d": 85.4,
    "avg_uptime_method": "per-service mean of the latest daily uptime rollup",
    "avg_response_time_ms": 730,
    "checks_per_hour": 2994,
    "pricing": {
      "avg_price_usd": 0.397,
      "min_price_usd": 0,
      "max_price_usd": 50,
      "median_price_usd": 0.01
    },
    "networks": [
      {
        "abbreviation": "BSE",
        "is_mainnet": true,
        "service_count": 819,
        "avg_uptime": 84.8
      },
      {
        "abbreviation": "SOL",
        "is_mainnet": true,
        "service_count": 268,
        "avg_uptime": 89.6
      }
    ],
    "traction": {
      "unique_buyers_30d": 4767,
      "volume_usd_30d": 53492.382143,
      "settlement_count_30d": 500276,
      "measured_services": 593,
      "measured_networks": [
        "BSE",
        "SOL"
      ],
      "coverage_of_measured_flow_pct": 7.6,
      "measured_flow_freshness": {
        "oldest_cursor_age_seconds": 29255,
        "stale_sync_groups": 1,
        "total_sync_groups": 52,
        "stale_facilitators": 1,
        "total_facilitators": 38
      },
      "top_10_services_share_pct": 89.8,
      "top_1_service_share_pct": 64.2,
      "top_1_service_top_buyer_share_pct": 7.6,
      "method": "dedup on settlement identity (network,tx_hash,log_index); do not sum per-service figures; measured_networks are network abbreviations, the per-service traction block uses CAIP-2 ids; coverage_of_measured_flow_pct is the listed dedup volume as a share of the flow measurable by our tracked settlers (the facilitator daily volume we measure, not the whole ecosystem); top_10_services_share_pct is the top 10 services' share of the same 30d dedup volume; both are precomputed hourly and null until the first refresh",
      "caveat": "measured across listed services, a measured floor over 30d, not an ecosystem total; USDC via measured facilitators only"
    },
    "verified_count": 13,
    "payment_ready_count": 750,
    "listing_growth": {
      "new_7d": 85,
      "new_30d": 306
    },
    "facilitator_volume_usd_30d": 680103.69,
    "facilitator_volume_note": "Aggregate facilitator settlement volume over 30 days across measured facilitators; a superset of the listed-services flow, not de-duplicated on settlement identity."
  }
}

GET /api/v1/categories

Lista las etiquetas de categoría actualmente en uso, como un arreglo plano de cadenas. Usa estos valores para el filtro ?category= en /services y el campo category de POST /submit. La taxonomía anterior /api/v1/tags se ha eliminado y ahora devuelve 410 Gone.

Respuesta de ejemplo

{
  "data": [
    "AI",
    "Blockchain",
    "Compute",
    "Content",
    "Data",
    "Finance",
    "Other",
    "Verification"
  ]
}

GET /api/v1/facilitators

Lista paginada de facilitadores x402 con volúmenes de liquidación medidos en cadena, ordenados por volumen en el período de tiempo seleccionado. verification es on-chain (medido a partir de transacciones blockchain) o listed (cadena declarada por una dirección de liquidador, aún no medida).

Parámetros de consulta

Parámetro	Tipo	Descripción
timeframe	string	Ventana que impulsa el orden de clasificación: 24h, 7d, 30d, all (predeterminado: 7d)
include	string	Incrustaciones opcionales separadas por comas: timeseries (serie de volumen diario) y/o chains (desglose por red y por token)
days	integer	Longitud de la ventana de series temporales incrustadas, 1 a 90 (predeterminado: 30, solo con include=timeseries)
page	integer	Número de página (predeterminado: 1)
per_page	integer	Resultados por página, máximo 100 (predeterminado: 25)

Respuesta de ejemplo (truncada a 2 entradas)

Solo meta.total, el conteo de facilitadores rastreados, se lee en vivo en este ejemplo. Las dos filas anteriores son una instantánea ilustrativa de facilitadores reales tomada en julio de 2026, conservada por la forma de la respuesta: sus volúmenes han cambiado mucho desde entonces, así que llama a GET /api/v1/facilitators para obtener los actuales.

{
  "data": [
    {
      "facilitator_id": "coinbase",
      "name": "Coinbase",
      "website_url": "https://docs.cdp.coinbase.com/x402/welcome",
      "volume_usd_24h": 2427.75,
      "volume_usd_7d": 36219.99,
      "volume_usd_30d": 193952.67,
      "volume_usd_all": 1573230.28,
      "tx_count_24h": 151811,
      "tx_count_7d": 1399119,
      "tx_count_30d": 8869191,
      "tx_count_all": 16978418,
      "last_activity_at": "2026-07-06T00:00:00.000Z",
      "first_activity_at": "2026-04-05T00:00:00.000Z",
      "settler_count": 35,
      "verification": "on-chain"
    },
    {
      "facilitator_id": "mrdn",
      "name": "Meridian",
      "website_url": "https://docs.mrdn.finance",
      "volume_usd_24h": 2331.97,
      "volume_usd_7d": 32219.96,
      "volume_usd_30d": 187217.82,
      "volume_usd_all": 1236223.48,
      "tx_count_24h": 113,
      "tx_count_7d": 1709,
      "tx_count_30d": 8315,
      "tx_count_all": 57941,
      "last_activity_at": "2026-07-06T00:00:00.000Z",
      "first_activity_at": "2026-04-12T00:00:00.000Z",
      "settler_count": 1,
      "verification": "on-chain"
    }
  ],
  "meta": {
    "total": 38,
    "page": 1,
    "per_page": 25,
    "total_pages": 2,
    "timeframe": "7d"
  }
}

GET /api/v1/facilitators/:id

Detalle completo de un solo facilitador: las mismas cifras de volumen y liquidación que la fila de la lista, más el desglose chains por (red, token) (ahora con first_activity_at), los settlers en cadena (EOAs), buyers distintos por cadena, USD promedio por liquidación y una tendencia de 7 días, el series diario, y el puente listed_services (qué servicios del directorio liquidan aquí). Un id desconocido se compara sin distinguir mayúsculas y redirige con 301 al id canónico antes de devolver 404. avg_settlement_usd_all / avg_settlement_usd_30d son volumen sobre conteo de liquidaciones y son null (nunca un 0 fabricado) cuando no hay nada que promediar; trend_7d_vs_prev_7d compara los últimos 7 días con los 7 anteriores y es null cuando la ventana anterior está vacía. El bloque buyers es por cadena y total_upper_bound_30d es un límite superior declarado, no un conteo exacto: los compradores en diferentes cadenas o tokens no se deduplican (prefiere las cifras por cadena). En listed_services, el volumen del servicio es la cifra de 30 días sobre su mapeo de pagos y un servicio que comparte una dirección de pago se cuenta a nivel de dirección; all_time_count es null hasta que el precomputo por hora lo registre.

Parámetros de consulta

Parámetro	Tipo	Descripción
period	string	Ventana para el series diario: 30d (predeterminado) o all. all devuelve la serie de historial completo (coincide con el period=all de los servicios)
series_by	string	Forma del series: total (predeterminado, totales por día) o chain (por día, por red)

Respuesta de ejemplo (chains/settlers/listed_services/series truncados)

{
  "data": {
    "facilitator_id": "mrdn",
    "name": "Meridian",
    "website_url": "https://docs.mrdn.finance",
    "volume_usd_24h": 2331.97,
    "volume_usd_7d": 32219.96,
    "volume_usd_30d": 187217.82,
    "volume_usd_all": 1236223.48,
    "tx_count_24h": 113,
    "tx_count_7d": 1709,
    "tx_count_30d": 8315,
    "tx_count_all": 57941,
    "last_activity_at": "2026-07-06T00:00:00.000Z",
    "settler_count": 1,
    "verification": "on-chain",
    "avg_settlement_usd_all": 21.34,
    "avg_settlement_usd_30d": 22.51,
    "trend_7d_vs_prev_7d": 1.08,
    "buyers": {
      "by_chain": [
        {
          "network": "base",
          "network_caip2": "eip155:8453",
          "unique_buyers_30d": 214
        },
        {
          "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
          "network_caip2": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
          "unique_buyers_30d": 87
        }
      ],
      "total_upper_bound_30d": 301,
      "caveat": "Distinct buyers are counted per chain from the daily snapshots. A buyer active on more than one day is counted once per active day, and buyers on different chains or tokens are not de-duplicated, so total_upper_bound_30d is an upper bound, not an exact head count. Prefer the per-chain figures."
    },
    "chains": [
      {
        "network": "base",
        "network_caip2": "eip155:8453",
        "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "token_address_norm": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "asset_name": "USDC",
        "volume_usd_24h": 2331.97,
        "volume_usd_7d": 32219.96,
        "volume_usd_30d": 187217.82,
        "volume_usd_all": 1236223.48,
        "tx_count_all": 57941,
        "first_activity_at": "2026-05-02T00:00:00.000Z",
        "last_activity_at": "2026-07-06T00:00:00.000Z",
        "verification": "on-chain"
      }
    ],
    "settlers": [
      {
        "address": "0x2a9e8fa63c9d4e1b7a5c6f8d0e2b4a6c8d0f1a3b",
        "network": "base",
        "network_caip2": "eip155:8453",
        "source": "x402scan",
        "last_seen_at": "2026-07-06T00:00:00.000Z",
        "token_name": "USDC",
        "token_decimals": 6,
        "enabled": true
      }
    ],
    "listed_services": {
      "all_time_count": 7,
      "active_count_30d": 4,
      "top": [
        {
          "slug": "netintel",
          "name": "NetIntel",
          "status": "online",
          "volume_usd_30d": 842.15,
          "tx_count_30d": 210
        }
      ],
      "caveat": "Services listed in this directory that have settled on-chain via this facilitator. Volume is the service 30d figure over its payout mapping (a conservative floor, USDC via measured facilitators only); services that share a payout address are counted at the address level here. The all-time count is null until the hourly precompute records it."
    },
    "series": [
      {
        "date": "2026-07-05",
        "volume_usd": 6215.4,
        "tx_count": 288
      },
      {
        "date": "2026-07-06",
        "volume_usd": 5820.11,
        "tx_count": 265
      }
    ],
    "method": "Settlement volume is measured directly on-chain by settler-address attribution (USDC), never self-reported.",
    "caveat": "A measured floor, not an ecosystem total. Average USD per settlement is volume divided by settlement count over the window (null when there are no settlements), and the trend compares the last 7 days to the previous 7. The 24h figures are today so far in UTC, not a trailing 24 hours."
  }
}

POST /api/v1/submit

Envíe un nuevo servicio compatible con x402 para su revisión e inclusión en el directorio. Los endpoints se sondean automáticamente para verificar respuestas HTTP 402 válidas, y luego un humano revisa el envío antes de que se publique. Una URL de servicio en un host de cómputo gratuito (vercel.app, workers.dev, fly.dev y similares) no se rechaza: cuesta un pago único de $1 USDC (x402) en Base para entrar en la cola de revisión humana, y la tarifa no se reembolsa independientemente de lo que decida el revisor. Una URL de servicio en hosting de solo estática (github.io, gitlab.io, surge.sh) o en un túnel de desarrollo (ngrok, trycloudflare y similares) se rechaza con 400 a cualquier precio. Las URLs de sitios web nunca se cobran y solo se rechazan cuando son túneles de desarrollo. Cada dirección de correo electrónico puede enviar una vez cada 7 días (ver Límite de frecuencia más abajo), y los envíos que sigan pendientes después de la ventana de revisión de 7 días se rechazan automáticamente con una notificación por correo electrónico. El mismo endpoint también acepta envíos de facilitadores x402: consulte la siguiente sección.

Reenvío pagado después de un rechazo. Si el envío más reciente para el mismo correo electrónico o la misma URL de servicio fue rechazado hace menos de 14 días, reenviar no es gratuito: cuesta un pago único de $0.50 USDC (x402) en Base, una tarifa anti-spam que reemplaza el período de espera de 7 días (pague y vuelva a entrar inmediatamente). Una vez que hayan pasado 14 días desde el rechazo, reenviar vuelve a ser gratuito. Sin pago, el endpoint responde HTTP 402 con un encabezado PAYMENT-REQUIRED y un cuerpo accepts[]; pague con un cliente compatible con x402 y reintente la misma solicitud con un encabezado PAYMENT-SIGNATURE. En caso de éxito, el 201 lleva un encabezado PAYMENT-RESPONSE. Los envíos por primera vez, y los reenvíos cuyo envío más reciente sigue pendiente o aprobado, no se ven afectados.

Envío pagado desde hosting gratuito. Si la URL del servicio se ejecuta en una plataforma de cómputo gratuito, enviar cuesta un pago único de $1 USDC (x402) en Base. Se acumula con la tarifa de reenvío anterior: un reenvío desde un host de cómputo gratuito dentro de la ventana de 14 días es un pago único de $1.50. La tarifa compra un lugar en la cola de revisión humana y nada más: no la publicación, no prioridad, no una fecha límite de revisión. No se reembolsa si el envío es rechazado. Sin pago, el endpoint responde HTTP 402; pague accepts[0] con un cliente compatible con x402 y reintente con un encabezado PAYMENT-SIGNATURE. Cuando la capa de cobro está fuera de línea, el envío se rechaza con 400 en su lugar, como antes de que existiera esta tarifa.

Cuerpo de la solicitud (JSON, todos los campos obligatorios excepto notas)

Campo	Tipo	Descripción
url	string	URL base del servicio x402
email	string	Correo electrónico de contacto del remitente
service_name	string	Nombre legible del servicio (máx. 255 caracteres)
description	string	Breve descripción de lo que hace el servicio
website_url	string	URL pública del sitio web
category	string	Categoría del servicio (use /categories para valores válidos)
endpoints	string[]	Rutas de endpoints a sondear, máx. 50 (p. ej. ["/v1/generate"])
notes	string	Contexto adicional (opcional)

Ejemplo de solicitud

curl -X POST https://x402-list.com/api/v1/submit \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "email": "operator@example.com",
    "service_name": "Example x402 API",
    "description": "AI text generation via x402 micropayments",
    "website_url": "https://example.com",
    "category": "AI",
    "endpoints": ["/v1/generate", "/v1/classify"],
    "notes": "Optional context about the service"
  }'

Ejemplo de respuesta (201; probe_result es null si el sondeo agotó el tiempo)

{
  "data": {
    "submission_id": "7f0d2c5e-9a41-4b3a-8c67-2f51f0f8a915",
    "status": "pending",
    "probe_result": {
      "endpoints_found": 2,
      "errors": []
    }
  }
}

Respuesta de pago requerido (402; URL de servicio en host gratuito, reenvío recientemente rechazado, o ambos)

El encabezado de respuesta PAYMENT-REQUIRED lleva el mismo objeto x402 codificado en base64, sin el campo message a nivel de aplicación (que solo está en el cuerpo). Pague la única opción accepts[0] ($0.50, $1.00 o $1.50 USDC en Base: lea accepts[0].amount y resource.description) y reintente con un encabezado PAYMENT-SIGNATURE. El ejemplo a continuación es el caso de reenvío (error: "resubmission_fee_required"); un 402 de host gratuito lleva error: "free_host_fee_required" y difiere solo en el monto, la descripción y el mensaje.

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "amount": "500000",
      "payTo": "0x0000000000000000000000000000000000000000",
      "maxTimeoutSeconds": 300,
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ],
  "resource": {
    "url": "https://x402-list.com/api/v1/submit",
    "description": "Resubmission fee after a rejected submission",
    "mimeType": "application/json",
    "serviceName": "x402 List"
  },
  "error": "resubmission_fee_required",
  "message": "A submission from this email or for this URL was rejected less than 14 days ago, so resubmitting now requires a $0.50 x402 payment on Base (USDC). Pay with an x402-capable client by sending the request again with a PAYMENT-SIGNATURE header, or wait until 14 days have passed to resubmit for free. See https://x402-list.com/api for the flow."
}

POST /api/v1/submit (facilitador)

El mismo endpoint también acepta envíos de facilitadores x402 (operadores de infraestructura de liquidación, listados en /facilitators). Establezca "type": "facilitator" en el cuerpo para seleccionar esta variante; sin él, la solicitud se maneja como un envío de servicio. Los facilitadores no se sondean por HTTP: en su lugar, las cadenas EVM habilitadas entre las redes declaradas se escanean en busca de actividad reciente de liquidación de USDC en cadena originada por las direcciones de liquidación enviadas (ventana de 30 días, presupuesto total de 15 segundos). Solana y las cadenas fuera del registro medido se registran como afirmaciones declaradas y se verifican durante la revisión manual. Un sondeo fallido o inactivo nunca bloquea el envío: cada envío de facilitador es revisado por un humano antes de publicarse. Los facilitadores aprobados aparecen en GET /facilitators con verification: "listed" y cambian a "on-chain" automáticamente una vez que se mide el volumen de liquidación. Las URLs de sitios web en hosting gratuito o dominios de túnel de desarrollo se rechazan con 400, y el período de espera de 7 días por correo electrónico se rastrea por separado por tipo de envío (ver Límite de frecuencia más abajo).

Cuerpo de la solicitud (JSON; obligatorios: type, email, facilitator_name, website_url, settler_addresses, networks)

Campo	Tipo	Descripción
type	string	Debe ser facilitator para seleccionar esta variante
email	string	Correo electrónico de contacto del remitente
facilitator_name	string	Nombre legible del facilitador (máx. 255 caracteres)
website_url	string	URL pública del sitio web, en su propio dominio
settler_addresses	string[]	Direcciones en cadena que originan transacciones de liquidación, de 1 a 25: 0x EVM (40 caracteres hex) o base58 Solana (32-44 caracteres). También se acepta como una sola cadena separada por comas/saltos de línea
networks	string[]	Redes de liquidación declaradas, de 1 a 25 (p. ej. base, polygon, solana). Las cadenas EVM habilitadas se sondean en cadena; el resto permanecen como afirmaciones declaradas. También se acepta como una sola cadena separada por comas/saltos de línea
description	string	Qué hace el facilitador (opcional)
facilitator_id_slug	string	Slug de identificador propuesto: letras minúsculas, dígitos, guiones simples, máx. 100 caracteres (opcional)
token_claims	string[]	Tokens que el facilitador afirma liquidar, solo informativo (opcional)
claimed_volume_usd	string | number	Volumen de liquidación histórico autoinformado en USD, solo informativo: se contrasta con el sondeo en cadena en la revisión (opcional)
notes	string	Contexto adicional (opcional)

Ejemplo de solicitud

curl -X POST https://x402-list.com/api/v1/submit \
  -H "Content-Type: application/json" \
  -d '{
    "type": "facilitator",
    "email": "operator@examplepay.com",
    "facilitator_name": "ExamplePay",
    "website_url": "https://examplepay.com",
    "description": "x402 settlement facilitator for USDC on Base and Solana",
    "settler_addresses": [
      "0x7c5fa2ab8c9d01234e56f7a8b9c0d1e2f3a4b5c6",
      "4Nd1mYQZ7d5xUEhFcq8xJwzB3tYkTn5eGf2u1V9pQrSt"
    ],
    "networks": ["base", "solana"],
    "facilitator_id_slug": "examplepay",
    "token_claims": ["USDC"],
    "claimed_volume_usd": "125000",
    "notes": "Settling x402 payments since May 2026"
  }'

Ejemplo de respuesta (201; probe_result cubre solo las cadenas EVM habilitadas y es null si el sondeo no pudo ejecutarse)

{
  "data": {
    "submission_id": "3b8e1f42-6c9d-4e07-9a15-d824c0b7f691",
    "status": "pending",
    "probe_result": {
      "addresses_with_activity": [
        "0x7c5fa2ab8c9d01234e56f7a8b9c0d1e2f3a4b5c6"
      ],
      "tx_count": 1284,
      "errors": []
    }
  }
}

POST /api/v1/services/:slug/request-update

Los propietarios de un servicio listado pueden proponer cambios a los metadatos declarativos de su listado: nombre, descripción, URL del sitio web, categoría, correo electrónico de contacto, rutas de endpoints NUEVOS y URL base como un cambio de identidad siempre manual. Los datos medidos (estado verificado, tiempo de actividad, precios, pay_to) nunca se pueden sobrescribir a través de este canal: permanecen de solo lectura para todos. Un campo vacío u omitido siempre significa sin cambios, por lo que un cuerpo parcial nunca puede borrar o reescribir accidentalmente un campo. La propiedad se demuestra por solicitud con una prueba de dominio: la respuesta devuelve un token de un solo uso (mostrado una vez, solo se almacena su hash) que debe publicarse como su propia línea en {base_url origin}/.well-known/x402list.txt en el dominio listado ACTUAL, y luego confirmarse con verify-ownership a continuación dentro de 72 horas. Cada solicitud verificada es revisada por un humano antes de aplicar cualquier cosa, y nada sobre una solicitud pendiente se muestra públicamente. Una solicitud por correo electrónico por servicio cada 7 días (429 con Retry-After), contando solo solicitudes activas o aprobadas: una solicitud rechazada no mantiene la ventana, por lo que una corregida se puede enviar inmediatamente. Hay un formulario de navegador disponible en /services/:slug/update.

Cuerpo de la solicitud (JSON o codificado en formulario; obligatorio: email, más al menos un campo modificado)

Campo	Tipo	Descripción
email	string	Correo electrónico de contacto del solicitante (clave de período de espera junto con el servicio)
name	string	Nuevo nombre para mostrar (opcional; vacío = sin cambios)
description	string	Nueva descripción (opcional; vacío = sin cambios)
website_url	string	Nueva URL pública del sitio web, solo dominio propio (opcional)
category	string	Nueva categoría (use /categories para valores válidos) (opcional)
contact_email	string	Nuevo correo electrónico de contacto del listado (opcional)
base_url	string	Nueva URL base. Cambio de identidad: siempre revisado manualmente, el slug nunca cambia (opcional)
endpoints_add	string[]	NUEVOS endpoints para agregar y monitorear, máx. 50. Uno por entrada, como /v1/resource o POST /v1/resource: GET y POST son los métodos aceptados, y una entrada sin prefijo de método se toma como GET. Método y ruta juntos identifican un endpoint, por lo que POST /x es una adición nueva incluso cuando GET /x ya está listado; una entrada ya listada con el mismo método se ignora. También se acepta como una sola cadena separada por comas/saltos de línea (opcional)

Ejemplo de solicitud

curl -X POST https://x402-list.com/api/v1/services/example-x402-api/request-update \
  -H "Content-Type: application/json" \
  -d '{
    "email": "operator@example.com",
    "description": "AI text generation and classification via x402 micropayments",
    "endpoints_add": ["/v1/summarize", "POST /v1/chat/completions"]
  }'

Ejemplo de respuesta (201; el ownership_token se devuelve solo aquí, solo una vez, y aparece primero en el cuerpo)

{
  "data": {
    "request_id": "9c2f7b1e-4d3a-4f60-b2c8-51e9a0d47f36",
    "status": "pending_verification",
    "ownership_token": "x402list-verify-Ux3nT9qYw1Zb7kD4mR8sVfA2cH6jL0pEoI5gNyQtBw0",
    "proposed_changes": {
      "description": "AI text generation and classification via x402 micropayments",
      "endpoints_add": [
        {
          "method": "GET",
          "path": "/v1/summarize"
        },
        {
          "method": "POST",
          "path": "/v1/chat/completions"
        }
      ]
    },
    "well_known_url": "https://example.com/.well-known/x402list.txt",
    "well_known_path": "/.well-known/x402list.txt",
    "token_expires_at": "2026-07-09T14:00:00.000Z",
    "verify": {
      "method": "POST",
      "url": "/api/v1/services/example-x402-api/verify-ownership",
      "body": {
        "request_id": "9c2f7b1e-4d3a-4f60-b2c8-51e9a0d47f36"
      }
    },
    "reissue": {
      "method": "POST",
      "url": "/api/v1/services/example-x402-api/reissue-token",
      "body": {
        "request_id": "9c2f7b1e-4d3a-4f60-b2c8-51e9a0d47f36",
        "email": "[email protected]"
      }
    },
    "note": "Publish the ownership_token as a line of the well-known file on the service's CURRENT domain, then call verify. The token is shown only once and expires in 72 hours. Review is manual after verification. If you lose the token, call reissue once and the replacement arrives by email."
  }
}

POST /api/v1/services/:slug/reissue-token

El ownership_token se muestra exactamente una vez, en la respuesta request-update. Si se pierde, este endpoint pone en cola un reemplazo: publique el request_id junto con el mismo correo electrónico que creó la solicitud. El nuevo token se entrega solo por correo electrónico, a la dirección ya en la solicitud, y nunca aparece en esta respuesta. La respuesta es deliberadamente idéntica en todos los casos (solicitud encontrada o no, correo electrónico incorrecto, ya verificado, ya revisado, token expirado, reemisión ya en cola): si existe una solicitud de actualización pendiente no es información pública, y un endpoint que respondiera de manera diferente revelaría ese hecho, y con él una ruta a la prueba de propiedad. No hay GET por la misma razón. Una reemisión por solicitud de actualización: restaura el acceso a la prueba, no mantiene una solicitud viva indefinidamente. Si el token se pierde dos veces, envíe una nueva solicitud de actualización una vez que expire la actual: una solicitud pendiente cuyo token sigue vivo es exactamente lo que mantiene el período de espera de 7 días en ese correo electrónico y listado, por lo que una nueva solicitud antes de eso se rechaza. Una solicitud cuyo token ya expiró no mantiene nada, por lo que su reemplazo puede salir inmediatamente. Límite de frecuencia por IP más estricto que el presupuesto general de API.

Cuerpo de la solicitud (JSON o codificado en formulario; ambos campos obligatorios)

Campo	Tipo	Descripción
request_id	string	El request_id devuelto por request-update (UUID)
email	string	El correo electrónico utilizado para crear esa solicitud de actualización; el nuevo token va a él, nunca al llamante

Ejemplo de solicitud

curl -X POST https://x402-list.com/api/v1/services/example-x402-api/reissue-token \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "9c2f7b1e-4d3a-4f60-b2c8-51e9a0d47f36",
    "email": "operator@example.com"
  }'

Ejemplo de respuesta (200; el mismo cuerpo en todos los casos, y nunca el token en sí)

{
  "data": {
    "status": "accepted",
    "message": "If a pending update request exists for this service and email, a new ownership token is on its way to the address on record. The token is only ever sent by email, never in this response."
  }
}

POST /api/v1/services/:slug/verify-ownership

Paso 2 de una solicitud de actualización: después de publicar el token en el archivo well-known, llame a este endpoint con el request_id. El servidor vuelve a obtener {base_url origin}/.well-known/x402list.txt en el dominio listado ACTUAL (con la misma disciplina SSRF que el monitor: solo hosts públicos, redirecciones manuales, límite de cuerpo de 64KB, tiempo de espera de 10s) y compara el token con las líneas del archivo. En caso de éxito, el token se consume (de un solo uso) y, cuando el diff propuesto toca base_url o agrega endpoints, se ejecuta el sondeo HTTP 402 estándar para que el revisor vea datos frescos de probe_result; un sondeo fallido nunca bloquea la solicitud. La solicitud luego pasa a revisión manual y el solicitante recibe una notificación por correo electrónico del resultado. Errores: 400 cuando el archivo no se puede obtener o el token no está en él, 404 solicitud desconocida o servicio incorrecto, 409 ya revisado, 410 token expirado (envíe una nueva solicitud).

Ejemplo de solicitud

curl -X POST https://x402-list.com/api/v1/services/example-x402-api/verify-ownership \
  -H "Content-Type: application/json" \
  -d '{"request_id": "9c2f7b1e-4d3a-4f60-b2c8-51e9a0d47f36"}'

Ejemplo de respuesta (200; probe_result es null cuando el diff no toca la superficie de sondeo)

{
  "data": {
    "request_id": "9c2f7b1e-4d3a-4f60-b2c8-51e9a0d47f36",
    "status": "verified",
    "probe_result": {
      "endpoints_found": 1,
      "errors": []
    },
    "note": "Ownership verified. The request now goes to manual review; you will be notified by email."
  }
}

POST /api/v1/suggestions

Buzón de sugerencias de pago. Las disputas de listados y las exclusiones son gratuitas por correo electrónico ([email protected]). Este canal de pago es para comentarios generales sobre el directorio. Sugiere un cambio, una función, un error o una corrección de datos para el propio directorio x402 List, y paga por el canal de comentarios en x402. Cada sugerencia cuesta un pago único de $0.10 USDC (x402) en Base: la tarifa es la barrera anti-spam que demuestra compromiso, por lo que no hay reembolso. Las sugerencias son internas y revisadas por un humano; no se publican y no conllevan una hoja de ruta pública. Este endpoint está diseñado primero para agentes (JSON), y el flujo de pago es el protocolo de enlace x402 estándar: la primera llamada devuelve HTTP 402 con un encabezado PAYMENT-REQUIRED y un cuerpo accepts[] (opción única, $0.10 USDC en Base); paga con un cliente compatible con x402 y reintenta la misma solicitud con un encabezado PAYMENT-SIGNATURE. En caso de éxito, el 201 lleva un encabezado PAYMENT-RESPONSE.

Cuerpo de la solicitud (JSON; solo se requiere texto)

Campo	Tipo	Descripción
text	string	La sugerencia (de 1 a 2000 caracteres)
category	string	Uno de feature, bug, data, other (opcional, por defecto other)
email	string	Correo electrónico de contacto para recibir el resultado de la revisión (opcional)

Ejemplo de solicitud

curl -X POST https://x402-list.com/api/v1/suggestions \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: <base64 x402 payment payload>" \
  -d '{
    "text": "Add a /api/v1/services bulk export endpoint for offline indexing",
    "category": "feature",
    "email": "agent@example.com"
  }'

Ejemplo de respuesta (201; el encabezado PAYMENT-RESPONSE lleva el recibo de liquidación)

{
  "data": {
    "id": "b1e7c3a4-2f6d-4c8b-9a10-5e2f7d0c1a34",
    "status": "received"
  }
}

Respuesta de pago requerido (402; cuando no se envía PAYMENT-SIGNATURE)

El encabezado de respuesta PAYMENT-REQUIRED lleva el mismo objeto x402 codificado en base64, sin el campo message a nivel de aplicación (que solo está en el cuerpo). Paga la opción única accepts[0] ($0.10 USDC en Base) y reintenta con un encabezado PAYMENT-SIGNATURE. Cuando la capa de pago no está configurada, este endpoint responde HTTP 503 en su lugar.

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "amount": "100000",
      "payTo": "0x0000000000000000000000000000000000000000",
      "maxTimeoutSeconds": 300,
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ],
  "resource": {
    "url": "https://x402-list.com/api/v1/suggestions",
    "description": "Suggestion fee for x402 List directory feedback",
    "mimeType": "application/json",
    "serviceName": "x402 List"
  },
  "error": "suggestion_fee_required",
  "message": "Posting a suggestion to the x402 List directory requires a $0.10 x402 payment on Base (USDC). Pay with an x402-capable client: send the request again with a PAYMENT-SIGNATURE header. See https://x402-list.com/api for the flow."
}

POST /api/v1/assess

Evaluación de pago bajo demanda. Ejecuta una comparación nueva con un LLM insignia de una lista corta de servicios ya evaluados para tu necesidad declarada, y paga por ese razonamiento nuevo en x402. Nunca cobra por leer una evaluación ya calculada (eso sigue siendo gratuito en el detalle del servicio). Cada ejecución cuesta un pago único de $0.25 USDC (x402) en Base. El informe es un sobre modular: data lleva un bloque por módulo con precio (hoy la respuesta del asesor bajo data.answer), y meta lleva report_version y la lista modules_run, de modo que los módulos futuros son aditivos. El flujo de pago es el protocolo de enlace x402 estándar: la primera llamada devuelve HTTP 402 con un encabezado PAYMENT-REQUIRED y un cuerpo accepts[] (opción única, $0.25 USDC en Base); paga con un cliente compatible con x402 y reintenta la misma solicitud con un encabezado PAYMENT-SIGNATURE. En caso de éxito, el 200 lleva un encabezado PAYMENT-RESPONSE. Si no se puede producir la ejecución nueva, el endpoint responde HTTP 503 antes de liquidar, por lo que nunca se te cobra. No hay reembolso. Este endpoint está diseñado primero para agentes (solo JSON).

Cuerpo de la solicitud (JSON; ambos campos son obligatorios)

Campo	Tipo	Descripción
question	string	La necesidad contra la que evaluar la lista corta (de 1 a 1000 caracteres)
services	string[]	Slugs de servicios a comparar (de 1 a 8, sin duplicados)

Ejemplo de solicitud

curl -X POST https://x402-list.com/api/v1/assess \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: <base64 x402 payment payload>" \
  -d '{
    "question": "Which of these is the cheapest reliable weather API for a high-volume agent?",
    "services": ["weather-x402", "forecast-api", "meteo-402"]
  }'

Ejemplo de respuesta (200; el encabezado PAYMENT-RESPONSE lleva el recibo de liquidación)

{
  "data": {
    "answer": {
      "question": "Which of these is the cheapest reliable weather API for a high-volume agent?",
      "recommendation": {
        "value": "weather-x402 fits best: lowest price and highest measured uptime of the three.",
        "confidence": 0.72,
        "source": "ai"
      },
      "ranking": [
        {
          "slug": "weather-x402",
          "reason": "lowest price at $0.01 with 100% 24h uptime"
        },
        {
          "slug": "forecast-api",
          "reason": "comparable reliability but a higher price tier"
        }
      ],
      "model": "glm-5.2",
      "prompt_version": "f2-advisor-1",
      "candidates_considered": 3,
      "note": "AI-generated from the measured signals of the listed services. Not an endorsement; verify pricing and payTo before paying."
    }
  },
  "meta": {
    "report_version": 1,
    "modules_run": [
      "advisor"
    ]
  }
}

Respuesta de pago requerido (402; cuando no se envía PAYMENT-SIGNATURE)

El encabezado de respuesta PAYMENT-REQUIRED lleva el mismo objeto x402 codificado en base64. Paga la opción única accepts[0] ($0.25 USDC en Base) y reintenta con un encabezado PAYMENT-SIGNATURE. Cuando la capa de pago o la función de evaluación bajo demanda no está configurada, este endpoint responde HTTP 503 en su lugar.

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "amount": "250000",
      "payTo": "0x0000000000000000000000000000000000000000",
      "maxTimeoutSeconds": 300,
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ],
  "resource": {
    "url": "https://x402-list.com/api/v1/assess",
    "description": "On-demand x402 List assessment: a fresh AI comparison of the requested services for your need",
    "mimeType": "application/json",
    "serviceName": "x402 List"
  }
}

Sonda en vivo opcional

Opcionalmente incluye un objetivo probe { slug, endpoint_path? } en el cuerpo de la solicitud para probar también en vivo un servicio listado. Cuando la sonda en vivo está armada, después del razonamiento nuevo el servidor realiza un pago x402 real a ese endpoint y analiza lo que devuelve, y el monto único accepts[0] se convierte en $0.25 más el precio X de ese endpoint. El informe entonces lleva un bloque probe_report bajo data con un veredicto, una verificación determinista de conformidad de esquema y extractos truncados breves. Nunca contiene la respuesta de terceros verbatim. Las tarifas de la sonda son no reembolsables independientemente del resultado, y si el precio en vivo ha subido por encima de la cotización, la sonda no paga nada e informa price_drift. Las rutas de endpoint con plantilla (con marcadores de posición {param} o :param) no se pueden sondear en vivo y quedan excluidas de la sonda. Cuando la sonda en vivo no está armada, el objetivo de la sonda se ignora y la ejecución se mantiene solo con el asesor.

POST /api/v1/services/:slug/verify-live

Gana el nivel verificado. Así es como un listado pasa de payment-ready (el nivel base: responde a un desafío x402 válido y está en vivo) a verified (el nivel fuerte: x402 List pagó una llamada x402 real al endpoint y este entregó). En esta llamada, x402 List realiza un pago x402 real al endpoint más barato en USDC-en-Base del propio servicio y verifica que entregue; si se liquida en cadena y entrega, el servicio se vuelve verificado. El precio es una tarifa de manejo única de $0.25 USDC (x402) en Base más el precio propio X de ese endpoint, cotizado en el desafío antes de que se mueva cualquier dinero. La tarifa cubre el costo de la sonda, no la insignia. Una llamada que no entrega aún cuesta la tarifa y no gana nada, y no hay reembolso: la insignia no se puede comprar, solo se gana con una llamada que entregue. El nivel verificado no tiene vencimiento; solo se revoca si la dirección payTo del endpoint o el esquema de pago se desvían en el cable más adelante (un cambio de precio solo nunca lo revoca). Este endpoint es solo para agentes y API (los humanos no firman x402 en el navegador), y solo puede alcanzar endpoints con precio en USDC en Base en una ruta sin plantilla, por lo que un servicio con precio solo en otras redes permanece payment-ready y no puede ascender a verificado. Consulta metodología para el informe completo.

Ejemplo de solicitud

curl -X POST https://x402-list.com/api/v1/services/example-x402-api/verify-live \
  -H "PAYMENT-SIGNATURE: <base64 x402 payment payload>"

Respuesta de pago requerido (402; cuando no se envía PAYMENT-SIGNATURE)

La primera llamada devuelve HTTP 402 con un encabezado PAYMENT-REQUIRED y un cuerpo accepts[] cuya opción única es la cotización total ($0.25 más el precio X del endpoint, en USDC en Base). Págala y reintenta la misma solicitud con un encabezado PAYMENT-SIGNATURE. El pago se liquida primero y la sonda de entrega se ejecuta después de la liquidación, por lo que la tarifa se cobra independientemente de lo que devuelva la sonda; no hay reembolso si el endpoint no entrega. Cuando la capa de pago o la función de verificación de pago no está armada, este endpoint responde HTTP 503 en su lugar, antes de liquidar, por lo que nunca se te cobra.

GET /api/v1/openapi.json

Devuelve la especificación completa de OpenAPI 3.1 para esta API. Úsala para generar automáticamente bibliotecas de cliente o importarla en herramientas como Postman. La URL corta /openapi.json redirige con 301 aquí, así que recupérala con el seguimiento de redirecciones habilitado (curl -L).

Formato de respuesta

Todas las respuestas exitosas son un objeto JSON con una clave data que contiene el recurso solicitado (objeto o matriz). Los endpoints de listas agregan una clave meta con información de paginación como total, page, per_page y total_pages.

Las respuestas de error usan una clave error en su lugar. code es un número que refleja el estado HTTP:

{
  "error": {
    "code": 404,
    "message": "Service 'nonexistent-slug-xyz' not found"
  }
}

Códigos de estado HTTP

Código	Significado
200	Éxito
201	Creado (POST /submit)
400	Solicitud incorrecta / parámetros no válidos
402	Pago requerido: una solicitud medida más allá de la cuota diaria gratuita (ver Medición), o un endpoint de escritura de pago
404	Recurso no encontrado
410	Eliminado: endpoint retirado (p. ej. /api/v1/tags, reemplazado por /api/v1/categories)
429	Límite de velocidad superado, o período de enfriamiento de correo electrónico de POST /submit (ver más abajo)
500	Error interno del servidor

Medición

Las lecturas son gratuitas para agentes y consultas puntuales. La extracción masiva sostenida se mide: cada IP obtiene 2,000 solicitudes GET gratuitas por día (día UTC) en /api/v1/*. Los agentes que comparten una IP de salida (detrás del mismo NAT o grupo de serverless) comparten esta cuota. Más allá de esa cuota, cada solicitud adicional cuesta $0.01 USDC (x402) en Base, cobrado por solicitud. La cuota no se aplica a /api/v1/openapi.json, a los endpoints de escritura (POST /submit, POST /suggestions y las rutas de propiedad), ni a /api/admin/*.

Cada respuesta medida lleva un encabezado X-Meter-Remaining con las solicitudes gratuitas restantes hoy, y un encabezado X-Meter-Reset: la marca de tiempo Unix (en segundos) en la que se restablece esa cuota diaria, las próximas 00:00 UTC. Un llamador detrás de una IP de salida compartida puede leer el restablecimiento para saber cuándo se renueva la cuota por IP en lugar de solo ver un recuento restante bajo. Una vez que la cuota se agota, la API responde a las solicitudes medidas con HTTP 402: paga accepts[0] ($0.01 USDC en Base) con un cliente compatible con x402 y reintenta la misma solicitud con un encabezado PAYMENT-SIGNATURE; la respuesta exitosa entonces lleva un encabezado PAYMENT-RESPONSE. El encabezado de respuesta PAYMENT-REQUIRED lleva el mismo objeto PaymentRequired de x402 codificado en base64, sin el campo de mensaje a nivel de aplicación (que solo está en el cuerpo).

Ejemplo de encabezado de respuesta

X-Meter-Remaining: 1913
X-Meter-Reset: 1767225600

Ejemplo de 402 (por encima de la cuota diaria gratuita)

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "amount": "10000",
      "payTo": "0x0000000000000000000000000000000000000000",
      "maxTimeoutSeconds": 300,
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ],
  "resource": {
    "url": "/api/v1/services",
    "description": "x402 List API metered access (per request beyond the free daily quota)",
    "mimeType": "application/json",
    "serviceName": "x402 List"
  },
  "error": "metering_fee_required",
  "message": "This request is beyond the free daily quota (2,000 requests/day per IP). Each additional request costs $0.01 USDC (x402) on Base. Pay with an x402-capable client and retry the same request with a PAYMENT-SIGNATURE header. See https://x402-list.com/api for the flow."
}

Límite de velocidad

Todos los endpoints tienen un límite de velocidad de 200 solicitudes por minuto por dirección IP (ventana deslizante, se restablece cada minuto). Por encima de 100 solicitudes/min, la respuesta incluye X-RateLimit-Throttled: true como señal informativa: las solicitudes aún tienen éxito. Por encima de 200 solicitudes/min, la API devuelve 429 Too Many Requests con un encabezado Retry-After que indica los segundos hasta que se restablezca la ventana.

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1783339200
X-RateLimit-Throttled: true   # only when count > 100

POST /submit además aplica un período de enfriamiento de 7 días por correo electrónico del remitente, rastreado por separado por tipo de envío: un segundo envío del mismo tipo (servicio o facilitador) desde el mismo correo electrónico dentro de 7 días devuelve 429 con Retry-After establecido en los segundos restantes hasta que termine el período de enfriamiento (hasta 7 días, no la ventana por minuto). Un envío de servicio no bloquea un envío de facilitador desde el mismo correo electrónico, y viceversa. Los envíos de cualquier tipo que aún estén pendientes después de la ventana de revisión de 7 días se rechazan automáticamente, con una notificación por correo electrónico, para que la dirección pueda enviar de nuevo.

Licencia de datos y atribución

Los datos del directorio que esta API y los feeds devuelven (listados de servicios, tiempo de actividad, precios, cifras de liquidación en cadena y eventos de cambio) se publican bajo la licencia Creative Commons Attribution 4.0 (CC BY 4.0). El documento de especificación de OpenAPI en sí permanece bajo MIT; CC BY 4.0 cubre los datos. Eres libre de reutilizar, redistribuir y construir sobre ellos, incluso con fines comerciales.

La atribución significa acreditar a x402-list.com como fuente, con un enlace donde el medio lo permita. Una línea de crédito lista para usar se incluye en cada respuesta, por lo que no tienes que componer la tuya propia.

Cada respuesta JSON 2xx lleva un único objeto provenance de nivel superior (una vez por respuesta, nunca por elemento) junto a data y meta. Indica el license, si se requiere atribución, una cadena attribution lista para usar, una URL canónica cite_as para el recurso específico y el origen source. Las respuestas de la API también envían un encabezado Link: <https://creativecommons.org/licenses/by/4.0/>; rel="license".

{
  "license": "CC-BY-4.0",
  "attribution_required": true,
  "attribution": "Data: x402-list.com (CC BY 4.0)",
  "cite_as": "https://x402-list.com/services/acme-generate",
  "source": "https://x402-list.com"
}