Loading...
Loading...
Compare original and translation side by side
| Need | Recommended path |
|---|---|
| Agent pays a 402-gated API on Base or another agentwallet-supported chain | Use |
| Agent pays a 402-gated API on X Layer | Use OKX Agent Payments Protocol from |
| TypeScript API charges agents | Use OKX Payments TypeScript seller SDK docs for Express, Hono, Fastify, or Next.js |
| Go API charges agents | Use OKX Payments Go seller SDK docs for Gin, Echo, or |
| Rust API charges agents | Use OKX Payments Rust seller SDK docs for Axum |
| Java API charges agents | Use OKX Payments Java seller SDK docs for Spring Boot 2/3, Java EE, or Jakarta |
| Python API charges agents | Check the current OKX Payments repository before implementation; a Python seller guide may not be available |
| 需求 | 推荐路径 |
|---|---|
| Agent在Base链或其他agentwallet-sdk支持的链上访问402管控的API | 使用 |
| Agent在X Layer链上访问402管控的API | 使用 |
| TypeScript API向Agent收费 | 参考OKX Payments TypeScript卖家SDK文档,支持Express、Hono、Fastify或Next.js |
| Go API向Agent收费 | 参考OKX Payments Go卖家SDK文档,支持Gin、Echo或 |
| Rust API向Agent收费 | 参考OKX Payments Rust卖家SDK文档,支持Axum |
| Java API向Agent收费 | 参考OKX Payments Java卖家SDK文档,支持Spring Boot 2/3、Java EE或Jakarta |
| Python API向Agent收费 | 实施前请查看OKX Payments当前仓库;Python卖家指南可能尚未提供 |
agentwallet-sdkeip155:196agentwallet-sdkeip155:196402402SpendingPolicySpendingPolicySecurity note: Always pin the package version. This tool manages private keys — unpinnedinstalls introduce supply-chain risk.npx
安全提示:始终固定包版本。该工具管理私钥 — 未固定版本的安装会引入供应链风险。npx
{
"mcpServers": {
"agentpay": {
"command": "npx",
"args": ["agentwallet-sdk@6.0.0"]
}
}
}{
"mcpServers": {
"agentpay": {
"command": "npx",
"args": ["agentwallet-sdk@6.0.0"]
}
}
}| Tool | Purpose |
|---|---|
| Check agent wallet balance |
| Send payment to address or ENS |
| Query remaining budget |
| Audit trail of all payments |
Note: Spending policy is set by the orchestrator before delegating to the agent — not by the agent itself. This prevents agents from escalating their own spending limits. Configure policy viain your orchestration layer or pre-task hook, never as an agent-callable tool.set_policy
| 工具 | 用途 |
|---|---|
| 检查Agent钱包余额 |
| 向地址或ENS发送支付 |
| 查询剩余预算 |
| 所有支付的审计追踪 |
注意:支出策略由编排器在委托给Agent前设置 — 而非Agent自身设置。这可防止Agent自行提升支出限额。请通过编排层或任务前钩子中的配置策略,切勿将其设为Agent可调用工具。set_policy
okx/onchainos-skillsskills/okx-agent-payments-protocol/SKILL.mdskills/okx-x402-payment/SKILL.md| Runtime | Current guide |
|---|---|
| TypeScript | |
| Go | |
| Rust | |
| Java | |
okx-agent-payments-protocolokx/onchainos-skillsskills/okx-agent-payments-protocol/SKILL.mdskills/okx-x402-payment/SKILL.md| 运行时 | 当前指南 |
|---|---|
| TypeScript | |
| Go | |
| Rust | |
| Java | |
okx-agent-payments-protocolPrerequisites: Install the package before adding the MCP config —withoutnpxwill prompt for confirmation in non-interactive environments, causing the server to hang:-ynpm install -g agentwallet-sdk@6.0.0
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
async function main() {
// 1. Validate credentials before constructing the transport.
// A missing key must fail immediately — never let the subprocess start without auth.
const walletKey = process.env.WALLET_PRIVATE_KEY;
if (!walletKey) {
throw new Error("WALLET_PRIVATE_KEY is not set — refusing to start payment server");
}
// Connect to the agentpay MCP server via stdio transport.
// Whitelist only the env vars the server needs — never forward all of process.env
// to a third-party subprocess that manages private keys.
const transport = new StdioClientTransport({
command: "npx",
args: ["agentwallet-sdk@6.0.0"],
env: {
PATH: process.env.PATH ?? "",
NODE_ENV: process.env.NODE_ENV ?? "production",
WALLET_PRIVATE_KEY: walletKey,
},
});
const agentpay = new Client({ name: "orchestrator", version: "1.0.0" });
await agentpay.connect(transport);
// 2. Set spending policy before delegating to the agent.
// Always verify success — a silent failure means no controls are active.
const policyResult = await agentpay.callTool({
name: "set_policy",
arguments: {
per_task_budget: 0.50,
per_session_budget: 5.00,
allowlisted_recipients: ["api.example.com"],
},
});
if (policyResult.isError) {
throw new Error(
`Failed to set spending policy — do not delegate: ${JSON.stringify(policyResult.content)}`
);
}
// 3. Use preToolCheck before any paid action
await preToolCheck(agentpay, 0.01);
}
// Pre-tool hook: fail-closed budget enforcement with four distinct error paths.
async function preToolCheck(agentpay: Client, apiCost: number): Promise<void> {
// Path 1: Reject invalid input (NaN/Infinity bypass the < comparison)
if (!Number.isFinite(apiCost) || apiCost < 0) {
throw new Error(`Invalid apiCost: ${apiCost} — action blocked`);
}
// Path 2: Transport/connectivity failure
let result;
try {
result = await agentpay.callTool({ name: "check_spending" });
} catch (err) {
throw new Error(`Payment service unreachable — action blocked: ${err}`);
}
// Path 3: Tool returned an error (e.g., auth failure, wallet not initialised)
if (result.isError) {
throw new Error(
`check_spending failed — action blocked: ${JSON.stringify(result.content)}`
);
}
// Path 4: Parse and validate the response shape
let remaining: number;
try {
const parsed = JSON.parse(
(result.content as Array<{ text: string }>)[0].text
);
if (!Number.isFinite(parsed?.remaining)) {
throw new TypeError("missing or non-finite 'remaining' field");
}
remaining = parsed.remaining;
} catch (err) {
throw new Error(
`check_spending returned unexpected format — action blocked: ${err}`
);
}
// Path 5: Budget exceeded
if (remaining < apiCost) {
throw new Error(
`Budget exceeded: need $${apiCost} but only $${remaining} remaining`
);
}
}
main().catch((err) => {
console.error(err);
process.exitCode = 1;
});前提条件:添加MCP配置前请先安装包 — 不带的-y会在非交互式环境中提示确认,导致服务器挂起:npxnpm install -g agentwallet-sdk@6.0.0
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
async function main() {
// 1. 在构建传输前验证凭据。
// 缺少密钥必须立即失败 — 绝不要让子进程在无授权的情况下启动。
const walletKey = process.env.WALLET_PRIVATE_KEY;
if (!walletKey) {
throw new Error("WALLET_PRIVATE_KEY未设置 — 拒绝启动支付服务器");
}
// 通过stdio传输连接到agentpay MCP服务器。
// 仅白名单服务器所需的环境变量 — 绝不要将所有process.env转发
// 给管理私钥的第三方子进程。
const transport = new StdioClientTransport({
command: "npx",
args: ["agentwallet-sdk@6.0.0"],
env: {
PATH: process.env.PATH ?? "",
NODE_ENV: process.env.NODE_ENV ?? "production",
WALLET_PRIVATE_KEY: walletKey,
},
});
const agentpay = new Client({ name: "orchestrator", version: "1.0.0" });
await agentpay.connect(transport);
// 2. 在委托给Agent前设置支出策略。
// 始终验证是否成功 — 静默失败意味着没有控制生效。
const policyResult = await agentpay.callTool({
name: "set_policy",
arguments: {
per_task_budget: 0.50,
per_session_budget: 5.00,
allowlisted_recipients: ["api.example.com"],
},
});
if (policyResult.isError) {
throw new Error(
`设置支出策略失败 — 请勿委托:${JSON.stringify(policyResult.content)}`
);
}
// 3. 在任何付费操作前使用preToolCheck
await preToolCheck(agentpay, 0.01);
}
// 工具前钩子:通过四个不同的错误路径实现故障关闭式预算强制执行。
async function preToolCheck(agentpay: Client, apiCost: number): Promise<void> {
// 路径1:拒绝无效输入(NaN/Infinity会绕过<比较)
if (!Number.isFinite(apiCost) || apiCost < 0) {
throw new Error(`无效的apiCost:${apiCost} — 操作已阻止`);
}
// 路径2:传输/连接失败
let result;
try {
result = await agentpay.callTool({ name: "check_spending" });
} catch (err) {
throw new Error(`支付服务不可达 — 操作已阻止:${err}`);
}
// 路径3:工具返回错误(例如,授权失败、钱包未初始化)
if (result.isError) {
throw new Error(
`check_spending失败 — 操作已阻止:${JSON.stringify(result.content)}`
);
}
// 路径4:解析并验证响应格式
let remaining: number;
try {
const parsed = JSON.parse(
(result.content as Array<{ text: string }>)[0].text
);
if (!Number.isFinite(parsed?.remaining)) {
throw new TypeError("缺少或非有限值的'remaining'字段");
}
remaining = parsed.remaining;
} catch (err) {
throw new Error(
`check_spending返回意外格式 — 操作已阻止:${err}`
);
}
// 路径5:预算超支
if (remaining < apiCost) {
throw new Error(
`预算超支:需要$${apiCost},但仅剩$${remaining}`
);
}
}
main().catch((err) => {
console.error(err);
process.exitCode = 1;
});agentwallet-sdk@6.0.0list_transactionsagentwallet-sdk@6.0.0list_transactionsagentwallet-sdkokx/paymentsokx/onchainos-skillsagentwallet-sdkokx/paymentsokx/onchainos-skills