AceDataCloud x402 Guia de Integração de Pagamento

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 AceDataCloud 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
Exemplo de código aberto do x402: https://github.com/coinbase/x402

Este documento é destinado a desenvolvedores que precisam integrar a capacidade de pagamento x402 da plataforma AceDataCloud 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://platform.acedata.cloud, 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://platform.acedata.cloud, 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:

Abra a página do console https://platform.acedata.cloud/console/platform-tokens;
Clique em “Criar Token”, preencha as informações de anotação conforme solicitado e gere;
Copie o Token gerado (por exemplo, platform-v1-xxxx) e guarde-o como platform_token.

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://platform.acedata.cloud
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

Iniciar solicitação de pagamento: primeira solicitação POST sem o cabeçalho X-PAYMENT, acionando a plataforma a retornar 402 Payment Required;
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;
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);
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;
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)

POST https://platform.acedata.cloud/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):

{
  "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.):

Converter a chave privada da carteira de pagamento em um objeto de conta;
Registrar os dados accepts da resposta 402, escolhendo a opção de pagamento onde network == "base";
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);
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

POST https://platform.acedata.cloud/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）

import axios from "axios";
import { Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { buildPaymentHeader, decodePaymentResponse } from "x402-js";

const baseURL = "https://platform.acedata.cloud";
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）

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://platform.acedata.cloud/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

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://platform.acedata.cloud/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）

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://platform.acedata.cloud",
        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://platform.acedata.cloud/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://platform.acedata.cloud/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://platform.acedata.cloud/support
Comunidade: Discord https://discord.gg/f9GRuKCmRc, X (Twitter) https://x.com/acedatacloud
Outros canais: E-mail office@acedata.cloud, office@germey.tech; endereço da empresa 131 Continental Dr, Suite 305, Newark, DE 19713, 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.

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Proxy

Avançado

AceDataCloud x402 Guia de Integração de Pagamento

I. Preparativos

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

2. Preparar a carteira de pagamento e os fundos

3. Criar Token da Plataforma

4. Solicitar informações básicas

II. Visão Geral do Fluxo de Pagamento

III. Exemplos de Integração

1. Primeira solicitação (aciona 402)

2. Gerar `X-PAYMENT`

3. Repetir com a assinatura

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

1. Axios（TypeScript）

2. Fetch（JavaScript）

3. Python requests

4. Python httpx（assíncrono）

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

Seis, Resolução de Problemas Comuns

Sete, Mais Ajuda

​I. Preparativos

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

​2. Preparar a carteira de pagamento e os fundos

​3. Criar Token da Plataforma

​4. Solicitar informações básicas

​II. Visão Geral do Fluxo de Pagamento

​III. Exemplos de Integração

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

​2. Gerar X-PAYMENT

​3. Repetir com a assinatura

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

​1. Axios（TypeScript）

​2. Fetch（JavaScript）

​3. Python requests

​4. Python httpx（assíncrono）

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

​Seis, Resolução de Problemas Comuns

​Sete, Mais Ajuda

I. Preparativos

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

2. Preparar a carteira de pagamento e os fundos

3. Criar Token da Plataforma

4. Solicitar informações básicas

II. Visão Geral do Fluxo de Pagamento

III. Exemplos de Integração

1. Primeira solicitação (aciona 402)

2. Gerar `X-PAYMENT`

3. Repetir com a assinatura

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

1. Axios（TypeScript）

2. Fetch（JavaScript）

3. Python requests

4. Python httpx（assíncrono）

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

Seis, Resolução de Problemas Comuns

Sete, Mais Ajuda