TypeScript SDK

AGON SDK

TypeScript-first. Type-safe. Everything you need in one package.

npm install @agon/sdkNode.js 18+ / Edge runtimeBase mainnet + Sepolia

Installation

Add the SDK to your project.

SDK Quickstart

Terminal

npm install @agon/sdk

Quick Start

Connect to AGON, list markets, get oracle edges, and execute a trade in 10 lines.

import { Agon } from '@agon/sdk';

const agon = new Agon({
  apiKey: process.env.AGON_API_KEY,
  network: 'base-sepolia',
});

// List open markets
const markets = await agon.markets.list({ resolved: false, limit: 10 });

// Get AI edge opportunities
const edges = await agon.oracle.getEdges({ minEdge: 0.05 });

// Execute a trade
const trade = await agon.trade.buy({
  marketId: 42,
  outcome: 'YES',
  amountUsdc: 100,
});

Modules

The SDK is organized into modules. Each module maps to an API domain.

agon.markets

list(filters)get(id)search(query)getTrades(id, opts)

// List open markets with filters
const markets = await agon.markets.list({
  resolved: false,
  category: 'sports',
  limit: 20,
  offset: 0,
});

// Get a single market
const market = await agon.markets.get(42);

// Search by question text
const results = await agon.markets.search('Will Bitcoin hit 100k?');

// Get trade history for a market
const trades = await agon.markets.getTrades(42, { limit: 50 });

agon.trade

buy(opts)sell(opts)estimate(opts)

// Estimate before executing
const estimate = await agon.trade.estimate({
  marketId: 42,
  outcome: 'YES',
  amountUsdc: 100,
});
console.log(estimate.expectedShares, estimate.priceImpact);

// Execute buy (requires signer)
const buyTx = await agon.trade.buy({
  marketId: 42,
  outcome: 'YES',
  amountUsdc: 100,
  signer, // ethers.Signer or viem WalletClient
});

// Execute sell
const sellTx = await agon.trade.sell({
  marketId: 42,
  outcome: 'YES',
  shares: 50,
  signer,
});

agon.arena

create(opts)join(id, opts)listOpen(filters)getScore(id)

// Create a 1v1 King of the Hill challenge
const arena = await agon.arena.create({
  type: 'koh',
  marketIds: [42, 43, 44],
  stakeUsdc: 50,
  signer,
});

// Join an open arena
await agon.arena.join(arena.id, { signer });

// List open challenges
const open = await agon.arena.listOpen({ type: 'royale' });

// Get live score
const score = await agon.arena.getScore(arena.id);

agon.oracle

getAnalysis(id)getEdges(opts)getSignals()

// Full AI analysis for a market
const analysis = await agon.oracle.getAnalysis(42);
console.log(analysis.probability, analysis.confidence, analysis.reasoning);

// Markets where AI diverges >5% from price
const edges = await agon.oracle.getEdges({ minEdge: 0.05 });

// Active signals (whale, AI, meta)
const signals = await agon.oracle.getSignals();
signals.forEach(s => console.log(s.type, s.marketId, s.direction));

agon.stream

onNewMarket(cb)onTrade(id, cb)onResolution(cb)

// Subscribe to new markets (SSE)
const unsubscribe = agon.stream.onNewMarket((market) => {
  console.log('New market:', market.question);
});

// Subscribe to trades for a market
agon.stream.onTrade(42, (trade) => {
  console.log('Trade:', trade.outcome, trade.amountUsdc);
});

// Subscribe to resolutions
agon.stream.onResolution((event) => {
  console.log('Resolved:', event.marketId, event.outcome);
});

// Unsubscribe when done
unsubscribe();

Types

Key TypeScript interfaces exported from @agon/sdk.

interface Market {
  id: number;
  question: string;
  category: MarketCategory;
  yesPrice: number;      // 0-1 probability
  noPrice: number;
  totalVolume: number;   // USDC
  resolvedAt: string | null;
  outcome: 'YES' | 'NO' | null;
}

interface Trade {
  id: number;
  marketId: number;
  wallet: string;
  outcome: TradeSide;
  amountUsdc: number;
  shares: number;
  price: number;
  txHash: string;
  createdAt: string;
}

interface Position {
  marketId: number;
  outcome: TradeSide;
  shares: number;
  avgPrice: number;
  currentValue: number;
  pnl: number;
}

type MarketCategory =
  | 'sports' | 'crypto' | 'politics' | 'tech'
  | 'entertainment' | 'science' | 'other';

type TradeSide = 'YES' | 'NO';

Error Handling

The SDK throws typed errors. Catch and handle them appropriately.

import { AgonError, AgonRateLimitError, AgonAuthError } from '@agon/sdk';

try {
  const trade = await agon.trade.buy({ marketId: 42, outcome: 'YES', amountUsdc: 100, signer });
} catch (err) {
  if (err instanceof AgonRateLimitError) {
    // Automatic retry with exponential backoff
    await new Promise(r => setTimeout(r, err.retryAfterMs));
  } else if (err instanceof AgonAuthError) {
    // Token expired — re-authenticate
    await agon.auth.reconnect(signer);
  } else if (err instanceof AgonError) {
    console.error(err.code, err.message);
  }
}

