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

# XHuoAPI x402 Guia de Integração de Pagamento

> x402 集成指南 - XHuoAPI

x402 é um protocolo de pagamento em blockchain baseado no padrão HTTP 402 Payment Required, que permite que o chamador complete a liquidação em blockchain ao iniciar uma solicitação de API, sendo muito adequado para cenários de cobrança por chamada entre programas automatizados, Agentes de IA e microsserviços. Através deste guia, você pode programaticamente realizar o pagamento de pedidos da XHuoAPI em seu próprio sistema, proporcionando uma experiência de "solicitação é pagamento".

Referências de documentação oficial:

* Documento de visão geral do x402: [https://docs.cdp.coinbase.com/x402/docs/overview](https://docs.cdp.coinbase.com/x402/docs/overview)
* Exemplo de código aberto do x402: [https://github.com/coinbase/x402](https://github.com/coinbase/x402)

Este documento é destinado a desenvolvedores que precisam integrar a capacidade de pagamento x402 da plataforma XHuoAPI em seus negócios, apresentando o fluxo completo desde a preparação do ambiente até a conclusão da chamada de pagamento, e fornecendo exemplos de código em Axios, Fetch, Python requests e httpx. Pontos principais:

* O link de pagamento é concluído na **rede principal Base**, utilizando **USDC** como ativo;
* É necessário usar a **chave privada EVM** da carteira que possui os ativos para gerar o cabeçalho de assinatura `X-PAYMENT`;
* Todas as APIs estão localizadas sob o domínio `https://api.xhuoapi.ai`, e o cabeçalho `Authorization` deve incluir o **Token da Plataforma**.

***

## I. Preparativos

### 1. Verificar o pedido e registrar as informações de recebimento

Faça login no console [https://api.xhuoapi.ai](https://api.xhuoapi.ai), na lista de pedidos ou na página de detalhes do pedido você pode ver o pedido que precisa ser pago. Os detalhes do pedido mostrarão:

* ID do pedido (por exemplo, `7744945e-5e77-4dcc-a9c4-528692d17b34`);
* Endereço de recebimento `pay_to` (também será retornado na resposta 402, recomenda-se considerar as informações da página como referência).

Por favor, registre o ID do pedido e confirme o endereço `pay_to`, pois será necessário garantir que os fundos sejam enviados para esse endereço durante a assinatura.

### 2. Preparar a carteira de pagamento e os fundos

* Prepare uma carteira EVM que suporte a rede principal Base e exporte a chave privada a ser utilizada;
* Carregue a rede principal Base com a quantidade suficiente de **USDC** (o valor do pagamento deve ser em unidades mínimas com 6 casas decimais);
* O Facilitador x402 pagará as taxas de rede, a carteira de pagamento só precisa manter USDC suficiente;
* A chave privada é usada apenas para assinatura local, mantenha-a em segurança e evite expô-la em navegadores ou ambientes não confiáveis.

### 3. Criar Token da Plataforma

O Token da Plataforma é usado para chamar a API da plataforma, semelhante à funcionalidade do Token de usuário usado no navegador após o login, mas não expira. Siga os passos abaixo para criar:

1. Abra a página do console [https://api.xhuoapi.ai/console/platform-tokens](https://api.xhuoapi.ai/console/platform-tokens);
2. Clique em "Criar Token", preencha as informações de anotação conforme solicitado e gere;
3. Copie o Token gerado (por exemplo, `platform-v1-xxxx`) e guarde-o como `platform_token`.

![platform-token](https://cdn.xhuoapi.ai/6g86oz.png)

Todos os cabeçalhos de chamadas de API subsequentes devem incluir:

```
Authorization: Bearer {platform_token}
```

### 4. Solicitar informações básicas

* Domínio base da API: `https://api.xhuoapi.ai`
* Caminho da solicitação de pagamento: `/api/v1/orders/{order_id}/pay/`
* Solicitações e respostas usam JSON, codificado em UTF-8.

***

## II. Visão Geral do Fluxo de Pagamento

1. **Iniciar solicitação de pagamento**: primeira solicitação `POST` sem o cabeçalho `X-PAYMENT`, acionando a plataforma a retornar 402 Payment Required;
2. **Ler requisitos de pagamento**: analisar o array `accepts` na resposta 402, confirmando que `network` é `base`, `asset` é USDC, e `payTo` é consistente com a página do pedido;
3. **Gerar `X-PAYMENT`**: usar a chave privada da carteira de pagamento, os requisitos do corpo da resposta, e as informações do domínio EIP-712 retornadas pelo Facilitador para gerar a assinatura (geralmente com a ajuda do SDK oficial);
4. **Repetir com a assinatura**: adicionar o cabeçalho `X-PAYMENT` à solicitação do mesmo caminho, e a plataforma retornará 200 após a validação bem-sucedida;
5. **Analisar resultados**: ler o cabeçalho de resposta `X-PAYMENT-RESPONSE`, onde é possível obter o hash da transação em blockchain, o valor efetivamente debitado, entre outras informações para conciliação.

***

## III. Exemplos de Integração

### 1. Primeira solicitação (aciona 402)

```http theme={null}
POST https://api.xhuoapi.ai/api/v1/orders/{order_id}/pay/
Authorization: Bearer {platform_token}
Content-Type: application/json

{
  "pay_way": "X402"
}
```

Resposta típica 402 (a ordem dos campos pode variar ligeiramente):

```json theme={null}
{
  "error": "Pagamento necessário para este pedido.",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54b268aa0e",
      "maxAmountRequired": "1250000",
      "payTo": "0x302afdd980aaefca3afa8df7222a6002774f6724",
      "extra": {
        "eip712": { "...": "..." }
      }
    }
  ],
  "paywall": { ... }
}
```

Descrição dos campos-chave:

* `network`: deve ser `base` (rede principal Base);
* `asset`: endereço do contrato USDC na Base (exemplo do contrato oficial da rede principal);
* `maxAmountRequired`: unidade atômica de USDC necessária para este pagamento (1 USDC = 1.000.000 unidades atômicas);
* `payTo`: endereço de recebimento da plataforma, deve ser consistente com a página de detalhes do pedido;
* `extra`: informações do domínio EIP-712 necessárias para a assinatura, etc.

### 2. Gerar `X-PAYMENT`

A prática comum é usar o SDK oficial (como `x402-js`, `x402-fetch`, `x402.clients`, etc.):

1. Converter a chave privada da carteira de pagamento em um objeto de conta;
2. Registrar os dados `accepts` da resposta 402, escolhendo a opção de pagamento onde `network == "base"`;
3. Chamar a função de assinatura fornecida pelo SDK para gerar a string `X-PAYMENT` codificada em Base64 (não é necessário conectar diretamente ao facilitador; o backend da plataforma será responsável por chamar o facilitador para concluir a verificação/liquidação);
4. Recomenda-se verificar se `maxAmountRequired` está dentro do intervalo aceitável, caso contrário, alertar o usuário para recarregar.

Se precisar implementar manualmente, consulte a documentação oficial do x402 e construa a estrutura EIP-712 conforme as informações do domínio `extra.eip712` antes de assinar.

### 3. Repetir com a assinatura

```http theme={null}
POST https://api.xhuoapi.ai/api/v1/orders/{order_id}/pay/
Authorization: Bearer {platform_token}
Content-Type: application/json
X-PAYMENT: {base64_signed_payload}

{
  "pay_way": "X402"
}
```

Se o pagamento for bem-sucedido, o status da resposta será 200, e o corpo da resposta retornará as informações atualizadas do pedido, incluindo:

```
X-PAYMENT-RESPONSE: eyJ0cmFuc2FjdGlvbiI6IjB4...==
```

`X-PAYMENT-RESPONSE` pode ser decodificado usando a função de decodificação do SDK para obter o hash da transação em blockchain, a rede de pagamento, o endereço do pagador e outros dados, para fins de contabilização ou exibição.

***

## IV. Exemplos de Código em Múltiplas Linguagens

Os exemplos a seguir assumem que as variáveis de ambiente ou arquivos de configuração são injetados:

* `ACE_PLATFORM_TOKEN`：Token da Plataforma；
* `ACE_X402_ORDER_ID`：ID do Pedido；
* `ACE_X402_PRIVATE_KEY`：Chave privada da carteira de pagamento (com prefixo `0x`).

### 1. Axios（TypeScript）

```ts theme={null}
import axios from "axios";
import { Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { buildPaymentHeader, decodePaymentResponse } from "x402-js";

const baseURL = "https://api.xhuoapi.ai";
const orderId = process.env.ACE_X402_ORDER_ID!;
const platformToken = process.env.ACE_PLATFORM_TOKEN!;
const privateKey = process.env.ACE_X402_PRIVATE_KEY as Hex;

const account = privateKeyToAccount(privateKey);
const api = axios.create({
  baseURL,
  headers: {
    Authorization: `Bearer ${platformToken}`,
    "Content-Type": "application/json",
  },
});

async function payOrder() {
  const payPath = `/api/v1/orders/${orderId}/pay/`;

  const initial = await api.post(
    payPath,
    { pay_way: "X402" },
    { validateStatus: () => true }
  );
  if (initial.status !== 402) {
    throw new Error(`status inesperado ${initial.status}`);
  }

  const requirement = initial.data.accepts.find(
    (item: any) => item.network === "base"
  );
  if (!requirement) {
    throw new Error("nenhum requisito base retornado");
  }

  const paymentHeader = await buildPaymentHeader({
    account,
    requirement,
  });

  const final = await api.post(
    payPath,
    { pay_way: "X402" },
    { headers: { "X-PAYMENT": paymentHeader } }
  );

  if (final.status >= 400) {
    throw new Error(`pagamento x402 falhou: ${final.status} ${final.statusText}`);
  }
  const receipt = decodePaymentResponse(final.headers["x-payment-response"]);
  console.log("recibo x402", receipt);
}

payOrder().catch(console.error);
```

### 2. Fetch（JavaScript）

```ts theme={null}
import { wrapFetchWithPayment, decodePaymentResponse } from "x402-fetch";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.ACE_X402_PRIVATE_KEY!);
const platformToken = process.env.ACE_PLATFORM_TOKEN!;
const orderId = process.env.ACE_X402_ORDER_ID!;
const fetchWithPayment = wrapFetchWithPayment(fetch, account);

async function payOrder() {
  const url = `https://api.xhuoapi.ai/api/v1/orders/${orderId}/pay/`;

  const response = await fetchWithPayment(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${platformToken}`,
    },
    body: JSON.stringify({ pay_way: "X402" }),
  });

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`pagamento x402 falhou: ${response.status} ${errorBody}`);
  }

  const receipt = decodePaymentResponse(
    response.headers.get("x-payment-response")!
  );
  console.log("recibo x402", receipt);
}

payOrder().catch(console.error);
```

### 3. Python requests

```python theme={null}
import os
from eth_account import Account
from x402.clients.requests import x402_requests
from x402.clients.base import decode_x_payment_response

order_id = os.environ["ACE_X402_ORDER_ID"]
platform_token = os.environ["ACE_PLATFORM_TOKEN"]
account = Account.from_key(os.environ["ACE_X402_PRIVATE_KEY"])

session = x402_requests(
    account,
    payment_requirements_selector=lambda accepts, **_: next(
        req for req in accepts if req.network == "base" and req.scheme == "exact"
    ),
)

response = session.post(
    f"https://api.xhuoapi.ai/api/v1/orders/{order_id}/pay/",
    json={"pay_way": "X402"},
    headers={"Authorization": f"Bearer {platform_token}"},
)

response.raise_for_status()
receipt_header = response.headers.get("X-PAYMENT-RESPONSE")
if receipt_header:
    print("recibo x402:", decode_x_payment_response(receipt_header))
```

### 4. Python httpx（assíncrono）

```python theme={null}
import asyncio
import os
from eth_account import Account
from x402.clients.httpx import x402HttpxClient
from x402.clients.base import decode_x_payment_response

async def pay_order() -> None:
    order_id = os.environ["ACE_X402_ORDER_ID"]
    platform_token = os.environ["ACE_PLATFORM_TOKEN"]
    account = Account.from_key(os.environ["ACE_X402_PRIVATE_KEY"])

    async with x402HttpxClient(
        account=account,
        base_url="https://api.xhuoapi.ai",
        headers={"Authorization": f"Bearer {platform_token}"},
        payment_requirements_selector=lambda accepts, **_: next(
            req for req in accepts if req.network == "base"
        ),
    ) as client:
        response = await client.post(
            f"/api/v1/orders/{order_id}/pay/",
            json={"pay_way": "X402"},
        )
        response.raise_for_status()
        receipt_header = response.headers.get("X-PAYMENT-RESPONSE")
        if receipt_header:
            print("recibo x402:", decode_x_payment_response(receipt_header))

asyncio.run(pay_order())
```

> O exemplo apenas demonstra chamadas-chave, em ambiente de produção, por favor, adicione tratamento de exceções, estratégias de repetição, logs e controles de segurança.

***

## Cinco, Verificação após o pagamento bem-sucedido

* **Verificação no console**: Acesse a página de detalhes do pedido `https://api.xhuoapi.ai/console/orders/{order_id}`, se a página mostrar "Pagamento bem-sucedido" ou o status do pedido tiver mudado para pago/concluído, isso significa que a liquidação na blockchain foi concluída.
* **Verificação da API**: Chame `GET https://api.xhuoapi.ai/api/v1/orders/{order_id}/` e inclua `Authorization: Bearer {platform_token}`, verifique o campo `state` na resposta ( `PAID` ou `FINISHED` indica pagamento bem-sucedido).
* **Cabeçalho de retorno**: Leia `X-PAYMENT-RESPONSE` na resposta de pagamento bem-sucedido, pode-se decodificar o hash da transação na blockchain como o comprovante final; recomenda-se salvar essa informação nos logs do sistema para conciliação.

***

## Seis, Resolução de Problemas Comuns

* **Ainda retorna 402**: Confirme se o endereço de pagamento possui USDC suficiente na rede Base, verifique se `maxAmountRequired` excede o saldo da carteira ou limite personalizado.
* **Falha na assinatura**: Certifique-se de que a chave privada tenha o prefixo `0x`; ao assinar, use estritamente o `extra` (domínio EIP-712) e `payTo` da resposta, não altere a ordem dos campos.
* **Rede não correspondente**: Pode haver múltiplos requisitos em `accepts`, escolha a opção `network === "base"`.
* **Falta de `X-PAYMENT-RESPONSE`**: Indica que o pagamento não foi realmente debitado, pode-se reiniciar com base no erro no corpo da resposta; se houver congestionamento na blockchain, tente novamente mais tarde.
* **Token da plataforma inválido**: Confirme se o Token não foi excluído e começa com o prefixo `platform-v1-`; se a interface retornar 401, pode-se regenerar no console.

***

## Sete, Mais Ajuda

* Documentação online e perguntas frequentes: Navegação "Documentação" no topo do console da plataforma.
* Envio de tickets e suporte ao cliente: [https://api.xhuoapi.ai/support](https://api.xhuoapi.ai/support)
* Comunidade: Discord [https://discord.gg/f9GRuKCmRc](https://discord.gg/f9GRuKCmRc), X (Twitter) [https://x.com/XHuoAPI](https://x.com/XHuoAPI)
* Outros canais: E-mail `office@xhuoapi.ai`, `office@germey.tech`; endereço da empresa 651 N Broad St, Suite 201, Middletown, Delaware, EUA; para suporte via WeChat, consulte o código QR mais recente na página de suporte.
* Feedback e sugestões: Sinta-se à vontade para nos informar sobre necessidades de melhoria através de qualquer um dos canais acima.