Koajo$KOAJO
Launch schedule
Contents

How Koajo fills a paper order

Koajo is a test drive for Solana trading bots. Your bot gets an API key, never a private key, and trades on paper against the live memecoin market: new pairs as they appear, quotes from the real pools, rugs as they happen. Nothing is ever signed or sent.

Koajo has not opened yet. Every number on this page comes from the published fill model, the test suite, a load test, or the Recorded session, Nov 5, 35 min, house bots, paper.

How it works

One server process does four jobs, all off chain.

  • It watches the market. New Solana pairs arrive from public new-pair feeds; prices and pool liquidity come from token data feeds and Solana RPC. Each tracked pair is snapshotted in rounds. In the recording a round took 868 ms at the median, and 313 pairs gave 23,056 snapshots in 193 rounds.
  • It checks every pair for rugs. Mint and freeze authority, risky Token-2022 extensions, top-10 holder share, liquidity, pool age and price impact, each with a plain-English reason code. Of 313 tracked pairs in the recording, 7 passed the normal check.
  • It fills orders with the published model. Quotes come from the bonding curve itself, from an outside quote service for AMM pools, or from a local constant product on the latest snapshot. The response always names its quote_source.
  • It writes everything down. Orders, fills, positions, a one-minute equity curve and every decision with its reason code. The same input always gives the same result.
What runs on chain: nothing that touches your funds. Koajo never holds a key that can sign, and never sends a transaction. The only chain reads are market data and, after launch, the public token balance behind a plan check.

Quickstart

At launch, send /key to the Telegram bot. One free key per Telegram account; the key starts with dr_, is shown once and is stored only as a hash. /rotate, /revoke and /plan work in the same chat. An operator invite code also gives a key. The Telegram bot opens at launch.

export KOAJO_BASE_URL=<the address published at launch>
export KOAJO_API_KEY=dr_...
H="Authorization: Bearer $KOAJO_API_KEY"
# the newest pairs, each with a rug summary
curl -s "$KOAJO_BASE_URL/v1/tokens/new?limit=5" -H "$H"
# a paper quote for 0.1 SOL
curl -s "$KOAJO_BASE_URL/v1/quote?mint=<MINT>&side=buy&amount=0.1&slippageBps=300" -H "$H"
# a market buy on the default bot, which starts with 10 paper SOL
curl -s -X POST $KOAJO_BASE_URL/v1/bots/default/orders -H "$H" \
  -H "content-type: application/json" \
  -d '{"mint": "<MINT>", "side": "buy", "amount": 0.1, "slippage_bps": 300, "client_order_id": "first-1"}'
# why it filled or failed
curl -s $KOAJO_BASE_URL/v1/bots/default/decisions -H "$H"

The order ends filled, or failed with a code such as FILL_FAILED_SLIPPAGE or FILL_FAILED_LIQ. Every answer carries the line "Paper trading. Real fills may differ." The full quickstart in curl, Python and TypeScript opens at /docs/quickstart with step 2.

The key guard

Before any handler runs, the query, the headers and the body of every request are scanned for anything shaped like a Solana private key or a seed phrase: a 64-byte key pair in base58, hex or a byte array, or any 12 consecutive words from the BIP-39 English list, even inside longer text. A match is refused with 400 SECRET_REJECTED, nothing in that request is stored, and the body is never logged. Signatures pass; key pairs never do. A 32-byte base58 string passes too, because it cannot be told apart from a public key or a mint.

The website itself never asks for a key, a seed or a signature, and has no wallet connection. That is the point of the product.

The fill model, version 1

The model is public at GET /v1/fill-model. A change to any number is a new version.

RuleValue
Latency penalty on every fill100 bps
Confirmation1.2 s after the order, re-quoted at confirmation
Quote older than 3 s at placementfetched again
Price worse than slippage_bps at confirmationFILL_FAILED_SLIPPAGE: principal back, transaction cost charged
Liquidity at or below 20% of its recent peak before confirmationFILL_FAILED_LIQ: principal back
Transaction cost0.0001 SOL per transaction plus your priority_fee_lamports
Inside the pricethe pool's own cost, and Token-2022 transfer charges
Bonding-curve cost125 bps, an estimate being calibrated against real quotes
Minimum order0.01 SOL
Holding through a rug (price down 90% or liquidity at 20% or less)LIQ_PULLED: you can only exit against what is left

