Docs
How the yolo API works on Sui: one REST base URL for every chain, bearer keys, clear limits and the same response shape everywhere.
Base URL and auth
Send your key in the Authorization header. Market data works without a key at lower limits. Account endpoints need a signed-in wallet session or a fresh wallet signature, so a key can never grant itself more. Create keys on the API Keys page.
https://yolo.casa/api/v1Authorization: Bearer $YOLO_API_KEYwss://yolo.casa/api/v1/streamhttps://yolo.casa/mcpChains
Each chain page has its formats, venues, signing and live coverage.
Keys from code
An agent with its own wallet can make a key by signing a challenge. No private key leaves the wallet.
curl https://yolo.casa/api/v1/auth/challenge \
-H 'Content-Type: application/json' \
--data '{"address":"YOUR_SUI_WALLET"}'
# Sign the returned message as a Sui personal message.
curl https://yolo.casa/api/v1/auth/keys \
-H 'Content-Type: application/json' \
--data '{"address":"YOUR_SUI_WALLET","challengeId":"CHALLENGE_ID","signature":"WALLET_SIGNATURE","name":"My agent"}'Rate limits
Counts reset each minute and at 00:00 UTC. Every data response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A key becomes funded with its first verified top-up.
| No key | Free key | Funded key | |
|---|---|---|---|
| Requests a minute | 30 | 120 | 600 |
| Free market data a day | 2,000 | 20,000 | 20,000 |
| Analytics, quotes, builds | No | With credits | With credits |
| Stream connections | 2 | 3 | 20 |
Responses and pagination
Every answer has the same envelope. Lists return items and nextCursor; pass nextCursor back as cursor for the next page. A value yolo does not know is null, never zero.
{
"version": "1",
"requestId": "...",
"data": {},
"usage": { "chargedUnits": 100, "balanceUnits": 999900 }
}Errors
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_requestinvalid_addresstype_requiredinvalid_swap | A parameter or body field is missing or wrong. |
| 401 | authentication_requiredinvalid_key | No key, a bad key or a revoked key. |
| 402 | insufficient_credits | The call is charged and the balance is too low. Add credits. |
| 403 | scope_denied | The key lacks the permission this endpoint needs. |
| 404 | token_not_foundmarket_not_found | Nothing exists with that id or coin type. |
| 409 | idempotency_conflictrequest_pendingrequest_refunded | The Idempotency-Key was used with other input, is still running, or was refunded and needs a new key. |
| 422 | no_routequote_expiredsimulation_failed | No pool or path trades this pair at this amount, a quote is too old, or the transaction would fail on chain. |
| 429 | rate_limitfree_limitbudget_limit | A per minute, free daily or key budget limit. Wait the seconds in Retry-After. |
| 503 | data_unavailablerouting_unavailable | A data source or router is briefly down. Retry with backoff. |
Retries and idempotency
Send an Idempotency-Key with charged POST requests and repeat it when you retry the same request. A completed result replays without a second charge. A failed request refunds its reservation; retry a refunded request with a new key. Reusing a key with different input returns 409. Transaction builders return unsigned transactions; your wallet signs and sends them.
Products
Account and service
Keys, credits, usage and status. Account endpoints run with your signed-in wallet.
/discovery
Discover capabilities and current prices
/auth/challenge
Request a wallet ownership challenge
/auth/keys
Sign the challenge and create an API key
/account
Read credit balance, payment recipient and pricing
/keys
List your keys with a wallet session; bearer authentication lists only its own key
/keys
Create a key from your signed-in account
/keys/{id}
Revoke a key
/credits/intent
Build an unsigned USDC top-up transaction
/credits/deposit
Verify a completed payment and credit your account once
/status
Service status: API, stream, indexer lag and the time each dataset is complete through
/usage
This key's tier, limits, free requests used today and credits spent today
/credits/funding-policy
Read account-wide automatic funding limits and usage
/credits/funding-policy
Enable or disable durable funding limits from a wallet session
/activity
Read request and research receipts; bearer keys see only their own activity
Changelog
2026-10-20
Free Sui swaps with a 20 bps fee, partner fees and commands for every key
- swap/quote and swap/build on Sui cost 0 credits. Any key with the quote or build scope can call them without funding; they do not use the free allowance or the daily budget. The per-minute limit still applies.
- Each Sui swap through the API pays a 20 bps yolo fee on chain, in USDC, inside the swap transaction (it was the website's 1%). The owner's own fee-free keys stay fee-free.
- swap/quote returns amountOut net of every fee, plus feeBps and fee (mode, coinType, amount taken and its estimate in USDC).
- Optional partner fee: pass partnerFeeBps (1 to 100) and partnerAddress on swap/quote. It is taken from the input coin in the same transaction and sent to your address, on top of yolo's fee, and shown in partnerFee.
- swap/build mode commands works for every key. Fee steps are commands of the plan and listed in plan.fees and fees; addYoloRoute refuses a plan whose fee steps are missing.
2026-10-10
Swaps for any wallet, route commands and an on-chain minimum
- swap/quote and swap/build take an optional owner: the wallet that trades. Quotes are bound to the key and that wallet.
- swap/build mode commands returns the route as JSON (calls, type arguments, object ids and shared versions, per-hop minimums). GET /route-commands.ts is a helper with no dependencies that adds it to your own transaction after an earlier step and hands the output coin back. For fee-free keys.
- Every swap/build now aborts on chain when the output is below minOut, the quote or dry run less your slippage. The response carries minOut and feeBps.
2026-10-07
Free tier, real-time stream and 25 new data endpoints
- Market data works without a key (30 requests a minute) and with a free key (120 a minute, 20,000 a day). No credits needed.
- New endpoints: search, trending with reasons, pulse, launches, launchpads, token security, holders with labels, bubble map, top traders, wallet portfolio, P/L, P/L series, trades, labels and search, smart money feed, leaderboards, perps markets, market and candles, plus token cost basis, wallet x-ray, copy backtest, dev report and the launchpad league.
- Real-time stream over WebSocket and SSE: trades per token, price ticks, wallet activity, launches, graduations, large trades, and a firehose for funded keys. Resume after short gaps with a sequence number.
- 429 responses carry the exact Retry-After. Data responses carry X-RateLimit headers. GET /usage reports a key's limits and usage.
- GET /status and the status page report API, stream, indexer lag and the time each dataset is complete through.
- The hosted MCP server accepts an API key directly and exposes every data endpoint as a tool.
- tokens, token, candles and trades moved into the free allowance. Funded keys pay their listed price only past 20,000 free requests a day.
2026-10-07
First release
- Tokens, token detail, candles, trades, token P/L, lending markets and positions, swap quotes, unsigned swap and lending transactions.
- Wallet-owned keys with scopes and daily budgets, USDC credits, historical research jobs, hosted MCP with OAuth, JavaScript SDK.