> ## Documentation Index
> Fetch the complete documentation index at: https://docs.afkcrypto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AFK API v1

> AFK Crypto API v1 の概要と規約

## 概要

* ベースパス: `/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）

## チェーン

[対応チェーン](/api-reference/supported-chains/) を参照。`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`。

## エラーハンドリング

### エラーレスポンス形式

```json theme={null}
{
  "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` – サーバーエラー

<Note>
  **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 が上流プロバイダーによって取引不可とマークされている場合の予期される動作です（他の場所にプールが存在する場合でも）。
</Note>

## バリデーション

### アドレス形式

* 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。

## 関連

<CardGroup cols={2}>
  <Card title="対応チェーン" icon="link-simple" href="/api-reference/supported-chains/" />

  <Card title="ポリシーとセキュリティ" icon="shield" href="/api-reference/policies-security/" />
</CardGroup>