Error code	When it occurs
`MARKET_CLOSED`	Market is resolved or expired
`INSUFFICIENT_BALANCE`	Wallet USDC balance too low
`SLIPPAGE_EXCEEDED`	Price moved beyond slippage tolerance
`RATE_LIMIT`	Too many requests — respect X-RateLimit-Reset
`AUTH_REQUIRED`	Endpoint requires wallet auth or API key
`INVALID_MARKET_ID`	Market does not exist
`ARENA_FULL`	Arena has reached max participant count
`PARLAY_SETTLED`	Parlay is already settled

Something missing?

Browse the full API reference or read the docs.

API Reference Documentation

import { Agon } from '@agon/sdk'; const agon = new Agon({ apiKey: process.env.AGON_API_KEY, network: 'base-sepolia', }); // List open markets const markets = await agon.markets.list({ resolved: false, limit: 10 }); // Get AI edge opportunities const edges = await agon.oracle.getEdges({ minEdge: 0.05 }); // Execute a trade const trade = await agon.trade.buy({ marketId: 42, outcome: 'YES', amountUsdc: 100, });

// List open markets with filters const markets = await agon.markets.list({ resolved: false, category: 'sports', limit: 20, offset: 0, }); // Get a single market const market = await agon.markets.get(42); // Search by question text const results = await agon.markets.search('Will Bitcoin hit 100k?'); // Get trade history for a market const trades = await agon.markets.getTrades(42, { limit: 50 });

// Estimate before executing const estimate = await agon.trade.estimate({ marketId: 42, outcome: 'YES', amountUsdc: 100, }); console.log(estimate.expectedShares, estimate.priceImpact); // Execute buy (requires signer) const buyTx = await agon.trade.buy({ marketId: 42, outcome: 'YES', amountUsdc: 100, signer, // ethers.Signer or viem WalletClient }); // Execute sell const sellTx = await agon.trade.sell({ marketId: 42, outcome: 'YES', shares: 50, signer, });

// Create a 1v1 King of the Hill challenge const arena = await agon.arena.create({ type: 'koh', marketIds: [42, 43, 44], stakeUsdc: 50, signer, }); // Join an open arena await agon.arena.join(arena.id, { signer }); // List open challenges const open = await agon.arena.listOpen({ type: 'royale' }); // Get live score const score = await agon.arena.getScore(arena.id);

// Full AI analysis for a market const analysis = await agon.oracle.getAnalysis(42); console.log(analysis.probability, analysis.confidence, analysis.reasoning); // Markets where AI diverges >5% from price const edges = await agon.oracle.getEdges({ minEdge: 0.05 }); // Active signals (whale, AI, meta) const signals = await agon.oracle.getSignals(); signals.forEach(s => console.log(s.type, s.marketId, s.direction));

// Subscribe to new markets (SSE) const unsubscribe = agon.stream.onNewMarket((market) => { console.log('New market:', market.question); }); // Subscribe to trades for a market agon.stream.onTrade(42, (trade) => { console.log('Trade:', trade.outcome, trade.amountUsdc); }); // Subscribe to resolutions agon.stream.onResolution((event) => { console.log('Resolved:', event.marketId, event.outcome); }); // Unsubscribe when done unsubscribe();

interface Market { id: number; question: string; category: MarketCategory; yesPrice: number; // 0-1 probability noPrice: number; totalVolume: number; // USDC resolvedAt: string | null; outcome: 'YES' | 'NO' | null; } interface Trade { id: number; marketId: number; wallet: string; outcome: TradeSide; amountUsdc: number; shares: number; price: number; txHash: string; createdAt: string; } interface Position { marketId: number; outcome: TradeSide; shares: number; avgPrice: number; currentValue: number; pnl: number; } type MarketCategory = | 'sports' | 'crypto' | 'politics' | 'tech' | 'entertainment' | 'science' | 'other'; type TradeSide = 'YES' | 'NO';

import { AgonError, AgonRateLimitError, AgonAuthError } from '@agon/sdk'; try { const trade = await agon.trade.buy({ marketId: 42, outcome: 'YES', amountUsdc: 100, signer }); } catch (err) { if (err instanceof AgonRateLimitError) { // Automatic retry with exponential backoff await new Promise(r => setTimeout(r, err.retryAfterMs)); } else if (err instanceof AgonAuthError) { // Token expired — re-authenticate await agon.auth.reconnect(signer); } else if (err instanceof AgonError) { console.error(err.code, err.message); } }

Error code

When it occurs

MARKET_CLOSED

Market is resolved or expired

INSUFFICIENT_BALANCE

Wallet USDC balance too low

SLIPPAGE_EXCEEDED

Price moved beyond slippage tolerance

RATE_LIMIT

Too many requests — respect X-RateLimit-Reset

AUTH_REQUIRED

Endpoint requires wallet auth or API key

INVALID_MARKET_ID

Market does not exist

ARENA_FULL

Arena has reached max participant count

PARLAY_SETTLED

Parlay is already settled