agentbox

AgentBox

通过 x402 支付 5 美元 USDC（Solana），配置专属 AI Agent。每个 Agent 都运行 OpenClaw AI 网关，并提供 HTTPS、Web 终端和 Solana 钱包。实例有效期为 7 天（可续期）。

基础 URL：https://api.agentbox.fyi

前提条件

npm install @x402/fetch @x402/svm @solana/kit

需要一个有 USDC 余额的 Solana 钱包文件（solana-keygen JSON 格式：64 字节数组）。

1. 配置实例

创建 provision.mjs，并使用 node provision.mjs /path/to/wallet.json [name] 运行：

import { readFileSync } from "node:fs";
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { registerExactSvmScheme } from "@x402/svm/exact/client";

const keypairBytes = new Uint8Array(
  JSON.parse(readFileSync(process.argv[2], "utf8")),
);
const signer = await createKeyPairSignerFromBytes(keypairBytes);

const client = new x402Client();
registerExactSvmScheme(client, { signer });
const x402Fetch = wrapFetchWithPayment(fetch, client);

const res = await x402Fetch("https://api.agentbox.fyi/provision", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(process.argv[3] ? { name: process.argv[3] } : {}),
});
console.log(JSON.stringify(await res.json(), null, 2));

通过 x402 自动支付 5 美元 USDC。名称为可选项（省略时会自动生成），且必须符合 DNS 命名规范：小写字母、数字和连字符，长度为 3–63 个字符。

响应（201）：

{
  "id": 12345678,
  "name": "boreal-enigma",
  "status": "provisioning",
  "gatewayToken": "pending",
  "accessToken": "eyJhbGci...",
  "expiresAt": "2026-03-11T10:00:00.000Z"
}

保存 id、name 和 accessToken。

2. 轮询直到运行

const { id, name, accessToken } = await res.json();

let instance;
for (let elapsed = 0; elapsed < 600; elapsed += 15) {
  await new Promise((r) => setTimeout(r, 15000));
  const poll = await fetch(`https://api.agentbox.fyi/provision/${id}`, {
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  instance = await poll.json();
  console.log(`[${elapsed}s] status=${instance.status} step=${instance.provisioningStep || "-"}`);
  if (instance.status === "running") break;
  if (instance.status === "error" || instance.status === "deleted") {
    throw new Error(`Provisioning failed: ${instance.status}`);
  }
}

每隔 15 秒轮询一次。启动需要 2–4 分钟，10 分钟后超时。

状态依次为：provisioning -> minting -> running。minting 状态持续时间很短（正在铸造 SATI NFT）。响应还包含 provisioningStep 字段，其中记录了更详细的子状态（vm_created、configuring、wallet_created、openclaw_ready、services_starting）。

当 status 为 "running" 时，响应中会包含真实的 gatewayToken：

{
  "status": "running",
  "gatewayToken": "a58310a5f1f07...",
  "chatUrl": "https://boreal-enigma.agentbox.fyi/chat#token=...",
  "terminalUrl": "https://boreal-enigma.agentbox.fyi/terminal/..."
}

保存 gatewayToken，用于 API 交互。

3. 聊天补全

使用虚拟机上的 OpenAI 兼容 API 发送消息：

curl -s https://NAME.agentbox.fyi/v1/chat/completions \
  -H "Authorization: Bearer GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello, what can you do?"}]}'

将 NAME 替换为实例名称，并将 GATEWAY_TOKEN 替换为轮询响应中的 gatewayToken。返回标准的 OpenAI 聊天补全 JSON（非流式）。

每个请求都是无状态的。对于多轮对话，请附上完整的消息历史：

curl -s https://NAME.agentbox.fyi/v1/chat/completions \
  -H "Authorization: Bearer GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messages": [
    {"role": "user", "content": "What is 2+2?"},
    {"role": "assistant", "content": "4"},
    {"role": "user", "content": "Multiply that by 10"}
  ]}'

响应还包含示例中未显示的其他字段（ownerWallet、ip、vmWallet、nftMint、terminalToken、provisioningStep、createdAt）。可安全地忽略这些字段，也可按需保存。

轮询响应中的 terminalUrl 可打开虚拟机的 Web 终端，并访问其 Shell。

续期

增加 7 天有效期（5 美元 USDC）。复用步骤 1 中的 x402 客户端：

const res = await x402Fetch("https://api.agentbox.fyi/provision/INSTANCE_ID/extend", {
  method: "POST",
  headers: { Authorization: "Bearer ACCESS_TOKEN" },
});

返回更新后的实例，其中包含新的 expiresAt 和 accessToken。最长有效期：90 天。

列出实例

通过 Ed25519 签名列出钱包拥有的所有实例：

import { readFileSync } from "node:fs";
import { createKeyPairFromBytes, signBytes, getAddressFromPublicKey } from "@solana/kit";

const keypairBytes = new Uint8Array(JSON.parse(readFileSync("/path/to/wallet.json", "utf8")));
const keyPair = await createKeyPairFromBytes(keypairBytes);
const address = await getAddressFromPublicKey(keyPair.publicKey);
const timestamp = Date.now();
const message = `List AgentBox instances\nTimestamp: ${timestamp}`;
const signature = await signBytes(keyPair.privateKey, new TextEncoder().encode(message));
const sig64 = Buffer.from(signature).toString("base64");

const res = await fetch(
  `https://api.agentbox.fyi/provision?wallet=${address}&signature=${encodeURIComponent(sig64)}&timestamp=${timestamp}`
);

返回 { instances: [...] }，其中包含运行中实例的 gatewayToken 和 terminalToken（通过钱包签名进行身份验证——只有钱包所有者才能列出自己的实例）。时间戳必须在服务器时间前后 5 分钟以内。

错误

HTTP	含义
402	需要付款（由 x402 自动处理）
409	实例名称已被占用
502	配置实例失败（不会向你收费）
401	缺少或无效的访问令牌
404	找不到实例

付款详情

• **网络：**Solana 主网（solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp）
• **金额：**每 7 天 5 美元 USDC
• **资产：**USDC（EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v）

如果配置实例失败（502），付款不会结算。