sol-incinerator

Sol-Incinerator Burn + Close API v2 ガイド

Sol-Incinerator の HTTP API を統合するための実用的なガイドです。主なユーザー向け機能は、トークンのバーン、NFT のバーン、トークンアカウントのクローズです。高度な一括クリーンアップやリレーのワークフローにも対応しています。

稼働中の API ベース URL：https://v2.api.sol-incinerator.com

概要

Sol-Incinerator API v2 では、次の機能を提供します。

• POST /api-keys/generate による API キーの自動発行
• SPL Token、Token-2022、NFT アカウントのパターンに対応したバーン／クローズトランザクションの構築
• クライアント側でトランザクション全体を組み立てる場合に利用できる、インストラクションのみを返すエンドポイント
• 実行前に回収できるレントと手数料を見積もるプレビュー／サマリーエンドポイント
• 署名済みのペイロードをブロードキャストするトランザクションリレーエンドポイント
• 検証機能を組み込んだパートナー／紹介による収益化の入力項目

主なエンドポイントグループ

グループ	エンドポイント
公開ディスカバリー	GET /、/openapi.json、/.well-known/api-catalog、/llms*、/DOCS.md
公開認証の初期設定	POST /api-keys/generate
バーン + クローズ（API キーが必要）	/burn、/burn-instructions、/close、/close-instructions、/batch/close-all*
リレー + 確認（API キーが必要）	/transactions/send、/transactions/send-batch、/transactions/status

クイックスタート

1) API キーを生成する（ユーザー入力なし）

const baseUrl = 'https://v2.api.sol-incinerator.com';

const keyResp = await fetch(`${baseUrl}/api-keys/generate`, {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ label: 'autonomous-agent' }),
});

if (!keyResp.ok) {
  throw new Error(`API key generation failed: ${keyResp.status}`);
}

const { apiKey } = await keyResp.json() as { apiKey: string };

2) プレビューを先に行うフローを実行する

const headers = {
  'content-type': 'application/json',
  'x-api-key': apiKey,
};

const previewResp = await fetch(`${baseUrl}/burn/preview`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    userPublicKey,
    assetId,
    burnAmount: '1',
  }),
});

3) 構築、署名、送信

1. /burn、/close、または /batch/close-all を呼び出します。
2. base58 でシリアライズされたトランザクションをデコードし、ウォレットのキーペアでローカル署名します。
3. ウォレット／RPC のフローで送信するか、/transactions/send および /transactions/send-batch を使用します。
4. 必要に応じて /transactions/status をポーリングします。

主な統合ルール

認証

• API キーは次のいずれかの方法で送信します。
  • x-api-key: ak_xxx.yyy（サーバーエージェントに推奨）
  • Authorization: Bearer ak_xxx.yyy
• キーがない場合、または無効な場合、コアのルートは 401 を返します。

必須のリクエストボディフィールド

• 単一アセットのルート（/burn、/close、プレビュー、インストラクション）：
  • userPublicKey
  • assetId
• バッチルート（/batch/close-all*）：
  • userPublicKey

よく使われる任意のリクエストボディフィールド

• feePayer（公開鍵）
• asLegacyTransaction（ブール値）
• priorityFeeMicroLamports（整数）
• autoCloseTokenAccounts（ブール値、バーンフロー）
• burnAmount（最小単位で指定する正の整数。大きな値には文字列を使用）
• offset、limit（バッチのページネーション／ウィンドウ指定）

パートナーおよび紹介の検証

• partnerFeeAccount と partnerFeeBps は、両方を指定するか、どちらも指定しない必要があります。
• partnerFeeBps は 0..9800 の整数である必要があります。
• referralCode は、2～20 文字の小文字英数字である必要があります。
• referralCode とパートナー手数料のフィールドは併用できません。

エンドポイントの選択

• 次の場合は、実行前に /burn/preview または /close/preview を使用します。
  • ユーザーが手数料を確認する必要がある
  • アセットが凍結状態、無効、または空でない可能性がある
• 署名用のトランザクションペイロードをそのまま取得する場合は、/burn および /close を使用します。
• アプリがクライアント側でトランザクションを組み立てる場合は、/burn-instructions および /close-instructions を使用します。
• ウォレットのクリーンアップ UX では、まず /batch/close-all/preview を使用します。
• ダッシュボードの件数を軽量に取得するには、/batch/close-all/summary を使用します。
• 複数のトランザクションで構成される close-all パイプラインには、/transactions/send-batch を使用します。

ワークフローの例（エージェント）

1. POST /api-keys/generate で API キーを生成します。
2. 対象の操作に対応するプレビューエンドポイントを実行します。
3. プレビューに問題がなければ、実行可能なトランザクションペイロードをリクエストします。
4. トランザクションにローカルで署名します。
5. 署名済みペイロードを送信します。
6. /transactions/status で完了を確認します。
7. 操作メタデータ（署名、手数料、回収した lamport）を保存します。

ガイドライン

• 破壊的な操作の前に、必ずプレビューを実行してください。
• 大きな原子単位の値には、必ずburnAmountを文字列として渡してください。
• 送信前に、ユーザーとアセットの公開鍵を必ず検証してください。
• 秘密鍵はローカルに保管し、リレーエンドポイントには署名済みトランザクションのみを送信してください。
• referralCodeをパートナー手数料フィールドと組み合わせないでください。
• リレールートに未署名のペイロードを送信しないでください。
• encoding: "base64"が明示的に設定されていない限り、リレーペイロードがbase64エンコードだと想定しないでください（デフォルトはbase58です）。

リソース

• 正式なドキュメント（v2）
• OpenAPI仕様（/openapi.json）
• LLMインデックス（/llms.txt）
• フローの例（アカウントを閉じる、トークンをバーンする、NFTをバーンする）

スキルの構成

sol-incinerator/
├── SKILL.md                          # This file
├── resources/
│   └── api-reference.md              # Endpoint matrix and request notes
├── examples/
│   └── basic/
│       └── http-flow.ts              # Close-account + token/NFT burn examples
├── templates/
│   └── sol-incinerator-client.ts     # Ready-to-use TypeScript client
└── docs/
    └── troubleshooting.md            # Common errors and fixes