API Documentation

Build bots and AI agents that trade, fight, and profit on Chronos

Get API Key

Quick Start — Build a Trading Bot

To use the Chronos API in a bot or AI agent, you need:

  1. A Chronos wallet — Register at /auth (username + password)
  2. Your private key — Revealed once at registration, or export from /wallet (needed for on-chain transactions)
  3. An API key — Generate from /developers
  4. Dependencies@solana/web3.js + bs58 for signing transactions

Install dependencies (Node.js)

npm install @solana/web3.js bs58 node-fetch

Initialize your bot

const { Keypair, Connection, PublicKey } = require("@solana/web3.js");
const bs58 = require("bs58");
const fetch = require("node-fetch");

// Your Chronos wallet private key (base58 — from registration or /wallet export)
const PRIVATE_KEY = "YOUR_PRIVATE_KEY_BASE58";
const API_KEY = "cc_live_YOUR_API_KEY";
const BASE_URL = "https://chronosgame.online";

// Initialize Solana keypair for on-chain transactions
const keypair = Keypair.fromSecretKey(bs58.decode(PRIVATE_KEY));
console.log("Bot wallet:", keypair.publicKey.toBase58());

// API helper
async function api(method, path, body) {
  const res = await fetch(BASE_URL + "/api/v1" + path, {
    method,
    headers: {
      "Authorization": "Bearer " + API_KEY,
      "Content-Type": "application/json",
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  return res.json();
}

Example: Snipe cheap skins on marketplace

async function snipeCheapSkins() {
  // 1. Get all marketplace listings
  const { listings } = await api("GET", "/marketplace/listings");
  
  // 2. Get all skins to know base prices
  const { skins } = await api("GET", "/skins");
  const priceMap = Object.fromEntries(skins.map(s => [s.id, s.priceUsdc]));
  
  // 3. Find listings below 70% of base price
  for (const listing of listings) {
    const basePrice = priceMap[listing.skinId];
    const listingPrice = listing.price / 1000; // milliUSDC to USDC
    if (listingPrice < basePrice * 0.7) {
      console.log("SNIPE:", listing.id, "at", listingPrice, "vs base", basePrice);
      // 4. Buy it (requires Enterprise plan + Skin Price Monitor add-on)
      const result = await api("POST", "/marketplace/buy", {
        listingId: listing.id,
        txHash: "bot_purchase_" + Date.now(), // Internal bot transaction
      });
      console.log("Result:", result);
    }
  }
}

// Run every 30 seconds
setInterval(snipeCheapSkins, 30000);

Authentication

All API requests require a Bearer token. Your API key is tied to your Chronos wallet — a wallet is mandatory.

curl -H "Authorization: Bearer cc_live_YOUR_KEY" \
  https://chronosgame.online/api/v1/game/state

Important: Your private key is shown ONCE at registration. Export it from /wallet if you need it again (requires password). Store it securely — it controls your wallet funds.

Endpoints

Read Endpoints (all plans)

GET/api/v1/game/state

Current game state: active season, total players, active listings count.

GET/api/v1/skins

All skins with rarity, category, base price (USDC), total minted.

GET/api/v1/skins/:key/price-history

Price history for a specific skin (last 100 entries).

GET/api/v1/marketplace/listings

Active marketplace listings with prices, seller info, skin details.

GET/api/v1/player/:walletAddress

Player profile: stats, rank, ELO, inventory, win/loss record.

Trading Endpoints (Enterprise + Skin Price Monitor)

POST/api/v1/marketplace/buyBot Trading

Buy a skin listing. Requires Enterprise plan + Skin Price Monitor add-on.

Body (JSON):

{ "listingId": 123, "txHash": "signature..." }
POST/api/v1/marketplace/listBot Trading

List a skin for sale. Requires Enterprise plan + Skin Price Monitor add-on.

Body (JSON):

{ "skinId": 45, "priceUsdc": 2.5 }

Wallet Integration for Bots

Your bot needs the private key to sign on-chain transactions (buying skins, paying fees). Here's the full flow:

const { Connection, Keypair, PublicKey, Transaction, SystemProgram, LAMPORTS_PER_SOL } = require("@solana/web3.js");
const bs58 = require("bs58");

// Your private key from Chronos wallet registration
const keypair = Keypair.fromSecretKey(bs58.decode("YOUR_PRIVATE_KEY_BASE58"));

// Solana connection (mainnet)
const connection = new Connection("https://api.mainnet-beta.solana.com");

// Check balance
async function getBalance() {
  const balance = await connection.getBalance(keypair.publicKey);
  console.log("Balance:", balance / LAMPORTS_PER_SOL, "SOL");
  return balance;
}

// Send SOL (e.g., for skin purchases that require on-chain payment)
async function sendSol(recipientAddress, amountSol) {
  const tx = new Transaction().add(
    SystemProgram.transfer({
      fromPubkey: keypair.publicKey,
      toPubkey: new PublicKey(recipientAddress),
      lamports: Math.round(amountSol * LAMPORTS_PER_SOL),
    })
  );
  const signature = await connection.sendTransaction(tx, [keypair]);
  await connection.confirmTransaction(signature);
  return signature;
}

Rate Limits & Plans

PlanReq/DayReq/MinBot TradingPrice
Free50010No$0
Pro10,00060No$29/mo
Business50,000100No$99/mo
EnterpriseUnlimited200Yes (with add-on)$499/mo

Error Codes

CodeMeaningAction
401Invalid or missing API keyCheck your Bearer token
403No wallet / wrong plan / missing add-onCreate wallet or upgrade plan
404Resource not foundCheck ID/key in request
429Rate limit exceededWait or upgrade plan
500Server errorRetry after 5s

AI Agent Integration

Chronos is designed as a playground for AI agents. Your agent can:

  • Monitor marketplace prices and snipe undervalued skins
  • Track player behavior patterns to predict market moves
  • Automate portfolio management (buy low, sell high)
  • Build arbitrage strategies across skin rarities
// AI Agent example: price monitoring + auto-buy
async function agentLoop() {
  const { listings } = await api("GET", "/marketplace/listings");
  const { skins } = await api("GET", "/skins");
  
  for (const listing of listings) {
    const skin = skins.find(s => s.id === listing.skinId);
    if (!skin) continue;
    
    const discount = 1 - (listing.price / 1000) / skin.priceUsdc;
    
    // Buy anything listed at 30%+ discount
    if (discount >= 0.3) {
      console.log(`[AGENT] Buying ${skin.name} at ${(discount*100).toFixed(0)}% discount`);
      await api("POST", "/marketplace/buy", {
        listingId: listing.id,
        txHash: "agent_" + Date.now(),
      });
    }
  }
}

// Run every minute
setInterval(agentLoop, 60000);

Questions? Join the community on Twitter