> ## 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 Przewodnik Integracji

> Platform API guide - Ace Data Cloud

TypeScript jest jednym z najbardziej zalecanych sposobów integracji z Ace Data Cloud X402. Oficjalne SDK odpowiada za zwykłe wywołania API, polling zadań, obsługę błędów i automatyczne ponowne próby; `@acedatacloud/x402-client` odpowiada za podpisywanie nagłówka żądania `PAYMENT-SIGNATURE` w przypadku napotkania `402 Payment Required`.

Adresy źródła i pakietów:

* Repozytorium SDK: [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK)
* Repozytorium 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)

## Instalacja zależności

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

Jeśli używasz Base lub SKALE, potrzebujesz zdolności podpisywania EVM:

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

Jeśli używasz Solana, potrzebujesz adaptera portfela Solana lub `@solana/web3.js`:

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

Czysta instalacja projektu npm i sprawdzenie importów:

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

Opis wyników:

* `@acedatacloud/sdk` i `@acedatacloud/x402-client` można zainstalować z npm i zaimportować do Node.js.
* `ethers` służy do podpisywania danych typu EVM, `@solana/web3.js` służy do budowy transakcji Solana.

## Przykład Base lub SKALE

W przeglądarce można bezpośrednio używać `window.ethereum`. W Node.js można użyć `ethers.Wallet`, aby opakować styl EIP-1193 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);
```

Wynik działania tego przykładu programu:

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

Opis wyników:

* Program najpierw wywołuje 402 bez autoryzacji, następnie handler podpisuje `PAYMENT-SIGNATURE`, a na końcu ponownie próbuje z tym samym ciałem żądania.
* `content ADC_TS_SDK_X402_OK` to stały ciąg zwracany przez model, co oznacza, że ponowne żądanie trafiło do docelowego API.
* `id chatcmpl-DlcVLO4PQWvmjPDQpy9yQw2QdLGAT` to identyfikator odpowiedzi chat completion, który można wykorzystać do porównania z zapisami na platformie.
* Wyniki rozliczenia na łańcuchu można zobaczyć w [E2E Weryfikacja i Rozwiązywanie Problemów](https://platform.acedata.cloud/documents/x402-e2e-troubleshooting).

Aby używać SKALE, wystarczy zmienić `network` na `skale`. Zaletą SKALE jest niski koszt gazu transakcji na łańcuchu; zaletą Base jest większa płynność USDC i bardziej dojrzałe wsparcie portfeli, a tylko Base oferuje pomiar `upto` po transakcji.

Uwaga: SKALE obecnie obsługuje tylko `exact`. Jeśli w `network: 'skale'` przekażesz `preferScheme: 'upto'`, handler nie znajdzie `upto` i cicho przełączy się na `exact`, nie zgłaszając błędu — scenariusze takie jak chat completion, które są rozliczane na podstawie tokenów, będą w związku z tym rozliczane według stałej stawki, a nie rzeczywistego zużycia. Aby uzyskać pomiar po transakcji, użyj Base.

## Przykład portfela przeglądarki

Podczas korzystania z MetaMask, Coinbase Wallet lub WalletConnect w aplikacji frontendowej, zazwyczaj bezpośrednio przekazuje się 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'
});
```

Portfel przeglądarki wyświetli okno potwierdzenia podpisu. Użytkownik nie podpisuje dowolnej wiadomości, lecz żądania płatności zwróconego przez API: adres odbiorcy, kontrakt USDC, kwotę, okres ważności i nonce są zawarte w podpisie.

## Przykład Solana

Solana używa SPL USDC `TransferChecked`. Przekazany adapter portfela musi udostępniać `publicKey` i `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
});
```

Ścieżka Solana obecnie obsługuje tylko `exact`, nie obsługuje `upto`. Jeśli API zwróci wiele `accepts`, handler wybierze tę, która ma `network = 'solana'`.

Ścieżka Solana została już zweryfikowana na tym samym publicznym API, gdzie płatne ponowne próby mogą zwrócić HTTP 200 i `ADC_SOLANA_E2E_OK`. Publiczne zapytania RPC mogą być ograniczone, dlatego w tym dokumencie nie podano hasha transakcji Solana; w przypadku potrzeby rozliczenia na łańcuchu, proszę użyć własnego RPC Solana lub konsoli do rejestrowania potwierdzeń.

## Wybór `exact` lub `upto`

Aktualny handler TypeScript wybierze pierwszy pasujący do sieci wymóg płatności zwrócony przez serwer. API Ace Data Cloud zazwyczaj umieszcza `exact` dla tej samej sieci przed `upto`, dlatego jeśli chcesz wyraźnie korzystać z pomiaru po transakcji, musisz przekazać `preferScheme: 'upto'`.

Przykład:

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

Jeśli serwer nie zwrócił wymogu `upto` dla tej sieci, handler automatycznie przełączy się na pierwszy dostępny wymóg dla tej sieci, którym zazwyczaj jest `exact`.

`upto` wymaga jednorazowego zezwolenia Permit2. `upto` obecnie dostępne jest tylko na Base, dlatego wystarczy raz zezwolić na USDC Base:

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

Base `upto` zakończyło publiczną weryfikację API: HTTP 402 -> HTTP 200, transakcja rozliczeniowa to `0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036`. Pełne wyjście znajduje się w opisie planu taryfowego.

## Co zrobiło SDK

Transport `@acedatacloud/sdk` wykona handler płatności po otrzymaniu 402:

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

Handler zwracany przez `@acedatacloud/x402-client`:

1. Wybiera wymagania płatności dla docelowej sieci z `ctx.accepts`.
2. Buduje podpis EVM EIP-712 lub transakcję transferu Solana w zależności od sieci.
3. Serializuje envelope do Base64.
4. Zwraca `{ headers: { 'PAYMENT-SIGNATURE': '<base64>' } }`.
5. SDK automatycznie powtarza żądanie z oryginalnym ciałem.

To oznacza, że kod biznesowy musi być napisany jak w przypadku zwykłego wywołania SDK, nie wymaga ręcznego obsługiwania ponownego próby 402.


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