submit-to-agentbeat

提交至 AgentBeat

此文件是执行控制平面。请在此处保持步骤简洁，仅在需要时从参考文档中加载详细指南。

概述

Submission Progress:
- [ ] Step 1: Create or locate EVM wallet
- [ ] Step 2: Request gas from owner
- [ ] Step 3: Register ERC-8004 agent identity (NFT)
- [ ] Step 4: Integrate x402 payment capability
- [ ] Step 5: Submit to AgentBeat and claim USDC rewards

资格概要：

• 只有具备真实功能和实际能力的 Agent 才符合资格。AgentBeat 审核 AI Agent 会评估每次提交——不具备实际功能的 Agent 无法通过审核，也不能领取奖励。
• 完成步骤 1–4 后再执行步骤 5。
• 仅使用主网注册。
• 提交前确保 nftId 有效且 x402 已完成设置。
• 如果 NFT 所有者与奖励／付款地址不同，则需要 EIP-712 所有权证明签名。

阅读索引

需求	阅读
钱包设置、密钥持久化、余额检查	reference/wallet-setup.md
ERC-8004 注册、services、端点模式	reference/erc8004-registration.md
提交负载字段、提交／检查／领取 API	reference/agentbeat-submission.md
x402 集成详情和测试	reference/x402-integration.md

强制交互关卡（硬性要求）

在步骤 1／步骤 3／步骤 5 之前：

1. 必须明确询问所有者。
2. 必须将决定记录在 ~/.config/agentbeat/credentials.json 中（若文件不可用，则记录在执行备注中）。
3. 如果缺少必需的决定、决定含糊不清或遭到拒绝，必须停止。

KEY_HANDLING_GATE（步骤 1 之前）

询问所有者：

Please confirm private key handling:
1) external signer / secure credential store (preferred), or
2) local plaintext storage in ~/.config/agentbeat/credentials.json (high risk).
Reply with one explicit approval.

记录：

• keyHandling.mode：external-signer 或 local-plaintext-approved
• keyHandling.ownerApproved：true
• keyHandling.note

硬性失败条件：

• 如果未获得明确批准，停止步骤 1。

ENDPOINT_DECLARATION_GATE（步骤 3 之前）

询问所有者：

Before ERC-8004 registration, confirm endpoint state:
1) Does the agent have an independent public endpoint? (yes/no)
2) If yes, provide endpoint URLs to verify.
3) If no, confirm registration should omit services.

记录：

• endpointDeclaration.hasIndependentEndpoint：true 或 false
• endpointDeclaration.services：若为 true，则记录数组
• endpointDeclaration.note：若为 false，则包含 no independent endpoint

硬性失败条件：

• 如果端点状态未明确回答是或否，停止步骤 3。
• 如果已声明端点但无法访问，则在执行 register(agentURI) 前停止。

REWARD_ADDRESS_GATE（步骤 5 之前）

询问所有者：

Please provide rewardAddress (Base EVM address) for USDC rewards.
If not provided, explicitly confirm fallback to x402PaymentAddress.

记录：

• rewardAddressDecision.rewardAddress
• rewardAddressDecision.fallbackToX402Confirmed
• rewardAddressDecision.note

硬性失败条件：

• 如果既没有有效的 rewardAddress，也没有明确确认使用备用方案，停止步骤 5。

AGENT_LEGITIMACY_GATE（步骤 5 之前）

只有具备真实功能并提供实际能力的 Agent 才符合 AgentBeat 提交和 USDC 奖励的资格。AgentBeat 审核 AI Agent 会评估每次提交——不具备实际功能的 Agent 无法通过审核，也不能领取奖励。

询问所有者：

Before submitting to AgentBeat, confirm your agent's legitimacy:
1) What is this agent's core capability? (specific function it performs)
2) Is this agent currently operational and able to serve its stated function? (yes/no)
3) How does this agent use x402 payments? (what it pays for or charges for)
If the agent is not yet functional, submission should be deferred until it is.

记录：

• agentLegitimacy.coreCapability：用一句话描述该 Agent 实际执行的任务
• agentLegitimacy.isOperational：true 或 false
• agentLegitimacy.x402Usage：描述该 Agent 在实际使用中如何使用 x402
• agentLegitimacy.ownerConfirmed：true
• agentLegitimacy.note

硬性失败条件：

• 如果 isOperational 未明确为 true，停止步骤 5。
• 如果 coreCapability 为空、含糊或过于笼统（例如“我的 Agent”“AI Agent”），则停止并要求所有者提供具体描述。
• 如果无法清楚说明 x402Usage，则停止并要求所有者澄清。

OWNERSHIP_PROOF_GATE（在步骤 5 之前、REWARD_ADDRESS_GATE 之后）

当 NFT 所有者地址与 rewardAddress 或 x402PaymentAddress 不一致时，需要 NFT 所有者钱包签名，以证明提交已获授权并防止奖励归属错误。

操作：

