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

> Platform API guide - Ace Data Cloud

TypeScript är ett av de mest rekommenderade sätten att integrera med Ace Data Cloud X402. Den officiella SDK:n ansvarar för vanliga API-anrop, uppgiftspolling, felhantering och automatisk omförsök; `@acedatacloud/x402-client` ansvarar för att signera `PAYMENT-SIGNATURE` begärningshuvudet när `402 Payment Required` inträffar.

Källkod och paketadress:

* SDK-förråd: [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK)
* X402 Client-förråd: [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)

## Installera beroenden

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

Om du använder Base eller SKALE, behöver du EVM-signaturkapacitet:

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

Om du använder Solana, behöver du Solana wallet adapter eller `@solana/web3.js`:

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

Utskrift av installation och importkontroll för ett rent npm-projekt:

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

Resultatförklaring:

* `@acedatacloud/sdk` och `@acedatacloud/x402-client` kan båda installeras från npm och importeras av Node.js.
* `ethers` används för EVM-typade data-signaturer, `@solana/web3.js` används för Solana-transaktionskonstruktion.

## Base eller SKALE-exempel

I webbläsaren kan du direkt använda `window.ethereum`. I Node.js kan du använda `ethers.Wallet` för att paketera en EIP-1193-stil provider.

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

Resultatet av att köra detta exempelprogram:

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

Resultatförklaring:

* Programmet utlöser först en 402 utan autentisering, sedan signerar handler `PAYMENT-SIGNATURE`, och slutligen försöker det igen med samma begäran.
* `content ADC_TS_SDK_X402_OK` är en fast sträng som modellen faktiskt returnerar, vilket indikerar att den omförsökta begäran nådde mål-API:t.
* `id chatcmpl-DlcVLO4PQWvmjPDQpy9yQw2QdLGAT` är ID:t för detta chat completion-svar, som kan användas för att jämföra med plattformens användningsregister.
* Resultatet av on-chain avräkning kan ses i [E2E verifiering och felsökning](https://platform.acedata.cloud/documents/x402-e2e-troubleshooting).

Ändra `network` till `skale` för att använda SKALE. Fördelen med SKALE är att gas-kostnaden för on-chain-transaktioner är låg; fördelen med Base är att USDC:s likviditet och plånboksstöd är mer moget, och endast Base erbjuder `upto` efterhandsmätning.

Observera: SKALE har för närvarande endast `exact`. Om `preferScheme: 'upto'` anges under `network: 'skale'`, kommer handler att tyst återgå till `exact` om `upto` inte hittas, utan att ge något felmeddelande—scenarier som chat completion som mäts per token kommer därför att avräknas till ett fast pris istället för baserat på verklig användning. För efterhandsmätning, använd Base.

## Webbläsarplånboksexempel

När du använder MetaMask, Coinbase Wallet eller WalletConnect i frontend-applikationer, skickar du vanligtvis direkt in EIP-1193 provider:

```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'
});
```

Webbläsarplånboken kommer att visa en signaturbekräftelse. Användaren signerar inte ett godtyckligt meddelande, utan betalningskravet som API:t returnerar: mottagaradress, USDC-kontrakt, belopp, giltighetstid och nonce ingår alla i signaturen.

## Solana-exempel

Solana använder SPL USDC `TransferChecked`. Den inkommande plånboksadaptern måste exponera `publicKey` och `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
});
```

Solana-vägen stöder för närvarande endast `exact`, och stöder inte `upto`. Om API:t returnerar flera `accepts`, kommer handler att välja den som har `network = 'solana'`.

Solana-vägen har verifierats för betald omförsök på samma offentliga API och kan returnera HTTP 200 och `ADC_SOLANA_E2E_OK`. Offentliga RPC-frågor kan begränsas, så denna artikel skriver inte ut Solana tx hash; för on-chain avstämning, använd din egen Solana RPC eller konsol för att registrera bekräftelse.

## Välja `exact` eller `upto`

Den nuvarande TypeScript-handlern kommer att välja det första betalningskravet som matchar nätverket som servern returnerar. Ace Data Clouds API placerar vanligtvis `exact` för samma nätverk före `upto`, så om du tydligt vill använda efterhandsmätning, behöver du ange `preferScheme: 'upto'`.

Exempel:

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

Om servern inte returnerar ett `upto` krav för det nätverket, kommer handler automatiskt att återgå till det första tillgängliga kravet för det nätverket, vilket vanligtvis är `exact`.

`upto` kräver engångsbehörighet för Permit2. `upto` erbjuds för närvarande endast på Base, så du behöver bara ge en engångsbehörighet för Base USDC:

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

Base `upto` har slutfört offentlig API-verifiering: HTTP 402 -> HTTP 200, efterföljande settlement tx är `0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036`. Fullständig utdata finns i beskrivningen av prissättningsplanen.

## SDK gjorde vad

`@acedatacloud/sdk`'s transport kommer att köra en betalningshanterare när den får 402:

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

`@acedatacloud/x402-client` returnerar en hanterare som kommer att:

1. Välja betalningskravet för mål-nätverket från `ctx.accepts`.
2. Konstruera EVM EIP-712 signatur eller Solana transfer transaction baserat på nätverket.
3. Serialisera kuvertet till Base64.
4. Returnera `{ headers: { 'PAYMENT-SIGNATURE': '<base64>' } }`.
5. SDK kommer automatiskt att försöka igen med den ursprungliga begäran.

Detta innebär att affärskoden bara behöver skrivas som en vanlig SDK-anrop, utan att manuellt hantera 402-omförsök.


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