> ## 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.

# Tutorial de Integração do SDK TypeScript X402

> Platform API guide - Ace Data Cloud

TypeScript é uma das maneiras mais recomendadas para integrar o Ace Data Cloud X402. O SDK oficial é responsável por chamadas de API comuns, polling de tarefas, tratamento de erros e tentativas automáticas; `@acedatacloud/x402-client` é responsável por assinar o cabeçalho de requisição `PAYMENT-SIGNATURE` quando encontra `402 Payment Required`.

Endereços do código-fonte e pacotes:

* Repositório do SDK: [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK)
* Repositório do X402 Client: [https://github.com/AceDataCloud/X402Client](https://github.com/AceDataCloud/X402Client)
* npm SDK: [https://www.npmjs.com/package/@acedatacloud/sdk](https://www.npmjs.com/package/@acedatacloud/sdk)
* npm X402 Client: [https://www.npmjs.com/package/@acedatacloud/x402-client](https://www.npmjs.com/package/@acedatacloud/x402-client)

## Instalação de Dependências

```bash theme={null}
npm install @acedatacloud/sdk @acedatacloud/x402-client
```

Se usar Base ou SKALE, é necessário ter capacidade de assinatura EVM:

```bash theme={null}
npm install ethers
```

Se usar Solana, é necessário o adaptador de carteira Solana ou `@solana/web3.js`:

```bash theme={null}
npm install @solana/web3.js
```

Saída de verificação de instalação e importação de um projeto npm limpo:

```text theme={null}
imports_ok true true true true true
@acedatacloud/sdk@2026.504.2
@acedatacloud/x402-client@2026.531.3
ethers@6.16.0
@solana/web3.js@1.98.4
```

Explicação dos resultados:

* `@acedatacloud/sdk` e `@acedatacloud/x402-client` podem ser instalados via npm e importados pelo Node.js.
* `ethers` é usado para assinatura de dados tipados EVM, `@solana/web3.js` é usado para construção de transações Solana.

## Exemplo de Base ou SKALE

No navegador, pode-se usar diretamente `window.ethereum`. No Node.js, pode-se usar `ethers.Wallet` para encapsular um provider no estilo EIP-1193.

```ts theme={null}
import { Wallet } from 'ethers';
import { AceDataCloud } from '@acedatacloud/sdk';
import { createX402PaymentHandler } from '@acedatacloud/x402-client';

const wallet = new Wallet(process.env.EVM_PRIVATE_KEY!);

const evmProvider = {
  async request({ method, params }: { method: string; params?: unknown[] }) {
    if (method !== 'eth_signTypedData_v4') {
      throw new Error(`unsupported method: ${method}`);
    }
    const [, typedDataJson] = params as [string, string];
    const typedData = JSON.parse(typedDataJson);
    return wallet.signTypedData(typedData.domain, typedData.types, typedData.message);
  }
};

const client = new AceDataCloud({
  paymentHandler: createX402PaymentHandler({
    network: 'base',
    evmProvider,
    evmAddress: wallet.address
  })
});

const result = await client.openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Say hi in 3 words' }],
  max_tokens: 10
});

console.log(result.choices[0].message.content);
```

Resultado da execução do programa deste exemplo:

```text theme={null}
payer 0xd0479FA9FD8C678303d477433d24C15e3723CC1C
elapsed_ms 6782
content ADC_TS_SDK_X402_OK
id chatcmpl-DlcVLO4PQWvmjPDQpy9yQw2QdLGAT
```

Explicação dos resultados:

* O programa primeiro aciona um 402 sem autenticação, depois o handler assina o `PAYMENT-SIGNATURE`, e finalmente tenta novamente com o mesmo corpo de requisição.
* `content ADC_TS_SDK_X402_OK` é a string fixa retornada pelo modelo, indicando que a requisição após a tentativa entrou na API alvo.
* `id chatcmpl-DlcVLO4PQWvmjPDQpy9yQw2QdLGAT` é o ID da resposta de chat completion desta vez, que pode ser usado para comparação com os registros da plataforma.
* Resultados de liquidação na blockchain podem ser vistos em [Verificação E2E e Resolução de Problemas](https://platform.acedata.cloud/documents/x402-e2e-troubleshooting).

Mude `network` para `skale` para usar SKALE. A vantagem do SKALE é o baixo custo de gás em transações na blockchain; a vantagem do Base é a liquidez do USDC e suporte a carteiras mais maduro, além de que apenas o Base oferece medição posterior `upto`.

Nota: SKALE atualmente só suporta `exact`. Se `preferScheme: 'upto'` for passado sob `network: 'skale'`, o handler não encontrará `upto` e fará um fallback silencioso para `exact`, sem gerar erro — cenários como chat completions que são medidos por token serão, portanto, liquidadas a uma taxa fixa, e não com base no uso real. Para medição posterior, use Base.

## Exemplo de Carteira do Navegador

Ao usar MetaMask, Coinbase Wallet ou WalletConnect em aplicações front-end, geralmente se passa diretamente o provider EIP-1193:

```ts theme={null}
import { AceDataCloud } from '@acedatacloud/sdk';
import { createX402PaymentHandler } from '@acedatacloud/x402-client';

const [address] = await window.ethereum.request({ method: 'eth_requestAccounts' });

const client = new AceDataCloud({
  paymentHandler: createX402PaymentHandler({
    network: 'base',
    evmProvider: window.ethereum,
    evmAddress: address
  })
});

const image = await client.images.generate({
  provider: 'nano-banana',
  prompt: 'a yellow banana on a white background'
});
```

A carteira do navegador exibirá uma confirmação de assinatura. O que o usuário assina não é uma mensagem qualquer, mas sim a solicitação de pagamento retornada pela API: o endereço de recebimento, o contrato USDC, o valor, a validade e o nonce estão todos incluídos na assinatura.

## Exemplo de Solana

Solana usa SPL USDC `TransferChecked`. O adaptador de carteira passado precisa expor `publicKey` e `signAndSendTransaction`.

```ts theme={null}
import { AceDataCloud } from '@acedatacloud/sdk';
import { createX402PaymentHandler } from '@acedatacloud/x402-client';

const client = new AceDataCloud({
  paymentHandler: createX402PaymentHandler({
    network: 'solana',
    solanaWallet: phantomWallet
  })
});

const result = await client.openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Say hi in 3 words' }],
  max_tokens: 10
});
```

O caminho Solana atualmente só suporta `exact`, não suporta `upto`. Se a API retornar múltiplos `accepts`, o handler escolherá aquele com `network = 'solana'`.

O caminho Solana já foi validado em uma API pública onde o retry pago pode retornar HTTP 200 e `ADC_SOLANA_E2E_OK`. Consultas RPC públicas podem ser limitadas, portanto, este documento não inclui o hash da transação Solana; para conciliação na blockchain, use seu próprio RPC Solana ou registre a confirmação no console.

## Escolhendo `exact` ou `upto`

Atualmente, o handler TypeScript escolherá o primeiro requisito de pagamento que corresponde à rede retornado pelo servidor. A API do Ace Data Cloud geralmente coloca o `exact` da mesma rede antes do `upto`, portanto, se você deseja claramente usar a medição posterior, precisa passar `preferScheme: 'upto'`.

Exemplo:

```ts theme={null}
const client = new AceDataCloud({
  paymentHandler: createX402PaymentHandler({
    network: 'base',
    evmProvider,
    evmAddress: wallet.address,
    preferScheme: 'upto'
  })
});
```

Se o servidor não retornar o requisito `upto` para essa rede, o handler fará automaticamente um fallback para o primeiro requisito disponível dessa rede, que geralmente é `exact`.

`upto` requer autorização única Permit2. `upto` atualmente só está disponível no Base, portanto, é necessário autorizar apenas uma vez o USDC do Base:

```bash theme={null}
npx tsx scripts/approve-permit2.ts --network base
```

Base `upto` já completou a validação da API pública: HTTP 402 -> HTTP 200, a transação de liquidação posterior é `0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036`. A saída completa pode ser vista na descrição do plano de cobrança.

## O que o SDK fez

O transport de `@acedatacloud/sdk` executará um handler de pagamento ao receber 402:

```ts theme={null}
type PaymentHandler = (ctx: {
  url: string;
  method: string;
  body?: unknown;
  accepts: PaymentRequirement[];
}) => Promise<{ headers: Record<string, string> }>;
```

O handler retornado por `@acedatacloud/x402-client` irá:

1. Selecionar o requisito de pagamento da rede alvo a partir de `ctx.accepts`.
2. Construir a assinatura EVM EIP-712 ou a transação de transferência Solana conforme a rede.
3. Serializar o envelope em Base64.
4. Retornar `{ headers: { 'PAYMENT-SIGNATURE': '<base64>' } }`.
5. O SDK automaticamente tentará novamente com o corpo da requisição original.

Isso significa que o código de negócios só precisa ser escrito como uma chamada normal do SDK, sem necessidade de lidar manualmente com a nova tentativa de 402.


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