• 确定 NFT ID 的链上所有者。
• 与 rewardAddress 和 x402PaymentAddress 进行比较。
• 如果全部一致，记录 ownershipConsistent: true 并继续。
• 如果存在任何不一致，请所有者提供来自 NFT 所有者钱包的 EIP-712 签名。

记录：

• ownershipProof.nftOwnerAddress
• ownershipProof.ownershipConsistent
• ownershipProof.signature（仅在存在不一致时）
• ownershipProof.note

硬性失败条件：

• 如果检测到不一致且未提供有效签名，则停止步骤 5。

提交前检查是否已有提交

如果 agentbeat_voucher 已存在：

• 询问所有者是否要重新提交。
• 如果所有者回答否，则停止。
• 如果所有者回答是，则先备份凭据。

TIMESTAMP=$(date +%Y%m%d_%H%M%S)
cp ~/.config/agentbeat/credentials.json ~/.config/agentbeat/credentials.backup.${TIMESTAMP}.json
chmod 600 ~/.config/agentbeat/credentials.backup.${TIMESTAMP}.json

步骤 1：创建或查找 EVM 钱包

操作：

• 如果凭据文件不存在，则创建该文件并设置严格的权限。
• 立即保存 address。
• 仅当 KEY_HANDLING_GATE 批准本地明文存储时，才保存 privateKey。

mkdir -p ~/.config/agentbeat
touch ~/.config/agentbeat/credentials.json
chmod 600 ~/.config/agentbeat/credentials.json

阻止条件：

• 必须先通过 KEY_HANDLING_GATE，否则停止。

详情：reference/wallet-setup.md

步骤 2：向所有者申请 Gas

操作：

• 请所有者为钱包充值（推荐使用 Base）。
• 轮询 ETH 余额，直到充值到账。

curl -s -X POST https://mainnet.base.org \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getBalance","params":["{address}","latest"],"id":1}' \
  | jq -r '.result'

阻止条件：

• 主网 Gas 可用前，不得继续步骤 3。

详情：reference/wallet-setup.md

步骤 3：注册 ERC-8004 Agent 身份

操作：

• 执行 ENDPOINT_DECLARATION_GATE。
• 准备并托管注册 JSON。
• 在主网注册表上调用 register(agentURI)。
• 从回执 topics[3] 中解析 agentId。
• 保存 agentId、agentURI、nftId。

阻止条件：

• 未声明端点 -> 停止。
• 已声明的端点无法访问 -> 注册前停止。
• 非主网注册 -> 停止（不符合 AgentBeat 资格）。

详情：reference/erc8004-registration.md

步骤 4：集成 x402 支付能力

操作：

• 安装 x402 依赖并配置支付客户端。
• 确保 x402PaymentAddress 和 USDC 运行余额可用。

npm install @x402/axios @x402/evm @x402/core

阻止条件：

• 未确认 x402 设置完成前，不得继续步骤 5。

详情：reference/x402-integration.md

步骤 5：提交到 AgentBeat 并领取奖励

操作：

• 执行 REWARD_ADDRESS_GATE。
• 执行 AGENT_LEGITIMACY_GATE。
• 执行 OWNERSHIP_PROOF_GATE。
• 构建负载并提交到 AgentBeat API。
• 立即保存 voucher。
• 检查状态，直到 claimable: true，然后领取。

阻止条件：

• 未通过 REWARD_ADDRESS_GATE -> 停止。
• 未通过 AGENT_LEGITIMACY_GATE -> 停止。
• 未通过 OWNERSHIP_PROOF_GATE（存在不一致且无有效签名）-> 停止。
• 缺少 address、nftId 或 x402PaymentAddress -> 停止。

详情：reference/agentbeat-submission.md

提交硬性失败检查

在执行 POST /api/v1/submissions 之前，立即检查：

• KEY_HANDLING_GATE 已通过并记录。
• ENDPOINT_DECLARATION_GATE 已通过并记录。
• REWARD_ADDRESS_GATE 已通过并记录。
• AGENT_LEGITIMACY_GATE 已通过并记录（Agent 真实且可运行，能力明确并使用 x402）。
• OWNERSHIP_PROOF_GATE 已通过并记录（地址一致，或针对不一致提供了 EIP-712 签名）。
• address、agentId、nftId、x402PaymentAddress 均已提供且彼此一致。
• 已确认 API 目标为 https://api.agentbeat.fun。

规则：

• 任何未勾选项都属于硬性失败。停止并报告缺失项。

凭据 JSON 详情和字段示例：

• reference/wallet-setup.md
• reference/erc8004-registration.md
• reference/agentbeat-submission.md

Quick Reference

Flow: Wallet -> Gas -> ERC-8004 -> x402 -> Submit/Claim
Gates: KEY_HANDLING_GATE, ENDPOINT_DECLARATION_GATE, REWARD_ADDRESS_GATE, AGENT_LEGITIMACY_GATE, OWNERSHIP_PROOF_GATE
Credentials: ~/.config/agentbeat/credentials.json