agentbox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AgentBox

Provision a dedicated AI agent by paying $5 USDC (Solana) via x402. Each agent runs an OpenClaw AI gateway with HTTPS, web terminal, and Solana wallet. Instances last 7 days (extendable).

Base URL:

https://api.agentbox.fyi

通过x402支付5 USDC（Solana链）部署专属AI Agent。每个Agent运行搭载HTTPS、网页终端和Solana钱包的OpenClaw AI网关。实例有效期7天（可续期。

Base URL:

https://api.agentbox.fyi

Prerequisites

前置要求

bash

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

Requires a Solana wallet file (

solana-keygen

JSON format: 64-byte array) with USDC funds.

bash

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

需要Solana钱包文件（

solana-keygen

JSON格式：64字节数组），且钱包内有USDC余额。

1. Provision

1. 部署

Create

provision.mjs

and run with

node provision.mjs /path/to/wallet.json [name]

javascript

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));

Pays $5 USDC automatically via x402. Name is optional (auto-generated if omitted), must be DNS-safe: lowercase alphanumeric + hyphens, 3-63 chars.

Response (201):

json

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

Save

id

name

, and

accessToken

创建

provision.mjs

文件，执行命令

node provision.mjs /path/to/wallet.json [name]

运行：

javascript

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）：

json

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

请保存

id

、

name

和

accessToken

。

2. Poll until running

2. 轮询状态直到实例运行

javascript

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}`);
  }
}

Poll every 15 seconds. Boot takes 2-4 minutes, timeout after 10 minutes.

Status progression:

provisioning

minting

running

. The

minting

state is brief (SATI NFT minting). The response also includes a

provisioningStep

field with granular sub-states (

vm_created

configuring

wallet_created

openclaw_ready

services_starting

When

status

"running"

, the response includes the real

gatewayToken

json

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

Save

gatewayToken

for API interaction.

javascript

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 minting过程）。响应还包含

provisioningStep

字段，提供更细粒度的子状态（

vm_created

、

configuring

、

wallet_created

、

openclaw_ready

、

services_starting

）。

当

status

为

"running"

时，响应会包含真实的

gatewayToken

：

json

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

请保存

gatewayToken

用于后续API交互。

3. Chat completions

3. 聊天补全

Send messages using the OpenAI-compatible API on the VM:

bash

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?"}]}'

Replace

NAME

with the instance name and

GATEWAY_TOKEN

with

gatewayToken

from the poll response. Returns standard OpenAI chat completions JSON (non-streaming).

Each request is stateless. For multi-turn conversations, include the full message history:

bash

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"}
  ]}'

The response also includes additional fields beyond those shown in examples (

ownerWallet

ip

vmWallet

nftMint

terminalToken

provisioningStep

createdAt

). These can be safely ignored or stored as needed.

terminalUrl

from the poll response opens a web terminal with shell access to the VM.

通过实例上兼容OpenAI的API发送消息：

bash

curl -s https://NAME.agentbox.fyi/v1/chat/completions \
  -H "Authorization: Bearer GATEWAY_TOKEN" \
  -H "Content-Type": "running"

将

NAME

替换为你的实例名称，

GATEWAY_TOKEN

替换为轮询响应中获取的

gatewayToken

。返回标准的OpenAI聊天补全JSON（非流式）。

每个请求都是无状态的。多轮对话需要包含完整的消息历史：

bash

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

可以打开网页终端，获得VM的shell访问权限。

Extend

续期

Add 7 more days ($5 USDC). Reuse the x402 client from step 1:

javascript

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

Returns updated instance with new

expiresAt

and

accessToken

. Maximum lifetime: 90 days.

新增7天使用时长（费用5 USDC）。复用步骤1中的x402客户端即可：

javascript

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

返回更新后的实例信息，包含新的

expiresAt

和

accessToken

。实例最长有效期：90天。

List instances

实例列表

List all instances owned by your wallet via Ed25519 signature:

javascript

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}`
);

Returns

{ instances: [...] }

including

gatewayToken

and

terminalToken

for running instances (authenticated by wallet signature - only the wallet owner can list their own instances). Timestamp must be within 5 minutes of server time.

通过Ed25519签名查询你的钱包拥有的所有实例：

javascript

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分钟以内。

Errors

错误码

HTTP	Meaning
402	Payment required (handled automatically by x402)
409	Instance name already taken
502	Provisioning failed (you are NOT charged)
401	Missing or invalid access token
404	Instance not found

HTTP	含义
402	需要支付（由x402自动处理）
409	实例名称已被占用
502	部署失败（不会扣费）
401	访问令牌缺失或无效
404	实例不存在

Payment details

支付详情

Network: Solana mainnet (
```
solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
```
)
Amount: $5 USDC per 7-day period

Asset: USDC (

EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

)

If provisioning fails (502), the payment is NOT settled.

网络： Solana主网 (
```
solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
```
)
金额： 每7天5 USDC

资产： USDC (

EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

)

如果部署失败（502错误），支付不会结算。