sol-incinerator

Sol-Incinerator 销毁 + 关闭 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（推荐用于服务器 Agent）
  • 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：
  • 应用在客户端组装交易
• 对于钱包清理体验，首先使用 /batch/close-all/preview
• 对于轻量级仪表板计数，使用 /batch/close-all/summary
• 对于多笔交易的 close-all 流程，使用 /transactions/send-batch

示例工作流（Agent）

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