合作伙伴 API

使用 Blast 只读 API 构建前端。将已有的合作伙伴凭证保留在后端，并随每个请求发送。

设置	值
基础 URL	`https://www.blast.fun`
认证请求头	`X-Blast-Partner-Key`
只读方法	`GET`、`HEAD`
合作伙伴共享配额	每分钟 300 次请求、每个 UTC 日 50,000 次请求

打开交互式 API 参考 → · 下载 OpenAPI · 限流与错误

第一个请求

将密钥存为私有环境变量 BLAST_PARTNER_KEY。不要将其放入 URL、公开环境变量、版本控制或请求日志。

curl --fail-with-body \
  'https://www.blast.fun/api/v1/presales?status=live&limit=20' \
  -H "X-Blast-Partner-Key: $BLAST_PARTNER_KEY"

成功响应包含 presales、next_cursor 和 as_of。将非 null 的 next_cursor 作为 cursor 传回，以读取下一页，同时保持状态、排序及过滤条件不变。null 游标表示最后一页。参数和排序选项见端点参考。

TypeScript SDK

在服务端应用中安装已发布的 REST 客户端：

npm install @interest-protocol/blast-partner-client@0.1.0

该 MIT 许可包没有运行时依赖或 peer 依赖。它与链上 @interest-protocol/blast-sdk 独立；后者的 ./partners 导出用于链上合约。

在服务器密钥存储或私有环境中配置 BLAST_PARTNER_KEY。SDK 使用已有凭证，不创建或分发凭证。绝不能使用公开环境变量，或将密钥打包到浏览器代码中。

下面是使用 Node.js 环境变量及标准 Request/Response API 的 TypeScript 服务端处理函数。请在应用自身认证和限流保护下挂载它。浏览器调用该函数，SDK 向 https://www.blast.fun/api/v1 发送 X-Blast-Partner-Key。

import {
  BlastPartnerError,
  createBlastPartnerClient,
} from "@interest-protocol/blast-partner-client";

const partnerKey = process.env.BLAST_PARTNER_KEY;
if (!partnerKey) {
  throw new Error("Configure BLAST_PARTNER_KEY on the server.");
}

const blast = createBlastPartnerClient({ partnerKey });

export async function listPartnerPresales(request: Request): Promise<Response> {
  try {
    const page = await blast.listPresales(
      { status: "live", limit: 20 },
      { signal: request.signal },
    );

    return Response.json(page, {
      headers: { "Cache-Control": "private, no-store" },
    });
  } catch (error) {
    if (!(error instanceof BlastPartnerError)) {
      throw error;
    }

    return Response.json(
      { error: { code: error.code ?? error.kind } },
      {
        status: error.status === 429 ? 429 : 502,
        headers: {
          "Cache-Control": "private, no-store",
          ...(error.retryAfter ? { "Retry-After": error.retryAfter } : {}),
        },
      },
    );
  }
}

响应保留 presales、next_cursor、as_of、精确的金额及价格字符串和 null 值。每次调用只读取一页；将非 null 的 next_cursor 作为 cursor，使用相同过滤条件读取下一页。详见分页与数据处理。

六个已开放的方法是 listPresales、featuredPresales、presale、prices、search 和 marketStatus。尚未开放的发行平台操作没有对应客户端方法。搜索仍保留部分覆盖限制及各分区的可用状态。

核心实现不依赖特定运行环境，使用标准 Fetch、Streams、URL、TextDecoder 和 AbortController API。示例中的环境变量访问属于你的应用逻辑；其他服务端运行时应通过各自绑定加载密钥，也可通过 createBlastPartnerClient({ partnerKey, fetch }) 注入兼容的 fetch。Node 和 Bun 已测试；Deno 和边缘运行时尚未直接验证。

请求默认超时为 10 秒，解码后的响应大小上限为 2 MiB。SDK 不自动重试、轮询或缓存。BlastPartnerError 提供经过脱敏的 kind、status、code 和 retryAfter 字段。不要记录凭证、请求头或原始传输错误。不要重试 401/403；对 429 和临时 503，按重试策略使用有上限的退避，并遵守 Retry-After。

密钥必须包含 Blast 发放的完整值，包括 blast_pk_ 前缀。使用 X-Blast-Partner-Key，而不是 Authorization: Bearer 或 X-Blast-Api-Key。无需 Blast 登录、钱包签名或页面 cookie。即使存在其他凭证，提供了无效密钥仍会被拒绝。

服务端集成

将带密钥的 SDK 客户端放在服务端模块。代理必须使用应用自身的授权和配额，只接受应用所需输入，并返回 Cache-Control: private, no-store。不要开放任意上游 URL 或请求头转发。请使用公开合作伙伴 API https://www.blast.fun/api/v1；内部服务 https://api.blast.fun 使用不同凭证。

REST API 也支持由 Blast 登记的精确 HTTPS 来源的 CORS。CORS 不会隐藏密钥，也不能阻止其在浏览器之外使用。应用集成应通过服务器或代理，避免合作伙伴凭证进入公开浏览器代码。排查已有浏览器直连集成时，参见认证与来源错误。

密钥轮换与泄露

密钥泄露时请立即联系 Blast。Blast 可单独撤销该密钥，无需重新部署。撤销成功后，后续认证检查返回 401 partner_key_invalid，已获授权的请求仍可完成。

常规轮换时，为同一合作伙伴申请新密钥，将后端切换到新密钥后，再请 Blast 撤销旧密钥。已知泄露时应立即撤销泄露密钥。密钥只在发放时展示一次，遗失后必须更换。轮换不重置配额，撤销某个密钥也不会撤销你的其他密钥。

读取响应

成功响应为 JSON；HEAD 不含响应正文，但与 GET 消耗相同配额。
保留原字段名：有些端点使用 next_cursor，另一些使用 nextCursor。分页令牌是不透明值，仅适用于原资源和过滤条件。
以十进制字符串返回的金额及价格必须保留精度。整数原子金额用 BigInt，小数价格用十进制运算库。以 _ms 或 Ms 结尾的时间戳为 Unix 毫秒；lag_ms 等时长字段以毫秒计；基点中 10,000 表示 100%。
数据新鲜度通过 as_of、provenance 或分区的来源信息报告。null 或不可用不等于零。请显式处理缺失价格、不完整持币人快照和过时数据。
合作伙伴 HTTP 响应使用 no-store。不要假设存在共享 CDN 缓存，或每次请求都会成功。详见重试策略。

继续阅读只读端点参考。

API 版本

新集成使用 /api/v1。已有 /api/social/... 和 /api/launchpad/... 合作伙伴 URL 继续使用相同密钥工作，无需立即迁移。详见版本与兼容性政策。