メインコンテンツへスキップ

​
概要

  • ベースパス: /api/v1
  • 認証: x-api-key ヘッダーで API キーを付与
  • 冪等性: 書き込み操作では Idempotency-Key ヘッダー（UUID 形式）が必須
  • レスポンス: すべての応答に追跡用ヘッダー x-request-id を含む

​
エンドポイント

  • GET /api/v1/wallets – ウォレット一覧
  • GET /api/v1/wallets/balances – 呼び出し元ウォレットの残高（チェーン別。既定ウォレットを使用）
  • GET /api/v1/wallets/:address/balances – 所有ウォレットアドレスの残高
  • GET /api/v1/tx/:id – トランザクション詳細
  • POST /api/v1/send – ネイティブ資産/トークン送付（EVM + Solana）
  • POST /api/v1/token/approve – ERC20 トークン承認（EVM のみ）
  • POST /api/v1/contracts/send – 一般的なコントラクト呼び出し（EVM のみ）
  • POST /api/v1/trade/quote – スワップ見積り（EVM + Solana）
  • POST /api/v1/trade/swap – スワップ実行（EVM + Solana）

​
チェーン

対応チェーン を参照。chain スラッグ（例: base, solana-devnet）を使用。

​
レート制限

  • 書き込み（POST /api/v1/trade/quote を含む）: ユーザーごとに 1 分あたり 15 リクエスト
  • 読み取り: ユーザーごとに 1 分あたり 60 リクエスト
  • 応答: 超過時は HTTP 429
  • ヘッダー: Retry-After（次ウィンドウまでの秒数）

​
冪等性（書き込み）

  • すべての変更系エンドポイントで Idempotency-Key が必要。
  • 同一のリクエスト本文での再送は元の 200 応答を返す。
  • 本文が異なる再送は HTTP 409（code: IDEMPOTENT_BODY_MISMATCH）。
  • 成功応答が保存されていない再送は HTTP 409（code: IDEMPOTENT_REPLAY）。
  • キーは認証ユーザー単位でスコープされ、エンドポイントパスが記録される。
  • 対象: POST /api/v1/send, POST /api/v1/token/approve, POST /api/v1/contracts/send, POST /api/v1/trade/swap。

​
エラーハンドリング

​
エラーレスポンス形式

{
  "error": "人間が読めるエラーメッセージ",
  "code": "ERROR_CODE",
  "requestId": "unique-request-id"
}

​
エラーコード

  • UNAUTHORIZED – 認証不足/無効または API キー不正（HTTP 401）
  • FORBIDDEN – 認証済みだが操作権限なし（HTTP 403）
  • NOT_FOUND – リソース未検出（HTTP 404）
  • RATE_LIMITED – レート制限超過（HTTP 429）
  • INVALID_INPUT – 無効なリクエストパラメータ（HTTP 400）
  • WALLET_NOT_FOUND – 指定ウォレット未検出
  • USER_NOT_LINKED – ユーザーが Privy に未連携
  • WALLET_NOT_DELEGATED – ウォレットがサーバー署名者に未委任
  • WALLET_ID_REQUIRED – Privy ウォレット ID 欠落
  • CHAIN_UNKNOWN – 不明または非対応のチェーン
  • INSUFFICIENT_FUNDS – 送信者の資金不足（価値/手数料）
  • IDEMPOTENT_BODY_MISMATCH – 同一キーで異なるリクエスト本文（HTTP 409）
  • IDEMPOTENT_REPLAY – 冪等性キーが既に使用済み（HTTP 409）
  • PRIVY_RPC_ERROR – Privy RPC サービスエラー
  • SEND_FAILED – トランザクション送信失敗
  • SERVICE_UNAVAILABLE – 必要なサービスが未構成
  • QUOTE_FAILED – 見積りサービスエラー（HTTP 400）
  • INTERNAL_ERROR – サーバーエラー
QUOTE_FAILED の詳細：
  • Solana/Jupiter: 一部の Solana mint は Jupiter で取引不可（厳選されたホワイトリスト）。この場合、API は HTTP 400 と code: QUOTE_FAILED、“Token not tradable on Jupiter” のようなエラーメッセージを返します。
  • EVM/1inch: トークンが 1inch でサポートされていない場合、API は HTTP 400 と code: QUOTE_FAILED、“Token not tradable on 1inch” のようなメッセージを返します。
  • これは、リクエストされた出力トークン/mint が上流プロバイダーによって取引不可とマークされている場合の予期される動作です（他の場所にプールが存在する場合でも）。

​
バリデーション

​
アドレス形式

  • EVM: /^0x[a-fA-F0-9]{40}$/ に一致
  • Solana: 有効な base58 公開鍵

​
共通パラメータ

  • 金額（EVM）: 整数文字列のみ（10 進または 0x-hex）。非負であること。ERC20 と value の場合は uint256 に収まること。
  • 金額（Solana）: 基本単位での整数文字列。SPL 金額は符号なし 64-bit 範囲内。
  • 送信者（from）: 任意。省略時は指定チェーンのユーザー既定ウォレットを使用。
  • 冪等性: すべての書き込みエンドポイントで Idempotency-Key ヘッダーが必要。同一本文の再送は元の応答を返す。

​
ネイティブトークンキーワード

トレードエンドポイント（/api/v1/trade/quote、/api/v1/trade/swap）では fromToken/toToken に大文字小文字を区別しない NATIVE キーワードを使用可能：
  • EVM: NATIVE は 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE に解決
  • Solana: NATIVE はラップ済み SOL ミント So11111111111111111111111111111111111111112 に解決
  • レスポンスは解決済みアドレスを返す（NATIVE ではない）
  • 送信エンドポイントではネイティブ転送に asset: "native" を使用（トークンアドレスではない）

​
規約

  • チェーン選択: chain スラッグ（例: base, base-sepolia, solana-devnet）。
  • Solana Transaction.chainId センチネル: 0 = mainnet, -2 = testnet, -3 = devnet。
  • 冪等性: ユーザー/キー単位で一意。再送は元の応答、本文不一致は 409。

​
関連

対応チェーン

ポリシーとセキュリティ