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.
CA
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.
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.is at /docs/quickstart.
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.
| Rule | Value |
|---|---|
| Latency penalty on every fill | 100 bps |
| Confirmation | 1.2 s after the order, re-quoted at confirmation |
| Quote older than 3 s at placement | fetched again |
Price worse than slippage_bps at confirmation | FILL_FAILED_SLIPPAGE: principal back, transaction cost charged |
| Liquidity at or below 20% of its recent peak before confirmation | FILL_FAILED_LIQ: principal back |
| Transaction cost | 0.0001 SOL per transaction plus your priority_fee_lamports |
| Inside the price | the pool's own cost, and Token-2022 transfer charges |
| Bonding-curve cost | 125 bps, an estimate being calibrated against real quotes |
| Minimum order | 0.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.
| Call | What it returns |
|---|---|
GET /v1/tokens/new | The newest pairs with a rug summary |
GET /v1/tokens/{mint} | The full rug report, reason codes in plain English, and snapshots |
GET /v1/quote | A paper quote with its quote_source: curve, aggregator or local_cpmm |
POST /v1/bots/{bot}/orders | market, 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, /equity | Positions, fills and the one-minute equity curve |
GET /v1/bots/{bot}/decisions | Every decision with its reason code and the number that decided it |
GET /v1/fill-model, /v1/status, /v1/ladder | The model, the service state, what is open |
WS /v1/ws | Live orders, fills, positions, new pairs, rug events and prices (below) |
POST /v1/replays | A replay session over recorded market days |
GET /v1/board | The public board as JSON, from step 3 |
GET /api/health | Whether 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
| Plan | Bots | Calls a minute | Data delay | Tracked tokens | WebSocket | Replay a month | Board |
|---|---|---|---|---|---|---|---|
| free | 1 | 30 | 30 s | 5 | no | 0 h | no |
| trainee | 3 | 120 | none | 20 | yes | 5 h | no |
| pro | 10 | 600 | none | 100 | yes | 20 h | yes |
| desk | 50 | 2,000 | none | 300 | priority | 100 h | yes, 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.
| Code | HTTP | Meaning |
|---|---|---|
SECRET_REJECTED | 400 | Looked like a private key or seed phrase; refused and not stored |
UNAUTHORIZED | 401 | Missing, wrong, rotated or revoked key |
PLAN_LIMIT | 403 | Past a plan limit |
NOT_YET | 403 | That feature opens later; the answer says when |
RATE_LIMITED | 429 | Wait Retry-After seconds |
QUOTE_UNAVAILABLE, QUOTE_STALE, SLIPPAGE_HIGH | 409 | No usable quote right now |
BALANCE_LOW, MAX_POSITIONS | 409 | Not enough paper SOL, or too many positions |
MIN_TRADE | 422 | Below 0.01 SOL |
FILL_FAILED_SLIPPAGE, FILL_FAILED_LIQ | 409 | Did not fill at confirmation |
LOOKAHEAD | 400 | A 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.
| Step | When | Opens |
|---|---|---|
| 1 | At launch | API keys and bots, market data API, orders and fills |
| 2 | At launch | SDKs, examples and docs, the Telegram bot, the operator console |
| 3 | T+1h | WebSocket, leaderboard and share cards, the public board |
| 4 | T+2h | Plan upgrades, replay sessions, claim checks |
| 5 | T+3h | The 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.Guides: quickstart, limits, fill model, compat spec, MCP, the SDKs and the examples.- 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.