バイヤー向けクイックスタート

x402を使って支払いが必要なサービスにプログラムでアクセスする方法を説明します。

このガイドでは、支払い要件の検出・支払いの実行・有料リソースへのアクセスをプログラムで行う方法を学びます。

x402リポジトリにはfetch・Axios・MCPなど各種クライアントの設定済みサンプルが用意されています。GitHubで確認する

前提条件

始める前に以下を準備してください：

USDC入りのクリプトウォレット（EVM・SVM互換）
Node.jsとnpm、Go、またはPythonとpip
x402決済が必要なサービス（テスト用は https://x402.org/facilitator を使うサービスで可）

クライアントを選択：

1. 依存関係のインストール

npm install @x402/fetch @x402/evm

# Solanaサポートを追加する場合:
npm install @x402/svm

2. ウォレット署名者の作成

秘密鍵から署名者を作成します。秘密鍵は必ず環境変数で管理し、コードに直接記述しないでください。

必要なパッケージをインストール：

npm install viem

import { privateKeyToAccount } from "viem/accounts";

// 環境変数から秘密鍵を読み込む
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

Solana（SVM）署名者

Solanaでの支払いには、SolanaKitを使って署名者を作成します：

import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";

// 64バイトのbase58秘密鍵（秘密鍵 + 公開鍵）
const svmSigner = await createKeyPairSignerFromBytes(
  base58.decode(process.env.SVM_PRIVATE_KEY!)
);

3. 支払い対応クライアントの作成

既存のHTTPクライアントをx402対応版にラップします。ラップ後は通常のHTTPクライアントと同じように使えます。402レスポンスが返ってきた場合、自動的に支払いを処理してリクエストを再送します。

import { wrapFetchWithPayment } from "@x402/fetch";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

// 通常のfetchをx402対応版にラップ
const x402Fetch = wrapFetchWithPayment(fetch, signer);

// 通常のfetchと同じように使える
const response = await x402Fetch("https://api.example.com/weather");
const data = await response.json();
console.log(data);

4. エラーハンドリング

支払いが失敗する主なケースと対処法：

残高不足：ウォレットにUSDCが不足している場合。必要額を入金してください。
ネットワーク不一致：サーバーが要求するネットワークに対応した署名者を使っていない場合。
支払い期限切れ：支払いペイロードの有効期限が切れた場合。再度リクエストを送信してください。

詳細なサンプルコードはリポジトリのexamplesディレクトリを参照してください。

次のステップ

まとめ

x402クライアントSDKのインストール
秘密鍵からウォレット署名者を作成
既存HTTPクライアントをx402対応版にラップ
通常のHTTPリクエストと同じ感覚で有料APIにアクセス

← FAQ セラー向けクイックスタート →