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

# X402 TypeScript SDK Guide d'intégration

> Platform API guide - Ace Data Cloud

TypeScript est l'un des moyens les plus recommandés pour intégrer Ace Data Cloud X402. Le SDK officiel gère les appels API ordinaires, le polling des tâches, la gestion des erreurs et les tentatives automatiques ; `@acedatacloud/x402-client` gère la signature de l'en-tête de requête `PAYMENT-SIGNATURE` en cas de `402 Payment Required`.

Adresse du code source et du package :

* Dépôt SDK : [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK)
* Dépôt 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)

## Installation des dépendances

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

Si vous utilisez Base ou SKALE, vous aurez besoin de la capacité de signature EVM :

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

Si vous utilisez Solana, vous aurez besoin de l'adaptateur de portefeuille Solana ou de `@solana/web3.js` :

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

Sortie de vérification d'installation et d'importation d'un projet npm propre :

```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
```

Explication des résultats :

* `@acedatacloud/sdk` et `@acedatacloud/x402-client` peuvent être installés depuis npm et importés par Node.js.
* `ethers` est utilisé pour la signature de données typées EVM, `@solana/web3.js` est utilisé pour la construction de transactions Solana.

## Exemple Base ou SKALE

Dans le navigateur, vous pouvez utiliser directement `window.ethereum`. Dans Node.js, vous pouvez envelopper `ethers.Wallet` dans un provider de style 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(`méthode non prise en charge : ${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);
```

Résultat de l'exécution de cet exemple de programme :

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

Explication des résultats :

* Le programme déclenche d'abord un 402 sans authentification, puis le handler signe `PAYMENT-SIGNATURE`, et enfin réessaie avec le même corps de requête.
* `content ADC_TS_SDK_X402_OK` est la chaîne fixe réellement renvoyée par le modèle, indiquant que la requête réessayée a atteint l'API cible.
* `id chatcmpl-DlcVLO4PQWvmjPDQpy9yQw2QdLGAT` est l'ID de réponse de cette complétion de chat, pouvant être utilisé pour faire correspondre avec les enregistrements de la plateforme.
* Les résultats de règlement sur la chaîne sont disponibles dans [E2E Vérification et Dépannage](https://platform.acedata.cloud/documents/x402-e2e-troubleshooting).

Il suffit de changer `network` en `skale` pour utiliser SKALE. L'avantage de SKALE est le faible coût des transactions sur la chaîne ; l'avantage de Base est la liquidité USDC et le support des portefeuilles plus matures, et seul Base propose une mesure postérieure `upto`.

Remarque : SKALE ne propose actuellement que `exact`. Si vous passez `preferScheme: 'upto'` sous `network: 'skale'`, le handler ne trouvera pas `upto` et reviendra silencieusement à `exact`, sans erreur — des scénarios comme la complétion de chat, qui sont mesurés par token, seront donc réglés à un tarif fixe, et non en fonction de l'utilisation réelle. Pour une mesure postérieure, veuillez utiliser Base.

## Exemple de portefeuille de navigateur

Lors de l'utilisation de MetaMask, Coinbase Wallet ou WalletConnect dans une application frontale, vous passez généralement directement le 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'
});
```

Le portefeuille du navigateur affichera une demande de confirmation de signature. L'utilisateur ne signe pas un message quelconque, mais la demande de paiement renvoyée par l'API : l'adresse de réception, le contrat USDC, le montant, la durée de validité et le nonce sont tous inclus dans la signature.

## Exemple Solana

Solana utilise SPL USDC `TransferChecked`. L'adaptateur de portefeuille passé doit exposer `publicKey` et `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
});
```

Le chemin Solana ne prend actuellement en charge que `exact`, pas `upto`. Si l'API renvoie plusieurs `accepts`, le handler choisira celui avec `network = 'solana'`.

Le chemin Solana a été vérifié sur la même API publique pour que le retry payé puisse renvoyer HTTP 200 et `ADC_SOLANA_E2E_OK`. Les requêtes RPC publiques peuvent être limitées, donc cet article ne fournit pas de hash de transaction Solana ; pour la réconciliation sur la chaîne, veuillez utiliser votre propre RPC Solana ou enregistrer la confirmation dans la console.

## Choisir `exact` ou `upto`

Le handler TypeScript actuel choisira le premier besoin de paiement correspondant au réseau renvoyé par le serveur. L'API d'Ace Data Cloud place généralement `exact` du même réseau avant `upto`, donc si vous souhaitez clairement utiliser la mesure postérieure, vous devez passer `preferScheme: 'upto'`.

Exemple :

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

Si le serveur n'a pas renvoyé le besoin `upto` pour ce réseau, le handler reviendra automatiquement au premier besoin disponible pour ce réseau, qui est généralement `exact`.

`upto` nécessite une autorisation unique Permit2. `upto` est actuellement uniquement disponible sur Base, donc il suffit d'autoriser une fois le USDC de Base :

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

Base `upto` a terminé la validation de l'API publique : HTTP 402 -> HTTP 200, la transaction de règlement en arrière-plan est `0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036`. Pour la sortie complète, voir la description du plan de facturation.

## Que fait le SDK

Le transport de `@acedatacloud/sdk` exécutera un gestionnaire de paiement lorsqu'il recevra un 402 :

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

Le gestionnaire retourné par `@acedatacloud/x402-client` fera :

1. Sélectionner l'exigence de paiement du réseau cible à partir de `ctx.accepts`.
2. Construire une signature EVM EIP-712 ou une transaction de transfert Solana selon le réseau.
3. Sérialiser l'enveloppe en Base64.
4. Retourner `{ headers: { 'PAYMENT-SIGNATURE': '<base64>' } }`.
5. Le SDK réessaie automatiquement avec le corps de la requête d'origine.

Cela signifie que le code métier n'a besoin d'être écrit que comme un appel SDK ordinaire, sans avoir à gérer manuellement les réessais 402.


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