In a replay, every quote is fresh arithmetic on the recorded snapshot at the session clock, held between snapshots and never interpolated.

Once the public board opens at T+1h, its fill lab runs these rules on all 102 recorded paper trades; move the order time and watch each rule act.

Endpoints

Every call takes Authorization: Bearer dr_..., except the health check and the ladder.

CallWhat it returns
GET /v1/tokens/newThe newest pairs with a rug summary
GET /v1/tokens/{mint}The full rug report, reason codes in plain English, and snapshots
GET /v1/quoteA paper quote with its quote_source: curve, aggregator or local_cpmm
POST /v1/bots/{bot}/ordersmarket, limit and tp_sl orders, sized in SOL, tokens or percent, with slippage_bps, priority_fee_lamports and client_order_id
GET /v1/bots/{bot}/positions, /fills, /equityPositions, fills and the one-minute equity curve
GET /v1/bots/{bot}/decisionsEvery decision with its reason code and the number that decided it
GET /v1/fill-model, /v1/status, /v1/ladderThe model, the service state, what is open
WS /v1/wsLive orders, fills, positions, new pairs, rug events and prices (below)
POST /v1/replaysA replay session over recorded market days
GET /v1/boardThe public board as JSON, from step 3
GET /api/healthWhether the service is up, without a key

Bots are sub-accounts on one key, and each starts with 10 paper SOL. A reset is allowed once every 24 hours and takes that bot off the season's board.

WebSocket

/v1/ws opens at step 3 of the ladder and needs the trainee plan or higher. Authenticate with the first message, {"op": "auth", "key": "dr_..."}, within 10 seconds; a key in the URL is refused. Channels: orders, fills, positions, tokens.new, rug.events and prices:{mint}.

Every data message is numbered with seq, and {"op": "resume", "since_seq": N} sends what you missed in the last 5 minutes. The server pings every 20 s and closes a connection that stays silent for 60 s. At most 5 open connections per key.

Replay

POST /v1/replays opens a session over recorded market days. Send the same calls with the header X-Replay-Session, and the bot code does not change. The clock moves by hand with advance, or runs at up to 60x. Asking for data past the clock is refused with LOOKAHEAD, so a backtest cannot peek. Replay opens at T+2h.

The compat switch

A compatibility layer answers in the exact request and response formats of the quote API and the trade API that Solana bots already use. A bot written against those formats points at /compat/quote/v1 and /compat/trade here; to go live, it changes only its base URL back. Every value it returns is a paper value, and nothing can be signed or sent. The compat layer opens at T+3h.

Coding agents

An MCP server at /mcp takes the same key, and one file, /skill.md, walks an agent from reading the docs to getting a key to placing a first order. Both open at T+3h.

Claim checks

Someone posts that their bot did 100x overnight. Enter the stated start balance, end balance, window and rules, and Koajo re-runs it on its own recorded market data. The answer is Reproduced, Not reproduced under these conditions, or Not enough data, each with the conditions it ran under. Claim checks open at T+2h, and a share card (1200 x 675, with the disclaimer) can go with any result.

Board and arena

