{
  "markdown": "# Arbiter\n\n**The judgment layer for autonomous agents.**\n\nAn AI agent about to act on the world often needs a judgment it cannot make by\nitself: *is this transaction safe to sign, is this counterparty real, is this\nphoto actually what it claims to be.* Arbiter sells those judgments one call at\na time, paid over [x402](https://x402.org) in USDC on Algorand.\n\nThree routes, one response contract:\n\n| Route | Judgment | Price |\n|---|---|---|\n| `POST /v1/judge/transaction` | Machine — decode and risk-score an unsigned transaction before signing | $0.002 |\n| `POST /v1/judge/counterparty` | Data — is this payment counterparty who they claim to be | $0.01 |\n| `POST /v1/judge/human` | Human — questions a model cannot settle alone, answered by vetted reviewers | $0.25 |\n\nEvery route returns the same verdict envelope, so an agent integrates one shape\nand can then ask for any kind of judgment without new branching logic:\n\n```jsonc\n{\n  \"decision\": \"block\",        // allow | warn | block | escalate\n  \"risk\": 100,                // 0-100\n  \"confidence\": 1,            // 0-1; low confidence forces \"escalate\"\n  \"findings\": [ /* itemised, each with severity, detail and source */ ],\n  \"evidence\": { /* the decoded transaction, the counterparty record */ },\n  \"meta\": { \"degraded\": false, \"latencyMs\": 378 }\n}\n```\n\n> **New here, or explaining this to someone non-technical?**\n> [What Arbiter actually does](./WHAT-IT-DOES.md) — no code, no jargon.\n\n## Live\n\n**https://arbiter-hs23.onrender.com** — API, and the reviewer app at\n[`/work`](https://arbiter-hs23.onrender.com/work/).\n\nPreflight: 18 passed, 0 blocking failures. Running on Render's free plan, which\nhas no persistent disk and spins down after 15 minutes idle — see\n[DEPLOY.md](./DEPLOY.md) for what that costs and the upgrade needed before the\nOctober leaderboard window.\n\n## Status\n\n| Component | State |\n|---|---|\n| x402 payment core (Algorand, USDC, GoPlausible facilitator) | Working, verified end-to-end |\n| Bazaar discovery + `x402-global-challenge` tag | Working, verified in the 402 response |\n| `/v1/judge/transaction` Algorand firewall | Working, 5/5 attack cases pass |\n| `/v1/judge/transaction` EVM firewall | Working, 7/7 drain patterns pass, EIP-7702 aware |\n| `/v1/judge/counterparty` engine | Working, 5/5 cases pass against live mainnet + NFD |\n| `/v1/judge/human` marketplace | Working, consensus + reviewer reliability + payout ledger |\n| On-chain payout settlement | Working — real USDC paid to a reviewer on-chain |\n| SDK, MCP server, LangChain, ElizaOS, paying proxy | Built, typechecked, runtime-verified |\n| CrewAI tools (Python) | Built; runs through the paying proxy — see below |\n| KeeperHub integration | Working, real Sepolia transaction executed |\n| Reviewer app (React) | Live at `/work`, verified end-to-end with a paid question |\n\n## The transaction firewall\n\nAutonomous agents lose funds in a small number of specific ways. The firewall\ndecodes the actual transaction bytes and reports what signing would really do:\n\n- **Rekey** — `rekeyTo` permanently transfers signing authority over the account\n- **Close-remainder** — sweeps the entire ALGO balance regardless of the stated amount\n- **Asset close-out** — sweeps the entire ASA holding regardless of the stated amount\n- **Clawback** — moves assets out of a third party's account\n- **Fee drain** — the balance leaves via an oversized fee rather than a visible transfer\n- **App delete / update** — destroys or silently replaces contract logic\n- Asset-level risk: creator-held clawback and freeze authority, non-existent assets\n- Account-level risk: signer already rekeyed, unfunded recipient, expired validity window\n\nRun it against real, freshly-encoded transactions:\n\n```bash\nnpm run demo:attacks\n```\n\n```\n[BLOCK]  Rekey attack              risk=100/100  confidence=1  1365ms\n[BLOCK]  Close-remainder drain     risk=100/100  confidence=1   378ms\n[BLOCK]  Asset close-out drain     risk=100/100  confidence=1  1432ms\n[BLOCK]  Fee drain                 risk=100/100  confidence=1   379ms\n[ALLOW]  Benign payment            risk=0/100    confidence=1   398ms\n```\n\nThe benign case returning zero findings matters as much as the blocks — a\nfirewall that cries wolf gets switched off.\n\n## Counterparty verification\n\nCatches the two silent, expensive failures a payout agent cannot see by reading\nan invoice:\n\n- **Swapped payment address** — the invoice is genuine and the payee is real, but\n  the address belongs to someone else. Resolved against the NFD registry and\n  compared to every address the identity legitimately controls.\n- **Missing asset opt-in** — on Algorand an ASA transfer to an account that has\n  not opted in is rejected outright. The payment simply never arrives.\n\nPlus rekeyed recipients, frozen holdings, below-minimum balances, unregistered or\nexpired identities, and never-funded addresses.\n\n```bash\nnpm run demo:counterparty     # live NFD registry + Algorand mainnet, read-only\n```\n\nThe two cases worth reading are adjacent and opposite: an identity that\n**verifies** but whose address cannot receive the asset, and an identity that\n**fails** on an address that could. Both block, for entirely different reasons.\n\n## Human judgment\n\nQuestions a model cannot settle alone go to vetted reviewers. The paid call\nlong-polls for a bounded window; if reviewers answer in time the verdict returns\ninline, otherwise the caller gets a pending verdict and a **free** retrieval URL.\nTiming out never costs a second payment.\n\n```bash\nnpm run demo:human\n```\n\n- Majority vote across a configurable quorum, with the agreement ratio exposed\n- Confidence is agreement discounted by how proven the panel is, so a unanimous\n  answer from unproven reviewers is not treated as certainty\n- Reviewers are paid for participating, not for agreeing — paying for agreement\n  incentivises guessing the majority rather than reporting what you saw\n- Implausibly fast answers are flagged as a quality signal\n- Per-reviewer reliability accrues from consensus agreement over time\n\nWorker API (`/v1/work/*`) is unpriced: reviewers are the supply side.\n\n### Paying reviewers\n\n```bash\nnpm run settle -- --dry-run    # check everything, send nothing\nnpm run settle                 # pay\n```\n\nTwo rules govern this, and both cost something to follow:\n\n**Claim before broadcasting.** Payouts move to `settling` with an attempt id\n*before* any transaction is sent, and that attempt id is written into the\ntransaction's note field. A process that dies mid-flight therefore leaves money\nunpaid rather than paid twice — unpaid is recoverable by a person reading the\nstuck rows against the ledger, paid twice is not.\n\n**Check the payee before paying.** Every payout address goes through Arbiter's\nown `/v1/judge/counterparty` engine first. Not decoration: a USDC transfer to an\naccount that has not opted in is rejected by the protocol, so paying blind burns\na fee and leaves the reviewer unpaid with no explanation. Blocked payouts stay\npending and are retried once the reviewer opts in.\n\n```\n[PAID]  0.150000 USDC -> GBRO5EM4JM57PDPS…\n        txid  SIEXIGX6KQKA4D4PTOUL7R6M5BDP4BIUEW2TTOIFZHBU233LSKWQ\n        note  arbiter:payout:pay_msft8csu_rfq0ch\n\n[SKIP]  0.150000 USDC -> OEQWDYGTEXMDWSH2…\n        Arbiter blocked this payee: Counterparty has not opted in to the asset\n```\n\nThe payout account is configured separately from `PAY_TO` on purpose. `PAY_TO`\naccumulates revenue and its key never needs to be on a server; the payout\naccount holds working capital only, so a compromised host cannot drain earnings.\n\n### Design rule: the caller has already paid\n\nBy the time an engine runs, the agent has been charged. So no upstream failure\nmay throw. Every algod lookup has a hard timeout and returns a result that says\nwhether data was actually obtained; a failed lookup lowers `confidence` and sets\n`meta.degraded`, and the static decode rules — which catch the critical\nseverities — still run. A degraded verdict is still a useful verdict.\n\nSeparately, `confidence < 0.4` returns `escalate` rather than `allow`, so a\nthin-evidence verdict can never be mistaken for a clean bill of health.\n\n## Getting it into agents\n\nVolume on a usage-ranked leaderboard comes from other people's agents calling\nyou, so the clients are the product surface, not an afterthought. Full detail in\n[clients/README.md](./clients/README.md).\n\n| Package | For |\n|---|---|\n| `@arbiterlabs/sdk` | TypeScript agents; pays x402 automatically |\n| `@arbiterlabs/mcp` | Any MCP host — Claude Code, Claude Desktop, OpenClaw |\n| `@arbiterlabs/langchain` | LangChain.js tools |\n| `@arbiterlabs/eliza` | ElizaOS plugin |\n| `@arbiterlabs/proxy` | Local paying sidecar for non-TypeScript agents |\n| `arbiter-crewai` | CrewAI (Python), via the sidecar |\n\nSpend limits live in the client rather than in advice to integrators, because an\nagent in a retry loop against a paid endpoint is a wallet-draining bug:\n\n```ts\nconst client = new ArbiterClient({\n  baseUrl: process.env.ARBITER_URL,\n  privateKey: process.env.ALGO_KEY,\n  maxPricePerCallUsd: 0.5,\n  maxTotalSpendUsd: 10,\n});\n```\n\nBoth caps are enforced in the payment selector, before anything is signed.\n\n### Why Python needs a sidecar\n\nPaying x402 on Algorand requires an AVM scheme client, and that exists only in\nTypeScript today. `x402` 2.18 ships no AVM client, and `x402-avm` 2.0.2 — despite\nthe name — ships none either, has no `algosdk` dependency, and installs *into\nthe `x402` namespace*, overwriting the base package. So a Python agent cannot\nconstruct an Algorand x402 payment at all.\n\n`@arbiterlabs/proxy` therefore holds the key, pays, and re-exposes the judgments\nunpriced on loopback. That is also the better arrangement in general: one\nprocess holds the funded key and enforces one budget, instead of every agent\nprocess carrying a copy of both.\n\n## Setup\n\n```bash\nnpm install\ncp .env.example .env    # then set PAY_TO\nnpm run dev\n```\n\n`PAY_TO` must be a real Algorand address **opted in to the USDC ASA** for the\nnetwork you are running (testnet `10458941`, mainnet `31566704`), or settlement\nfails.\n\nVerify the payment gate:\n\n```bash\ncurl -i -X POST http://localhost:4021/v1/judge/transaction \\\n  -H 'content-type: application/json' \\\n  -d '{\"chain\":\"algorand\",\"transaction\":\"abc\"}'\n```\n\nExpect `HTTP 402` with a base64 `PAYMENT-REQUIRED` header carrying the price,\nasset, `payTo`, `feePayer` and the Bazaar discovery schema.\n\n## A note on the facilitator network identifier\n\nThe GoPlausible facilitator advertises Algorand using the **full padded base64\ngenesis hash** as the CAIP-2 reference:\n\n```\nalgorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=\n```\n\nwhile `@x402/avm`'s `ALGORAND_TESTNET_CAIP2` uses the CAIP-2-legal 32-character\ntruncation:\n\n```\nalgorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDe\n```\n\nBoth normalize to the same network inside the AVM scheme, but the resource\nserver validates route configuration against the facilitator's advertised\nstrings by exact equality — so using the SDK constant fails startup with\n`missing_facilitator`. `src/facilitator.ts` resolves the identifier from\n`/supported` at boot and matches by normalization, which works with either form\nand will keep working if the padding is fixed upstream. It also picks up the\nadvertised `feePayer`, so callers can pay in USDC without holding ALGO for gas.\n\n## Competition configuration\n\nBuilt for the [Algorand Global x402 Challenge](https://algorand.co/global-x402-challenge)\nas a **Composite Entry**: all three routes share one `payTo`, so their volume\nrolls up into a single merchant entry while each route stays individually\ndiscoverable in the Bazaar.\n\nRequirements wired in and verified in the live 402 response:\n\n- [x] Paid endpoint returning HTTP 402 without payment\n- [x] GoPlausible facilitator (not an alternative facilitator)\n- [x] Bazaar discovery extension with per-route input/output schemas\n- [x] `x402-global-challenge` tag on every route\n- [x] Single consistent `payTo` across all routes\n- [x] Deployed to public HTTPS on MainNet\n- [x] One real MainNet payment settled, USDC confirmed received\n- [x] Listed on the Algorand MainNet USDC leaderboard\n\nThe first settled MainNet payment was\n[`IUTXAWFK…`](https://lora.algokit.io/mainnet/transaction/IUTXAWFKZUJNDPC222U6EKKDWP5DB5JWHWAATTCBK3R5O7M7XZBQ):\n0.002 USDC (ASA 31566704) in round 63,807,235, verified on the indexer rather\nthan taken from the settlement response.\n\nAttribution is by `payTo` address. The leaderboard exposes no tag filter, so the\n`x402-global-challenge` tag aids Bazaar discovery but does not gate scoring —\n`npm run preflight -- <url>` now confirms the listing directly instead of\ninferring it from the tag.\n\n`assertChallengeReady()` fails startup if a mainnet deployment is still pointing\nat localhost or plain HTTP.\n",
  "bytes": 12745,
  "sha": "5e465c5095c3a68ecbb897ab9c27f76babf5220ec5729e02a6475d0f6af6790f",
  "repo_slug": "godwin105/arbiter_ai",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_godwin105_arbiter_e1e04bb4/readme"
}