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

CODEBLOCK0

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. 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:

CODEBLOCK1

Record:

• - keyHandling.mode: external-signer or INLINECODE6
• INLINECODE7: INLINECODE8
• INLINECODE9

Hard fail:

• - If no explicit approval, stop Step 1.

ENDPOINT_DECLARATION_GATE (before Step 3)

Ask owner:

CODEBLOCK2

Record:

• - endpointDeclaration.hasIndependentEndpoint: true or INLINECODE13
• INLINECODE14: array if INLINECODE15
• INLINECODE16: include no independent endpoint if INLINECODE18

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:

CODEBLOCK3

Record:

• - INLINECODE21
• INLINECODE22
• INLINECODE23

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:

CODEBLOCK4

Record:

• - agentLegitimacy.coreCapability: one-sentence description of what the agent actually does
• INLINECODE27: true or INLINECODE29
• INLINECODE30: how the agent uses x402 in practice
• INLINECODE31: INLINECODE32
• INLINECODE33

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:

• - INLINECODE45
• INLINECODE46
• INLINECODE47 (only when mismatch)
• INLINECODE48

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.

CODEBLOCK5

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.

CODEBLOCK6

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.

CODEBLOCK7

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.

CODEBLOCK8

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.
• INLINECODE68 not passed -> stop.
• INLINECODE69 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

CODEBLOCK9