> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Guía de Integración X402

> Platform API guide - Ace Data Cloud

X402 es un protocolo de pago en cadena basado en HTTP `402 Payment Required`. A través de las capacidades X402 de Ace Data Cloud, el llamador puede realizar pagos en cadena directamente con USDC en cada solicitud API sin necesidad de crear un token API o recargar el saldo de la cuenta.

Este conjunto de documentos está organizado en el orden de integración real: primero ejecutar una solicitud mínima, luego integrar el SDK, y después entender la red, los planes de facturación, el pago de pedidos y el Facilitador. Se recomienda leer la tabla a continuación de arriba hacia abajo.

| Tutorial | Escenario aplicable | Enlace |
| - | - | - |
| Inicio rápido | Primero entender el proceso de 402, `accepts` y `PAYMENT-SIGNATURE` con una solicitud mínima | [Inicio rápido X402](https://platform.acedata.cloud/documents/x402-quickstart) |
| SDK TypeScript | Llamar a la API de Ace Data Cloud en navegadores, Node.js o aplicaciones frontales | [Integración SDK TypeScript](https://platform.acedata.cloud/documents/x402-typescript-sdk) |
| SDK Python | Llamar a la API en servicios Python, scripts, Agentes o tuberías de datos | [Integración SDK Python](https://platform.acedata.cloud/documents/x402-python-sdk) |
| Pago de pedidos | Pagar pedidos en la consola de Ace Data Cloud con X402 | [Tutorial de pago de pedidos](https://platform.acedata.cloud/documents/x402-order-payment) |
| Redes y métodos de pago | Entender los activos, firmas y escenarios aplicables de Base, SKALE y Solana | [Redes y métodos de pago](https://platform.acedata.cloud/documents/x402-networks) |
| `exact` y `upto` | Diferenciar entre API de precio fijo y API de liquidación posterior a uso | [Descripción del plan de facturación](https://platform.acedata.cloud/documents/x402-metered-upto) |
| Descripción de precios | Entender la relación entre los precios de X402 y el precio unitario de Créditos, así como los precios reales de cada servicio | [Descripción de precios X402](https://platform.acedata.cloud/documents/x402-pricing) |
| Facilitador | Entender la relación entre `verify`, `settle` y la API de cobro autoconstruida en el servidor | [Integración Facilitador](https://platform.acedata.cloud/documents/x402-facilitator) |
| E2E y solución de problemas | Verificar entradas públicas, ejecutar herramientas de validación avanzadas, localizar problemas comunes de 402, firma y liquidación | [Validación E2E y solución de problemas](https://platform.acedata.cloud/documents/x402-e2e-troubleshooting) |

## Ruta de integración recomendada

Si solo deseas llamar a la API de Ace Data Cloud, utiliza primero el SDK oficial:

* TypeScript: `@acedatacloud/sdk` + `@acedatacloud/x402-client`
* Python: `acedatacloud` + `acedatacloud-x402`

Direcciones de código abierto y paquetes:

| Proyecto | Dirección |
| - | - |
| SDK Ace Data Cloud | [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK) |
| Cliente X402 | [https://github.com/AceDataCloud/X402Client](https://github.com/AceDataCloud/X402Client) |
| Facilitador X402 | [https://github.com/AceDataCloud/FacilitatorX402](https://github.com/AceDataCloud/FacilitatorX402) |
| SDK npm | [https://www.npmjs.com/package/@acedatacloud/sdk](https://www.npmjs.com/package/@acedatacloud/sdk) |
| Cliente X402 npm | [https://www.npmjs.com/package/@acedatacloud/x402-client](https://www.npmjs.com/package/@acedatacloud/x402-client) |
| SDK PyPI | [https://pypi.org/project/acedatacloud/](https://pypi.org/project/acedatacloud/) |
| Cliente X402 PyPI | [https://pypi.org/project/acedatacloud-x402/](https://pypi.org/project/acedatacloud-x402/) |

El SDK completará automáticamente la primera solicitud sin autenticación, analizará `402 Payment Required`, llamará al manejador de pagos y reintentará estos pasos con `PAYMENT-SIGNATURE`. Solo necesitas preparar una billetera con USDC y elegir la red que deseas utilizar.

Si deseas que tu API también soporte pagos X402, necesitarás leer la documentación del Facilitador y entender la relación entre `paymentRequirements`, `paymentPayload`, `/verify` y `/settle`.

## Estado de soporte

Ace Data Cloud X402 ha completado la validación en la API pública, el SDK oficial, el Facilitador y la ruta de liquidación en cadena. La siguiente tabla resume el estado actual según las capacidades más utilizadas por los desarrolladores al integrarse.

| Capacidad | Estado | Descripción |
| - | - | - |
| Capacidades del Facilitador | Disponible | `https://facilitator.acedata.cloud/.well-known/x402` devuelve la red de pago y los puntos finales del protocolo. |
| API 402 `accepts` | Disponible | Las solicitudes no pagadas devolverán los requisitos de pago disponibles para Base, SKALE y Solana. |
| SDK TypeScript | Disponible | `@acedatacloud/sdk` y `@acedatacloud/x402-client` pueden manejar automáticamente 402, firmas y reintentos. |
| SDK Python | Disponible | `acedatacloud` y `acedatacloud-x402` pueden manejar automáticamente 402, firmas y reintentos. |
| Base `exact` | Validado en cadena | Adecuado para API de monto fijo y pago de pedidos. |
| Base `upto` | Validado en cadena | Adecuado para API de medición posterior como autocompletado de chat, actualmente la única red que ofrece `upto`. |
| SKALE `exact` | Validado en cadena | Adecuado para escenarios de pago EVM de bajo costo de gas. |
| Solana `exact` | HTTP paid retry validado | API de reintento pagado validada con respuesta del modelo; se recomienda usar reconciliación de RPC de Solana propia. |
| Pago de pedidos | Validado en cadena | El pago de pedidos Base `exact` ha completado la liquidación en cadena y actualizado el estado del pedido. |

La siguiente salida es solo para ilustrar la forma de retorno de las rutas validadas. Al integrarse, siempre consulta el `accepts` devuelto por la API actual.

```text theme={null}
packages
@acedatacloud/sdk@2026.504.2 import ok
@acedatacloud/x402-client@2026.531.3 import ok
acedatacloud==2026.4.26.1 import ok
acedatacloud-x402==2026.5.31.3 import ok

API 402
status 402
accepts eip155:8453/exact, eip155:8453/upto, solana:5eykt4.../exact, eip155:1187947933/exact

TypeScript SDK
content ADC_TS_SDK_X402_OK

Python SDK
content ADC_PY_SDK_X402_OK

Base exact
content ADC_BASE_E2E_OK
tx 0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3
explorer https://basescan.org/tx/0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3

SKALE exact
content ADC_SKALE_E2E_OK
tx 0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f
explorer https://skale-base-explorer.skalenodes.com/tx/0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f

Base upto
content ADC_BASE_UPTO_OK
tx 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
explorer https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
signed ceiling 95215 atomic USDC
transfer value 3 atomic USDC

Solana exact
HTTP 402 -> HTTP 200
content ADC_SOLANA_E2E_OK
chain signature not confirmed in this run

Order payment
order 78481793-304e-47f7-bc0c-8231aec9cc1e state Finished pay_way X402
tx 0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
explorer https://basescan.org/tx/0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
```

Instrucciones:

* Los paquetes de npm y PyPI se han instalado e importado correctamente en un entorno limpio.
* La solicitud de API no pagada devuelve 402, `accepts` incluye los métodos de pago disponibles para Base, SKALE y Solana.
* `accepts[].network` es la identificación CAIP-2, el cliente debe coincidir con la cadena CAIP-2 al seleccionar la red.
* Tanto el SDK de TypeScript como el SDK de Python pueden manejar automáticamente el 402 y completar el reintento pagado.
* Base `exact`, SKALE `exact`, Base `upto` y el pago del pedido tienen direcciones de explorador que se pueden abrir públicamente.
* El límite de firma de Base `upto` es de `95215` USDC atómicos, el asentamiento real es de `3` USDC atómicos, lo que refleja la característica de liquidación por medición posterior según el uso real.
* Solana `exact` ha verificado HTTP 402 -> HTTP 200 y la salida del modelo. Dado que la consulta RPC pública puede estar limitada, se recomienda utilizar RPC de Solana propio o registros de liquidación del lado de la plataforma para confirmar la firma de la transacción.

## Consideraciones para la integración

Al integrar, los desarrolladores deben centrarse en los requisitos de pago en tiempo real devueltos por la solicitud actual, en lugar de copiar los montos o direcciones de ejemplo en la documentación:

* `accepts[].maxAmountRequired` es el monto máximo que se puede firmar en la solicitud actual.
* `accepts[].asset` es el contrato o mint de USDC que se utilizará en esta solicitud.
* `accepts[].extra.chainId`, `accepts[].extra.facilitatorAddress` y `accepts[].extra.verifyingContract` participarán en la firma de datos tipados de EVM.
* `upto` requiere que la billetera autorice primero el USDC de la cadena objetivo con Permit2; si no está autorizado, devolverá `PERMIT2_ALLOWANCE_REQUIRED`.
* Si se desea explícitamente utilizar la medición posterior, se debe pasar `preferScheme: 'upto'` en el SDK de TypeScript; de lo contrario, el SDK elegirá el primer requisito disponible devuelto por el servidor en esa red.

## Rango de verificación pública

Antes de la integración, se pueden verificar estos puntos de entrada públicos y el comportamiento del SDK:

* Las solicitudes de API sin `Authorization` o `PAYMENT-SIGNATURE` devolverán `402 Payment Required`, y `accepts` en la respuesta es la única base de firma para esta solicitud.
* Tanto el SDK de TypeScript como el SDK de Python proporcionan un controlador de pago; la capa de transporte del SDK llamará al controlador y reintentará una vez al recibir 402.
* `https://facilitator.acedata.cloud/.well-known/x402`: devuelve las redes, esquemas y puntos finales de protocolo admitidos por el Facilitador; el precio de la API seguirá siendo el 402 devuelto en tiempo real por la solicitud objetivo.
* `https://facilitator.acedata.cloud/supported`: devuelve las redes y esquemas admitidos por el Facilitador.
* El repositorio de X402Client incluye herramientas avanzadas de verificación en cadena que se pueden utilizar para confirmar firmas, reintentos y comportamientos de liquidación; la salida de la herramienta no reemplaza la `accepts` devuelta por la API en línea.

`upto` pertenece a la liquidación por medición posterior, adecuada para API donde el uso real, como la finalización de chat o la llamada de modelo, solo se conoce después de la respuesta. Actualmente, solo Base ofrece `upto`; si la verificación de la firma falla, verifique si el id de la cadena, la dirección del facilitador, el gastador, el contrato de USDC y la asignación de Permit2 coinciden con la respuesta 402.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.