> ## 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 інтеграційний посібник

> Platform API guide - Ace Data Cloud

TypeScript є одним з найрекомендованіших способів інтеграції з Ace Data Cloud X402. Офіційний SDK відповідає за звичайні API виклики, опитування завдань, обробку помилок та автоматичне повторення; `@acedatacloud/x402-client` відповідає за підписання заголовка запиту `PAYMENT-SIGNATURE` у разі отримання `402 Payment Required`.

Джерело та адреса пакета:

* SDK репозиторій: [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK)
* 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)

## Встановлення залежностей

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

Якщо використовуєте Base або SKALE, потрібна EVM підписна можливість:

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

Якщо використовуєте Solana, потрібен Solana wallet adapter або `@solana/web3.js`:

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

Чисте встановлення npm проекту та перевірка імпортів:

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

Результати пояснюють:

* `@acedatacloud/sdk` та `@acedatacloud/x402-client` можуть бути встановлені з npm та імпортовані в Node.js.
* `ethers` використовується для підпису EVM typed data, `@solana/web3.js` використовується для побудови транзакцій Solana.

## Приклад для Base або SKALE

У браузері можна безпосередньо використовувати `window.ethereum`. У Node.js можна обернути `ethers.Wallet` в provider стилю 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);
```

Результат виконання цього прикладу програми:

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

Результати пояснюють:

* Програма спочатку викликає 402 без аутентифікації, потім обробник підписує `PAYMENT-SIGNATURE`, і нарешті повторює запит з тим же тілом.
* `content ADC_TS_SDK_X402_OK` є фіксованим рядком, який дійсно повертає модель, що свідчить про те, що повторний запит потрапив до цільового API.
* `id chatcmpl-DlcVLO4PQWvmjPDQpy9yQw2QdLGAT` є ID відповіді на це chat completion, який можна використовувати для звірки з записами платформи.
* Результати розрахунків в ланцюгу дивіться в [E2E верифікація та усунення неполадок](https://platform.acedata.cloud/documents/x402-e2e-troubleshooting).

Змініть `network` на `skale`, щоб використовувати SKALE. Перевага SKALE полягає в низькій вартості газу для транзакцій в ланцюгу; перевага Base полягає в більш зрілій ліквідності USDC та підтримці гаманців, а також тільки Base пропонує `upto` післявимірювання.

Зверніть увагу: SKALE наразі підтримує лише `exact`. Якщо в `network: 'skale'` передати `preferScheme: 'upto'`, обробник не знайде `upto` і тихо повернеться до `exact`, не видаючи помилок — сценарії, які вимірюються за токенами, такі як chat completion, будуть розраховані за фіксованою ціною, а не за реальним споживанням. Для післявимірювання використовуйте Base.

## Приклад браузерного гаманця

При використанні MetaMask, Coinbase Wallet або WalletConnect у фронтенд-додатках зазвичай безпосередньо передається 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'
});
```

Браузерний гаманець виведе підтвердження підпису. Користувач підписує не будь-яке повідомлення, а платіжний запит, що повертається API: адреса отримувача, контракт USDC, сума, термін дії та nonce всі включені в підпис.

## Приклад Solana

Solana використовує SPL USDC `TransferChecked`. Переданий гаманець адаптер має експонувати `publicKey` та `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 наразі підтримує лише `exact`, не підтримує `upto`. Якщо API повертає кілька `accepts`, обробник вибирає той, що має `network = 'solana'`.

Шлях Solana на одному публічному API вже перевірено, що платний повтор може повернути HTTP 200 та `ADC_SOLANA_E2E_OK`. Публічний RPC запит може бути обмежений, тому в цій статті не вказується хеш транзакції Solana; для звірки в ланцюгу використовуйте свій власний Solana RPC або консоль для запису підтвердження.

## Вибір `exact` або `upto`

Поточний TypeScript обробник вибирає першу відповідність вимоги оплати, повернуту сервером для мережі. API Ace Data Cloud зазвичай ставить `exact` для однієї мережі перед `upto`, тому якщо ви чітко хочете використовувати післявимірювання, потрібно передати `preferScheme: 'upto'`.

Приклад:

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

Якщо сервер не повертає вимогу `upto` для цієї мережі, обробник автоматично повернеться до першої доступної вимоги для цієї мережі, зазвичай це `exact`.

`upto` вимагає одноразового дозволу Permit2. `upto` наразі доступний лише на Base, тому потрібно лише один раз дозволити USDC Base:

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

Base `upto` вже завершив публічну перевірку API: HTTP 402 -> HTTP 200, наступна транзакція settlement tx - `0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036`. Повний вивід дивіться в описі тарифного плану.

## Що зробив SDK

`@acedatacloud/sdk` транспорт виконає один раз payment handler при отриманні 402:

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

`@acedatacloud/x402-client` повертає handler, який:

1. Вибирає payment requirement цільової мережі з `ctx.accepts`.
2. Формує EVM EIP-712 підпис або транзакцію переказу Solana за мережею.
3. Сериалізує envelope в Base64.
4. Повертає `{ headers: { 'PAYMENT-SIGNATURE': '<base64>' } }`.
5. SDK автоматично повторно намагається з оригінальним тілом запиту.

Це означає, що бізнес-код потрібно писати так, як звичайний виклик SDK, без необхідності вручну обробляти повторні спроби 402.


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