Submit To Agentbeat

Submit to AgentBeat

This file is the control plane for execution. Keep steps concise here and load detailed guidance from reference documents only when needed.

Overview

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

Eligibility summary:

• Only real, functional agents with genuine capability are eligible. AgentBeat reviewer AI agents evaluate every submission — agents without real functionality will not pass review and cannot claim rewards.
• Complete Steps 1-4 before Step 5.
• Use mainnet registration only.
• Ensure valid nftId and x402 setup before submission.
• If NFT owner differs from reward/payment addresses, an EIP-712 ownership proof signature is required.

Read Map

Mandatory Interaction Gates (Hard Requirements)

Before Step 1 / Step 3 / Step 5:

1. Must ask owner explicitly.
2. Must record decision in ~/.config/agentbeat/credentials.json (or execution note if file unavailable).
3. Must stop if required decision is missing, ambiguous, or denied.

KEY_HANDLING_GATE (before Step 1)

Ask owner:

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.

Record:

• keyHandling.mode: external-signer or local-plaintext-approved
• keyHandling.ownerApproved: true
• keyHandling.note

Hard fail:

• If no explicit approval, stop Step 1.

ENDPOINT_DECLARATION_GATE (before Step 3)

Ask owner:

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.

Record:

• endpointDeclaration.hasIndependentEndpoint: true or false
• endpointDeclaration.services: array if true
• endpointDeclaration.note: include no independent endpoint if false

Hard fail:

• If endpoint state is not explicitly yes/no, stop Step 3.
• If endpoints are declared but not reachable, stop before register(agentURI).

REWARD_ADDRESS_GATE (before Step 5)

Ask owner:

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

Record:

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

Hard fail:

• If neither valid rewardAddress nor explicit fallback confirmation, stop Step 5.

AGENT_LEGITIMACY_GATE (before Step 5)

Only real, functional agents that provide genuine capability are eligible for AgentBeat submission and USDC rewards. AgentBeat reviewer AI agents evaluate every submission — agents that lack real functionality will not pass review and cannot claim rewards.

Ask owner:

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.

Record:

• agentLegitimacy.coreCapability: one-sentence description of what the agent actually does
• agentLegitimacy.isOperational: true or false
• agentLegitimacy.x402Usage: how the agent uses x402 in practice
• agentLegitimacy.ownerConfirmed: true
• agentLegitimacy.note

Hard fail:

• If isOperational is not explicitly true, stop Step 5.
• If coreCapability is empty, vague, or generic (e.g. "my agent", "AI agent"), stop and ask owner to provide a specific description.
• If x402Usage cannot be articulated, stop and ask owner to clarify.

OWNERSHIP_PROOF_GATE (before Step 5, after REWARD_ADDRESS_GATE)

When the NFT owner address differs from rewardAddress or x402PaymentAddress, a signature from the NFT owner wallet is required to prove authorized submission and prevent reward misattribution.

Action:

• Determine the on-chain owner of the NFT ID.
• Compare with rewardAddress and x402PaymentAddress.
• If all match, record ownershipConsistent: true and proceed.
• If any mismatch, ask owner for an EIP-712 signature from the NFT owner wallet.

Record:

• ownershipProof.nftOwnerAddress
• ownershipProof.ownershipConsistent
• ownershipProof.signature (only when mismatch)
• ownershipProof.note

Hard fail:

• If mismatch detected and no valid signature provided, stop Step 5.

Pre-check Existing Submission

If agentbeat_voucher already exists:

• Ask owner whether to re-submit.
• If owner says no, stop.
• If owner says yes, backup credentials first.

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

Step 1: Create or Locate EVM Wallet

Action:

• Create credentials file if missing and set strict permissions.
• Save address immediately.
• Store privateKey only if KEY_HANDLING_GATE approved local plaintext.

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

Block:

• KEY_HANDLING_GATE must pass first, otherwise stop.

Details: reference/wallet-setup.md

Step 2: Request Gas from Owner

Action:

• Ask owner to fund wallet (Base recommended).
• Poll ETH balance until funded.

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'

Block:

• Do not proceed to Step 3 until mainnet gas is available.

Details: reference/wallet-setup.md

Step 3: Register ERC-8004 Agent Identity

Action:

• Execute ENDPOINT_DECLARATION_GATE.
• Prepare and host registration JSON.
• Call register(agentURI) on mainnet registry.
• Parse agentId from receipt topics[3].
• Save agentId, agentURI, nftId.

Block:

• Missing endpoint declaration -> stop.
• Unreachable declared endpoint -> stop before registration.
• Non-mainnet registration -> stop (not eligible for AgentBeat).

Details: reference/erc8004-registration.md

Step 4: Integrate x402 Payment Capability

Action:

• Install x402 dependencies and configure payment client.
• Ensure x402PaymentAddress and USDC operational balance.

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

Block:

• Do not proceed to Step 5 without confirmed x402 setup.

Details: reference/x402-integration.md

Step 5: Submit to AgentBeat and Claim

Action:

• Execute REWARD_ADDRESS_GATE.
• Execute AGENT_LEGITIMACY_GATE.
• Execute OWNERSHIP_PROOF_GATE.
• Build payload and submit to AgentBeat API.
• Save voucher immediately.
• Check status until claimable: true, then claim.

Block:

• REWARD_ADDRESS_GATE not passed -> stop.
• AGENT_LEGITIMACY_GATE not passed -> stop.
• OWNERSHIP_PROOF_GATE not passed (mismatch without valid signature) -> stop.
• Missing address, nftId, or x402PaymentAddress -> stop.

Details: reference/agentbeat-submission.md

Submission Hard Fail Checks

Immediately before POST /api/v1/submissions:

• KEY_HANDLING_GATE passed and recorded.
• ENDPOINT_DECLARATION_GATE passed and recorded.
• REWARD_ADDRESS_GATE passed and recorded.
• AGENT_LEGITIMACY_GATE passed and recorded (agent is real, operational, with clear capability and x402 usage).
• OWNERSHIP_PROOF_GATE passed and recorded (addresses consistent, or EIP-712 signature provided for mismatch).
• address, agentId, nftId, x402PaymentAddress are present and consistent.
• API target confirmed as https://api.agentbeat.fun.

Rule:

• Any unchecked item is a hard failure. Stop and report missing items.

Credentials JSON details and field examples:

• 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