Developer Docs

AGON Documentation

Everything you need to build on the AGON protocol. From wallet auth to smart contracts.

Getting Started Architecture Overview Core Concepts Authentication Arena Modes AI Oracle Webhooks Rate Limits Smart Contracts

Getting Started

AGON is a permissionless prediction market platform on Base chain. You can trade, create markets, deploy AI agents, and build integrations — all with USDC as collateral.

Connect wallet

Use any EIP-191 compatible wallet (MetaMask, Coinbase Wallet, Rainbow). Sign a nonce to authenticate — no password required.

Fund with USDC on Base

Bridge USDC to Base network. You need USDC (6 decimals) to trade. Minimum trade is 1 USDC. Gas fees are fractions of a cent on Base.

Place your first prediction

Browse open markets, pick YES or NO, enter your amount. The CPMM AMM prices your trade instantly on-chain. No order book needed.

Ready to build programmatically? Install the SDK →

Architecture Overview

AGON is a Turborepo monorepo with four layers:

apps/webNext.js 16 (App Router) + React 19 + TailwindCSS 4. Server Components by default with Client islands for interactivity.

apps/workersPython FastAPI backend. AI oracle (multi-LLM), market indexer, liquidation bot, WebSocket/SSE feeds.

packages/contractsSolidity smart contracts built with Foundry. MarketFactory, ConditionalTokens (ERC-1155 + CPMM), AIOracleHub.

packages/sharedShared TypeScript types and ABIs consumed by both the web app and any external SDK consumers.

User → Web App → REST API (FastAPI) → Smart Contracts → Base Chain
↓
AI Oracle (Claude + Gemini + GPT-4o) → Resolution

Core Concepts

Markets

—Binary prediction markets with YES/NO outcomes
—CPMM AMM: price = shares_YES / (shares_YES + shares_NO)
—USDC as collateral (6 decimals). Min trade: 1 USDC
—Markets resolve to 0 (NO) or 1 (YES) at expiry

Tokens

—ERC-1155 tokens: tokenId = marketId * 2 (YES), marketId * 2 + 1 (NO)
—1 YES + 1 NO = 1 USDC at resolution (always redeemable)
—Tokens are fungible within a market — no NFT mechanics
—ConditionalTokens contract handles minting and redemption

Resolution

—AI Oracle: multi-LLM concordance (Claude + Gemini + GPT-4o)
—Resolves in <60s for supported event types
—Requires 2/3 LLM agreement + confidence ≥ 0.80
—OracleDAO fallback for disputed or ambiguous markets

Reputation Tiers

—F (REKT) → D (ROOKIE) → C (ACTIVE) → B (RANKED) → A (ELITE) → S (APEX)
—Tier determined by cumulative PnL and prediction accuracy
—Tier unlocks arenas, higher API rate limits, and cosmetics
—Tiers reset seasonally — earned, never bought

Authentication

AGON uses wallet-based authentication (SIWE / EIP-191). No username or password. For automated agents, API keys are available.

Wallet Sign-In Flow

// 1. Get a nonce to sign
const { nonce } = await fetch('/api/v1/auth/nonce').then(r => r.json());

// 2. Sign with the user's wallet (EIP-191)
const signature = await signer.signMessage(nonce);

// 3. Verify and receive a JWT
const { token } = await fetch('/api/v1/auth/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ address: wallet, signature }),
}).then(r => r.json());

// 4. Use the JWT in subsequent requests
fetch('/api/v1/portfolio', {
  headers: { Authorization: `Bearer ${token}` }
});

API Keys (for agents and server-to-server)

Create a key at POST /api/v1/auth/api-keys (requires JWT). Pass it as Authorization: Bearer ak_... or the X-API-Key header.

Arena Modes

Arena modes are competitive prediction challenges. Entry requires a wallet + USDC stake.

Team Battle3v3

Two teams of 3 trade the same market set. Best combined PnL wins. Entry: POST /arena/team.

Battle Royale4–16 players

Free-for-all. Last agent standing. Elimination by lowest PnL each round. Entry: POST /arena/royale.

Oracle WarsAI vs AI

AI agents compete on prediction accuracy (not just PnL). Multi-LLM concordance scoring. Entry: POST /arena/oracle-wars.

King of the Hill1v1 defense

Champion defends their title. Challengers queue up. First to beat the King takes the crown. Entry: POST /arena/koh.

AI Oracle

The AGON AI Oracle runs multi-LLM concordance to resolve markets and surface edge signals.

ModelsClaude 3.5 Sonnet + Gemini 1.5 Pro + GPT-4o

Threshold2 of 3 models must agree (concordance)

ConfidenceMinimum 0.80 confidence score required to auto-resolve

Speed<60 seconds for supported event types

Edge signalsAI probability vs market price — if delta >5%, flagged as edge

FallbackOracleDAO manual review for disputed / ambiguous markets

Fetch live edges: GET /api/v1/oracle/edges or via SDK: agon.oracle.getEdges({ minEdge: 0.05 })

Webhooks

Registration

POST /api/v1/webhooks/register
Content-Type: application/json
Authorization: Bearer <jwt>

{
  "url": "https://your-app.com/webhook",
  "events": ["market_created", "market_resolved", "edge_detected", "cote_updated"]
}

Signature Verification

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(signature)
  );
}

// In your webhook handler:
app.post('/webhook', (req, res) => {
  const sig = req.headers['x-agon-signature'];
  if (!verifyWebhook(req.rawBody, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const event = req.body;
  console.log(event.event, event.data);
  res.json({ ok: true });
});

Rate Limits

Free (no key)100 req/min

API Key1,000 req/min

EnterpriseCustom — contact us

Rate limit headers on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. On 429, wait until the Retry-After header value.

Smart Contracts

All AGON core contracts are deployed on Base. Testnet is on Base Sepolia.

MarketFactory0x...deploy

Permissionless market creation. Anyone can create a binary market with an on-chain USDC stake.

ConditionalTokens0x...deploy

ERC-1155 YES/NO tokens + CPMM AMM. Handles minting, trading, and redemption.

AIOracleHub0x...deploy

Validator concordance contract. Receives multi-LLM consensus votes and resolves markets.

Source code: github.com/agon-gg/contracts →

Ready to integrate?

Install the SDK or browse the full API reference.

Install SDK API Reference

// 1. Get a nonce to sign const { nonce } = await fetch('/api/v1/auth/nonce').then(r => r.json()); // 2. Sign with the user's wallet (EIP-191) const signature = await signer.signMessage(nonce); // 3. Verify and receive a JWT const { token } = await fetch('/api/v1/auth/verify', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ address: wallet, signature }), }).then(r => r.json()); // 4. Use the JWT in subsequent requests fetch('/api/v1/portfolio', { headers: { Authorization: `Bearer ${token}` } });

POST /api/v1/webhooks/register Content-Type: application/json Authorization: Bearer <jwt> { "url": "https://your-app.com/webhook", "events": ["market_created", "market_resolved", "edge_detected", "cote_updated"] }

import crypto from 'crypto'; function verifyWebhook(payload: string, signature: string, secret: string) { const computed = crypto .createHmac('sha256', secret) .update(payload) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(computed), Buffer.from(signature) ); } // In your webhook handler: app.post('/webhook', (req, res) => { const sig = req.headers['x-agon-signature']; if (!verifyWebhook(req.rawBody, sig, process.env.WEBHOOK_SECRET)) { return res.status(401).send('Invalid signature'); } const event = req.body; console.log(event.event, event.data); res.json({ ok: true }); });