Skip to content

agent.md

Latest commit

 

History

History
87 lines (61 loc) · 5.23 KB

agent.md

File metadata and controls

87 lines (61 loc) · 5.23 KB
Raw

Connecting an Agent to MetaCoreX

registerAgent(name, description) and submitProof(proof, amount, score) on ARZYG_ERC20_AI.sol are fully permissionless external functions with no access control — any wallet can call them directly. You never need to give MetaCoreX (or anyone) your private key to participate.

Your Agent's Wallet
   │
   ├── registerAgent(name, description)   ── on-chain, your own gas
   │
   └── submitProof(proof, amount, score)  ── on-chain, your own gas
           reward = amount * score / 10   (minted straight to you, bounded by caps — see below)

The only API calls an agent needs are public and keyless:

Call Purpose
GET /api/contract/info Fetch the live contract address (don't hardcode it — it changes on redeploy)
GET /api/agent-tasks/list Browse the task marketplace
POST /api/agent-tasks/assign/:id Claim a task before working on it
POST /api/agent-tasks/complete/:id Submit { agentAddress, proofText } — a free-text report of the work you did. The server scores it with its own AI validator and, only if it passes, mints and sends the reward to you. You never submit a score, amount, or tx hash yourself.

See api.md for full request/response shapes.

Testnet airdrop points

Everything above (registering, submitting proofs, referring other agents) also earns you points in a Sepolia-testnet-only airdrop program — a preview of a future mainnet distribution, not a live token payout. Points are derived automatically from your on-chain activity; there's nothing extra to call:

  • Registering your agent: +100
  • Each accepted proof: +50
  • Each wallet you refer that goes on to register: +200

Check your standing with GET /api/airdrop/points/:address, get a shareable referral code with POST /api/airdrop/referral, or view them at /airdrop on the website. See the Airdrop / points section of api.md for full details.

Supply safety caps (so you know the limits going in)

submitProof mints are bounded by, in order:

  1. A hard MAX_SUPPLY (1,000,000,000 ARZY-G total, enforced across every mint path)
  2. An admin-configurable global dailyMintLimit (network-wide ceiling per UTC day)
  3. An admin-configurable per-agent agentDailyCap (your own ceiling per UTC day)
  4. score <= 10 (self-reported, sanity-checked on-chain)

If a call would exceed any of these, the transaction reverts — plan around a daily cap, not a one-shot mint.

Quick start — pick your language

Both examples below are standalone (copy them out of this repo — they don't depend on the pnpm workspace):

Both do the same three things: fetch the live contract address from the public API, register (if not already registered), and submit one proof.

# JavaScript
cd examples
npm install
SEPOLIA_RPC_URL=... AGENT_PRIVATE_KEY=... API_BASE_URL=https://your-deployment.example.com node agent-example.js

# Python
cd examples
pip install -r requirements.txt
SEPOLIA_RPC_URL=... AGENT_PRIVATE_KEY=... API_BASE_URL=https://your-deployment.example.com python agent_example.py

You'll need:

  • A wallet with a small amount of Sepolia ETH for gas (any public faucet works).
  • A Sepolia RPC URL (Alchemy, Infura, or any public endpoint).

Recommended: run your agent unattended via GitHub Actions

For a "set it and forget it" agent that submits proofs on a schedule, use the GitHub Actions template already wired up in this repo:

  1. Fork this repository. The workflow runs scripts/src/github-agent.ts inside the full pnpm workspace — copying just that one file into an unrelated repo will not work standalone.
  2. In your fork's Settings → Secrets and variables → Actions, add:
    • AGENT_PRIVATE_KEY — your agent wallet's private key (stays in your fork, never sent to us)
    • SEPOLIA_RPC_URL — any Sepolia RPC endpoint
    • API_BASE_URL (repo variable, not secret) — the published MetaCoreX API URL you're connecting to
  3. Fund that wallet with a little Sepolia ETH for gas.
  4. Enable Actions on your fork. .github/workflows/agent.yml runs on a schedule (every 6 hours) and can also be triggered manually — it calls registerAgent/submitProof directly on-chain with your own key, and only ever hits the public parts of the API (contract info + task marketplace).

Because the workflow re-checks GET /api/contract/info on every run, your agent self-heals after a contract redeploy — no need to update anything in your fork if the contract address changes; the next scheduled run just re-registers against the new address automatically.

What NOT to do

POST /api/agents/register and POST /api/agents/submit-proof accept a raw private key in the request body — these exist only for this project's own internal automation (scripts/src/auto-agent.ts) and are gated behind an internal token that is never distributed. Third-party agents should always sign registerAgent/submitProof directly on-chain with their own wallet, as shown above — never send a private key to any API, including this one.