The leaderboard is opt-in per bot (POST /v1/bots/{bot}/leaderboard), over 24 hours, 7 days and the season. A bot is eligible with 5 or more fills, a max drawdown of 50% or less and no reset in the period. It shows the pseudonym (Bot#4821), return, max drawdown, win rate, fills and the last three decision reasons, never a Telegram name or a wallet address.

The arena runs weekly seasons, Monday 00:00 UTC to Sunday 23:59 UTC. Every entrant starts at 10 SOL on the same fill model, ranks by season return, and a tie goes to the smaller drawdown. Results are public. Nothing here promises a prize.

In the recording, the four house bots ended at −16.4%, −24.1%, −74.6% and −84.6%. Bot#2264 and Bot#7330 would not be eligible: their drawdowns went past 50%.

Plans

PlanBotsCalls a minuteData delayTracked tokensWebSocketReplay a monthBoard
free13030 s5no0 hno
trainee3120none20yes5 hno
pro10600none100yes20 hyes
desk502,000none300priority100 hyes, plus arena seed

The delay applies to reading market data only. Every plan's fills run on the same real-time data. The live limits are at GET /v1/plans.

Errors

Every error body is {code, message_en, hint}. Branch on code.

CodeHTTPMeaning
SECRET_REJECTED400Looked like a private key or seed phrase; refused and not stored
UNAUTHORIZED401Missing, wrong, rotated or revoked key
PLAN_LIMIT403Past a plan limit
NOT_YET403That feature opens later; the answer says when
RATE_LIMITED429Wait Retry-After seconds
QUOTE_UNAVAILABLE, QUOTE_STALE, SLIPPAGE_HIGH409No usable quote right now
BALANCE_LOW, MAX_POSITIONS409Not enough paper SOL, or too many positions
MIN_TRADE422Below 0.01 SOL
FILL_FAILED_SLIPPAGE, FILL_FAILED_LIQ409Did not fill at confirmation
LOOKAHEAD400A replay asked for data past its clock

The token in the product

$KOAJO does one job in the product: holding it sets your plan. Hold the published tier for trainee, pro or desk limits. Holdings are valued at the 24-hour average price and checked every hour; drop below and the plan drops at the next check.

Streaks. Hold your tier for 7 days for 1.5x calls and replay hours, and 30 days for 2x. Any dip resets the streak to zero.

Binding a wallet without connecting one. The Telegram bot gives you a unique amount, for example 1.2347. You send exactly that from your own wallet to the published address, and the sending wallet is bound to your key. Nothing is signed on this site.

Supply and launch settings are published at launch. These features are built and switch on then.

What is thin

  • The free plan exists, and many developers will stay on it. That is fine.
  • Nothing about the token is enforced on chain by this product. Plan checks run on the server against public chain data.
  • The 125 bps bonding-curve cost is an estimate still being calibrated against real quotes.
  • A paper fill is a test, not a forecast. Real fills meet competing bots, congestion, failed transactions and priority auctions. Paper trading. Real fills may differ.
  • The recording is 35 minutes of one day. All four house bots lost money in it; that says what honest fills do to simple rules, and little more.

Measured

p95 25.6 ms with 500 keys and 50 orders a second, 0 errors.

That load test ran on one server, whose limit is about 145 requests a second. The code base carries 298 tests. The mainnet recording ran read-only for 35.1 minutes with Koajo's own engine and a paid RPC: 439 new SOL pairs seen, 313 tracked, 23,056 snapshots, SOL at $95.92.

SDKs and examples

Python and TypeScript clients, with four example bots: momentum, rug avoider, replay backtest and compat switch. MIT licensed. They pace themselves on the rate-limit headers, retry only idempotent requests, and raise errors that carry the API code.

Launch ladder and status

Nothing is open before launch. Then 15 features open in 5 steps, and GET /v1/ladder says what is open at any moment.

StepWhenOpens
1At launchAPI keys and bots, market data API, orders and fills
2At launchSDKs, examples and docs, the Telegram bot, the operator console
3T+1hWebSocket, leaderboard and share cards, the public board
4T+2hPlan upgrades, replay sessions, claim checks
5T+3hThe compatibility layer, arena season 1, the MCP server and /skill.md

Where to check it yourself, without a wallet: /docs/ladder, /api/health, GET /v1/status, GET /v1/fill-model and GET /v1/ladder.

Privacy

Keys are stored only as a hash. A request that carries a wallet secret is refused before it is read and nothing in it is stored. Public pages show bot pseudonyms only, never a Telegram name or a wallet address. This site sets no wallet connection and asks for no signature.

The name: Koajo comes from the Finnish koeajo, a test drive, with one letter dropped.

More to read

  • API reference: every endpoint, generated from the server, with a try-it console.
  • /docs/guides: quickstart, limits, fill model, compat spec, MCP, the SDKs and the examples. They open with step 2.
  • Ladder: what is open right now.
  • /skill.md: one file for a coding agent, from step 5.
  • /llms.txt: the docs index for language models, from step 2.