SDK and OpenAPI
A standalone JavaScript client, the OpenAPI specification for generated clients, and the whole API as one plain text guide for models. All three are built from the same endpoint list as these docs.
JavaScript SDK
A standalone ES module for Node and browsers. It holds no wallet keys.
TypeScript
import { YoloApiClient } from './yolo-api.mjs';
const yolo = new YoloApiClient({ apiKey: process.env.YOLO_API_KEY });
const trending = await yolo.get('tokens', { list: 'trending', limit: 5 });
console.log(trending);
const account = await yolo.account();
console.log(account.balanceUnits);Automatic funding
Give the client a wallet callback and a cap. It tops up when a call returns 402, then retries the same request.
TypeScript
import { YoloApiClient } from './yolo-api.mjs';
const yolo = new YoloApiClient({
apiKey: process.env.YOLO_API_KEY,
paymentReceiptStore: {
load: () => receipts.load(), // durable storage you control
save: (payment) => receipts.save(payment),
},
autoTopup: {
thresholdUnits: 100_000, // 0.10 USDC
amountUnits: 5_000_000, // top up 5 USDC
maxTotalUnits: 20_000_000, // at most 20 USDC per client
signAndExecute: async (intent) => {
// Your wallet executes intent.kind, preserving its commands.
// Return the successful Sui transaction digest.
return wallet.payApiIntent(intent);
},
},
});
const markets = await yolo.get('lending/markets', {});
// Swap quotes and builds use no credits; each swap pays a 20 bps fee on
// chain and amountOut is already net of it.
const quote = await yolo.post('swap/quote', {
coinIn: 'INPUT_COIN_TYPE',
coinOut: 'OUTPUT_COIN_TYPE',
amountIn: '1000000', // input token base units
});OpenAPI
OpenAPI 3.1, for code generators and API tools.
JSON
{
"openapi": "3.1.0",
"info": {
"title": "yolo API",
"version": "1",
"description": "Sui mainnet intelligence and unsigned transaction building with USDC-funded credits."
},
"servers": [
{
"url": "https://yolo.casa"
}
],
"paths": {
"/api/v1/discovery": {
"get": {
"summary": "Discover capabilities and current prices",
"operationId": "get_discovery",
"security": [],
"parameters": [],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
}
}
},
"/api/v1/auth/challenge": {
"post": {
"summary": "Request a wallet ownership challenge",
"operationId": "post_auth_challenge",
"security": [],
"parameters": [],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"address": {
"type": "string",
"description": "Sui wallet address"
}
},
"required": [
"address"
],
"additionalProperties": false
}
}
}
}
}
},
"/api/v1/auth/keys": {
"post": {
"summary": "Sign the challenge and create an API key",
"operationId": "post_auth_keys",
"security": [],
"parameters": [],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"address": {
"type": "string"
},
"challengeId": {
"type": "string"
},
"signature": {
"type": "string"
},
"name": {
"type": "string"
},
"dailyBudgetUnits": {
"type": "integer"
},
"scopes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"data",
"quote",
"build",
"research"
]
},
"description": "Choose data, quote, build and/or research"
}
},
"required": [
"address",
"challengeId",
"signature"
],
"additionalProperties": false
}
}
}
}
}
},
"/api/v1/account": {
"get": {
"summary": "Read credit balance, payment recipient and pricing",
"operationId": "get_account",
"security": [
{
"bearerAuth": []
}
],
"parameters": [],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
}
}
},
"/api/v1/keys": {
"get": {
"summary": "List your keys with a wallet session; bearer authentication lists only its own key",
"operationId": "get_keys",
"security": [
{
"bearerAuth": []
}
],
"parameters": [],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
}
},
"post": {
"summary": "Create a key from your signed-in account",
"operationId": "post_keys",
"security": [
{
"walletSession": []
}
],
"parameters": [],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"dailyBudgetUnits": {
"type": "integer"
},
"scopes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"data",
"quote",
"build",
"research"
]
},
"description": "Choose data, quote, build and/or research"
}
},
"required": [
"name"
],
"additionalProperties": false
}
}
}
}
}
},
"/api/v1/keys/{id}": {
"delete": {
"summary": "Revoke a key",
"operationId": "delete_keys__id_",
"security": [
{
"walletSession": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
}
}
},
"/api/v1/credits/intent": {
"post": {
"summary": "Build an unsigned USDC top-up transaction",
"operationId": "post_credits_intent",
"security": [
{
"bearerAuth": []
}
],
"parameters": [],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"amountUnits": {
"type": "string",
"description": "Integer micro-USDC. 1000000 = 1 USDC",
"example": "1000000"
},
"automatic": {
"type": "boolean",
"description": "Use enabled account funding policy and a stable Idempotency-Key"
}
},
"required": [
"amountUnits"
],
"additionalProperties": false
}
}
}
}
}
},
"/api/v1/credits/deposit": {
"post": {
"summary": "Verify a completed payment and credit your account once",
"operationId": "post_credits_deposit",
"security": [
{
"bearerAuth": []
}
],
"parameters": [],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"intentId": {
"type": "string"
},
"digest": {
"type": "string"
}
},
"required": [
"intentId",
"digest"
],
"additionalProperties": false
}
}
}
}
}
},
"/api/v1/tokens": {
"get": {
"summary": "List Sui tokens: trending, new, top, gainers, bonding, graduated",
"operationId": "get_tokens",
"security": [],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "list",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Which list. Default trending",
"enum": [
"trending",
"new",
"top",
"gainers",
"bonding",
"graduated",
"all"
],
"example": "trending"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Rows per page, 1 to 100. Default 50",
"example": 50
}
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Rows to skip, up to 10000"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 100,
"x-free-tier": true,
"tags": [
"Tokens"
]
}
},
"/api/v1/search": {
"get": {
"summary": "Search tokens by symbol, name or coin type",
"operationId": "get_search",
"security": [],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "q",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Symbol, name or coin type",
"example": "sui"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Rows per page, 1 to 50. Default 20",
"example": 20
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 100,
"x-free-tier": true,
"tags": [
"Tokens"
]
}
},
"/api/v1/trending": {
"get": {
"summary": "Trending tokens ranked by real traders, each with the reason it ranks",
"operationId": "get_trending",
"security": [],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Rows per page, 1 to 100. Default 30",
"example": 30
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "nextCursor from the previous page"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 100,
"x-free-tier": true,
"tags": [
"Tokens"
]
}
},
"/api/v1/pulse": {
"get": {
"summary": "Launchpad coins in three columns: new, about to bond, and bonded",
"operationId": "get_pulse",
"security": [],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "sort",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Order inside each column. Default new",
"enum": [
"new",
"trending"
]
}
},
{
"name": "launchpad",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Only this launchpad",
"enum": [
"perpsplexity",
"suipump",
"popularsui",
"amped",
"cetus-direct",
"blast-v1"
]
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 100,
"x-free-tier": true,
"tags": [
"Tokens"
]
}
},
"/api/v1/launches": {
"get": {
"summary": "Newest launches, optionally for one launchpad",
"operationId": "get_launches",
"security": [],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "launchpad",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Only this launchpad",
"enum": [
"perpsplexity",
"suipump",
"popularsui",
"amped",
"cetus-direct",
"blast-v1"
]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Rows per page, 1 to 100. Default 50",
"example": 50
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "nextCursor from the previous page"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 100,
"x-free-tier": true,
"tags": [
"Tokens"
]
}
},
"/api/v1/token": {
"get": {
"summary": "One token's market data, and whether it is a CTO (community takeover) with its CTO score",
"operationId": "get_token",
"security": [],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "type",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Sui coin type, for example 0x2::sui::SUI",
"example": "0x2::sui::SUI"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 100,
"x-free-tier": true,
"tags": [
"Token detail"
]
}
},
"/api/v1/candles": {
"get": {
"summary": "OHLCV candles. Page back with before; history reaches mid 2023 where the coin existed",
"operationId": "get_candles",
"security": [],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "type",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Sui coin type, for example 0x2::sui::SUI",
"example": "0x2::sui::SUI"
}
},
{
"name": "tf",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Candle size. Default 5m. 1s is a rolling five-minute view for Perpsplexity coins",
"enum": [
"1s",
"1m",
"5m",
"15m",
"1h",
"4h",
"1d"
],
"example": "1h"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Rows per page, 1 to 1000. Default 200",
"example": 200
}
},
{
"name": "before",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Unix seconds. Returns candles older than this; pass the oldest time you have"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 200,
"x-free-tier": true,
"tags": [
"Token detail"
]
}
},
"/api/v1/trades": {
"get": {
"summary": "A token's trades, newest first",
"operationId": "get_trades",
"security": [],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "type",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Sui coin type, for example 0x2::sui::SUI",
"example": "0x2::sui::SUI"
}
},
{
"name": "before",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Unix milliseconds. nextBefore from the previous page"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 200,
"x-free-tier": true,
"tags": [
"Token detail"
]
}
},
"/api/v1/token/security": {
"get": {
"summary": "Risk checks: mint, freeze and metadata control, dev, insiders, snipers, bundles, top 10 share, liquidity",
"operationId": "get_token_security",
"security": [],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "type",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Sui coin type, for example 0x2::sui::SUI",
"example": "0x2::sui::SUI"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 200,
"x-free-tier": true,
"tags": [
"Token detail"
]
}
},
"/api/v1/token/holders": {
"get": {
"summary": "Holders by size with labels, cost basis and P/L",
"operationId": "get_token_holders",
"security": [],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "type",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Sui coin type, for example 0x2::sui::SUI",
"example": "0x2::sui::SUI"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Rows per page, 1 to 100. Default 25",
"example": 25
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "nextCursor from the previous page"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 200,
"x-free-tier": true,
"tags": [
"Token detail"
]
}
},
"/api/v1/token/bubbles": {
"get": {
"summary": "Bubble map of the top 100 holders: funding clusters, bundles, snipers, insiders",
"operationId": "get_token_bubbles",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "type",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Sui coin type, for example 0x2::sui::SUI",
"example": "0x2::sui::SUI"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 500,
"x-free-tier": false,
"tags": [
"Token detail"
]
}
},
"/api/v1/token/top-traders": {
"get": {
"summary": "A token's top traders in a window",
"operationId": "get_token_top-traders",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "type",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Sui coin type, for example 0x2::sui::SUI",
"example": "0x2::sui::SUI"
}
},
{
"name": "window",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Time window. Default 7d",
"enum": [
"24h",
"7d",
"30d",
"all"
],
"example": "7d"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Ranking. Default pnl",
"enum": [
"pnl",
"loss",
"realized",
"volume",
"buys",
"earliest"
]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Rows per page, 1 to 25. Default 20",
"example": 20
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 500,
"x-free-tier": false,
"tags": [
"Token detail"
]
}
},
"/api/v1/token/pnl": {
"get": {
"summary": "All-time winners and losers of a token by realized, unrealized or total P/L",
"operationId": "get_token_pnl",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "type",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Sui coin type, for example 0x2::sui::SUI",
"example": "0x2::sui::SUI"
}
},
{
"name": "side",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Default winners",
"enum": [
"winners",
"losers"
]
}
},
{
"name": "sort",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Default realized",
"enum": [
"total",
"realized",
"unrealized"
]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Rows per page, 1 to 50. Default 20",
"example": 20
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "nextCursor from the previous page"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 500,
"x-free-tier": false,
"tags": [
"Token detail"
]
}
},
"/api/v1/token/cost-basis": {
"get": {
"summary": "Where holders bought: cost basis distribution of a token",
"operationId": "get_token_cost-basis",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "type",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Sui coin type, for example 0x2::sui::SUI",
"example": "0x2::sui::SUI"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 500,
"x-free-tier": false,
"tags": [
"Token detail"
]
}
},
"/api/v1/wallet/portfolio": {
"get": {
"summary": "A wallet's coins, value, cost basis, perps account and DeFi positions",
"operationId": "get_wallet_portfolio",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "address",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Sui wallet address"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 500,
"x-free-tier": false,
"tags": [
"Wallets"
]
}
},
"/api/v1/wallet/pnl": {
"get": {
"summary": "A wallet's realized and unrealized P/L, win rate, volume and per-coin results in a window",
"operationId": "get_wallet_pnl",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "address",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Sui wallet address"
}
},
{
"name": "window",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Time window. Default 30d",
"enum": [
"24h",
"7d",
"30d",
"all"
],
"example": "30d"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 500,
"x-free-tier": false,
"tags": [
"Wallets"
]
}
},
"/api/v1/wallet/pnl-series": {
"get": {
"summary": "A wallet's P/L over time, for charts",
"operationId": "get_wallet_pnl-series",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "address",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Sui wallet address"
}
},
{
"name": "window",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Time window. Default 30d",
"enum": [
"24h",
"7d",
"30d",
"all"
],
"example": "30d"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 200,
"x-free-tier": false,
"tags": [
"Wallets"
]
}
},
"/api/v1/wallet/trades": {
"get": {
"summary": "A wallet's trades, newest first, back to mid 2023",
"operationId": "get_wallet_trades",
"security": [],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "address",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Sui wallet address"
}
},
{
"name": "coin",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Only this coin type"
}
},
{
"name": "side",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Only buys or only sells",
"enum": [
"buy",
"sell"
]
}
},
{
"name": "minUsd",
"in": "query",
"required": false,
"schema": {
"type": "number",
"description": "Only trades worth at least this many dollars",
"example": 1000
}
},
{
"name": "since",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Only trades at or after this time, in milliseconds. The last page ends there"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Rows per page, 1 to 200. Default 50",
"example": 50
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "nextCursor from the previous page"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 200,
"x-free-tier": true,
"tags": [
"Wallets"
]
}
},
"/api/v1/wallet/labels": {
"get": {
"summary": "Names and labels for up to 50 wallets: KOL, exchange, smart money, whale, SuiNS",
"operationId": "get_wallet_labels",
"security": [],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "addresses",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Comma separated wallet addresses, up to 50"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 100,
"x-free-tier": true,
"tags": [
"Wallets"
]
}
},
"/api/v1/wallet/search": {
"get": {
"summary": "Find traders by username, SuiNS name or address",
"operationId": "get_wallet_search",
"security": [],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "q",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Username, SuiNS name or address"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 100,
"x-free-tier": true,
"tags": [
"Wallets"
]
}
},
"/api/v1/wallet/xray": {
"get": {
"summary": "A wallet's trading style and history at a glance",
"operationId": "get_wallet_xray",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "address",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Sui wallet address"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 1000,
"x-free-tier": false,
"tags": [
"Wallets"
]
}
},
"/api/v1/wallet/flows": {
"get": {
"summary": "What a wallet received and sent in transfers, per coin, or its top counterparties",
"operationId": "get_wallet_flows",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "address",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Sui wallet address"
}
},
{
"name": "window",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "How far back. Default all",
"enum": [
"7d",
"30d",
"90d",
"all"
]
}
},
{
"name": "coin",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Only this coin type"
}
},
{
"name": "counterparties",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Return the wallets that sent it the most (in) or that it sent the most to (out) instead of totals",
"enum": [
"in",
"out"
]
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 1000,
"x-free-tier": false,
"tags": [
"Wallets"
]
}
},
"/api/v1/wallet/copy-backtest": {
"get": {
"summary": "What copying a wallet's trades would have returned",
"operationId": "get_wallet_copy-backtest",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "address",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Sui wallet address"
}
},
{
"name": "usd",
"in": "query",
"required": false,
"schema": {
"type": "number",
"description": "Size of each copied buy, 1 to 100000. Default 100"
}
},
{
"name": "window",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "How far back to copy. Default 30d",
"enum": [
"7d",
"30d",
"90d",
"all"
]
}
},
{
"name": "delaySec",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Seconds behind the wallet, 0 to 120. Default 5"
}
},
{
"name": "slippageBps",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "0 to 2000. Default 100"
}
},
{
"name": "feeBps",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "0 to 500. Default 100"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 1000,
"x-free-tier": false,
"tags": [
"Wallets"
]
}
},
"/api/v1/dev/report": {
"get": {
"summary": "A developer wallet's launch record",
"operationId": "get_dev_report",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "address",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Sui wallet address"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 500,
"x-free-tier": false,
"tags": [
"Wallets"
]
}
},
"/api/v1/smart-money": {
"get": {
"summary": "Trades by smart money, whales and KOLs, newest first",
"operationId": "get_smart-money",
"security": [],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "who",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Default all",
"enum": [
"all",
"smart",
"whale",
"kol"
]
}
},
{
"name": "minUsd",
"in": "query",
"required": false,
"schema": {
"type": "number",
"description": "Smallest trade in USD"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Rows per page, 1 to 100. Default 40",
"example": 40
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "nextCursor from the previous page"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 200,
"x-free-tier": true,
"tags": [
"Rankings"
]
}
},
"/api/v1/leaderboard": {
"get": {
"summary": "Top wallets or teams by realized P/L. A launchpad filter ranks traders of that launchpad's coins",
"operationId": "get_leaderboard",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "window",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Time window. Default 24h",
"enum": [
"24h",
"7d",
"30d",
"all"
],
"example": "24h"
}
},
{
"name": "view",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Default wallets. Teams need 30d or all",
"enum": [
"wallets",
"teams"
]
}
},
{
"name": "launchpad",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Only this launchpad",
"enum": [
"perpsplexity",
"suipump",
"popularsui",
"amped",
"cetus-direct",
"blast-v1"
]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Rows per page, 1 to 100. Default 100",
"example": 100
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 200,
"x-free-tier": false,
"tags": [
"Rankings"
]
}
},
"/api/v1/launchpads": {
"get": {
"summary": "Launchpads with fees, status and listed coin counts",
"operationId": "get_launchpads",
"security": [],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 100,
"x-free-tier": true,
"tags": [
"Launchpads"
]
}
},
"/api/v1/launchpads/league": {
"get": {
"summary": "Launchpads compared over 7 days, 30 days and all time",
"operationId": "get_launchpads_league",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 200,
"x-free-tier": false,
"tags": [
"Launchpads"
]
}
},
"/api/v1/perps/markets": {
"get": {
"summary": "Perps markets with mark price, open interest, funding rate and next funding time",
"operationId": "get_perps_markets",
"security": [],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 100,
"x-free-tier": true,
"tags": [
"Perps"
]
}
},
"/api/v1/perps/market": {
"get": {
"summary": "One perps market by id or symbol",
"operationId": "get_perps_market",
"security": [],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "id",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Market object id or symbol, for example BTC",
"example": "BTC"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 100,
"x-free-tier": true,
"tags": [
"Perps"
]
}
},
"/api/v1/perps/candles": {
"get": {
"summary": "A perps market's candles",
"operationId": "get_perps_candles",
"security": [],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "id",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Market object id or symbol",
"example": "BTC"
}
},
{
"name": "tf",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Candle size. Default 5m. 1s is available for a short recent window",
"enum": [
"1s",
"1m",
"5m",
"15m",
"1h",
"4h",
"1d",
"1w"
]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Rows per page, 1 to 1500. Default 300",
"example": 300
}
},
{
"name": "before",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Unix seconds"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 200,
"x-free-tier": true,
"tags": [
"Perps"
]
}
},
"/api/v1/status": {
"get": {
"summary": "Service status: API, stream, indexer lag and the time each dataset is complete through",
"operationId": "get_status",
"security": [],
"parameters": [],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"tags": [
"Service"
]
}
},
"/api/v1/usage": {
"get": {
"summary": "This key's tier, limits, free requests used today and credits spent today",
"operationId": "get_usage",
"security": [
{
"bearerAuth": []
}
],
"parameters": [],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"tags": [
"Service"
]
}
},
"/api/v1/lending/markets": {
"get": {
"summary": "Compare available lending markets",
"operationId": "get_lending_markets",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 100,
"x-free-tier": false
}
},
"/api/v1/lending/positions": {
"get": {
"summary": "Read a wallet's lending positions",
"operationId": "get_lending_positions",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
},
{
"name": "owner",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Defaults to your account wallet"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 1000,
"x-free-tier": false
}
},
"/api/v1/swap/quote": {
"post": {
"summary": "Get an aggregated swap quote. amountOut is what the wallet receives after every fee; feeBps, fee and partnerFee show the fees",
"operationId": "post_swap_quote",
"security": [
{
"bearerAuth": []
}
],
"parameters": [],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 0,
"x-free-tier": false,
"x-swap-fee-bps": 20,
"x-partner-fee-max-bps": 100,
"description": "Free to call. Each swap pays a 20 bps (0.2%) yolo fee on chain, inside the swap transaction. 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 partnerAddress, on top of yolo's fee.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"coinIn": {
"type": "string"
},
"coinOut": {
"type": "string"
},
"amountIn": {
"type": "string",
"description": "Integer base units of the input token, fees included"
},
"owner": {
"type": "string",
"description": "The wallet that will trade (0x and 64 hex). Defaults to your key's wallet. The quote is bound to this key and this wallet."
},
"partnerFeeBps": {
"type": "integer",
"description": "Your own fee on top of yolo's, 1 to 100 bps of amountIn, paid in the input coin to partnerAddress in the same transaction. Pass with partnerAddress.",
"example": 25
},
"partnerAddress": {
"type": "string",
"description": "The Sui wallet (0x and 64 hex) that receives your partner fee."
}
},
"required": [
"coinIn",
"coinOut",
"amountIn"
],
"additionalProperties": false
}
}
}
}
}
},
"/api/v1/swap/build": {
"post": {
"summary": "Build an unsigned swap, or its route commands, for a wallet",
"operationId": "post_swap_build",
"security": [
{
"bearerAuth": []
}
],
"parameters": [],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 0,
"x-free-tier": false,
"x-swap-fee-bps": 20,
"x-partner-fee-max-bps": 100,
"description": "Free to call. Each swap pays a 20 bps (0.2%) yolo fee on chain, inside the swap transaction. 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 partnerAddress, on top of yolo's fee.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Quote ID returned by swap/quote"
},
"mustBeat": {
"type": "string"
},
"slippageBps": {
"type": "integer",
"example": 100
},
"owner": {
"type": "string",
"description": "The wallet the quote was made for. Defaults to your key's wallet. It is the sender of the dry run and its coins pay the input."
},
"mode": {
"type": "string",
"enum": [
"transaction",
"commands"
],
"description": "transaction (default): a whole unsigned transaction kind. commands: a route plan to add to your own transaction with addYoloRoute from GET /api/v1/route-commands.ts, any key. Both carry the fee steps listed in fees and abort on chain when the output is below minOut."
},
"partnerFeeBps": {
"type": "integer",
"description": "Optional. If sent, must match the quote's partner fee (set on swap/quote)."
},
"partnerAddress": {
"type": "string",
"description": "Optional. If sent, must match the quote's partner."
}
},
"required": [
"id"
],
"additionalProperties": false
}
}
}
}
}
},
"/api/v1/route-commands.ts": {
"get": {
"summary": "TypeScript helper with no dependencies: addYoloRoute(tx, plan, coinIn) appends a commands-mode plan to your Transaction and returns the output coin",
"operationId": "get_route-commands.ts",
"security": [],
"parameters": [],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
}
}
},
"/api/v1/lending/build": {
"post": {
"summary": "Build an unsigned lending deposit or withdrawal",
"operationId": "post_lending_build",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"x-price-micro-usdc": 5000,
"x-free-tier": false,
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"protocol": {
"type": "string"
},
"action": {
"type": "string",
"example": "deposit"
},
"amountUnits": {
"type": "string",
"description": "Integer micro-USDC; required unless all=true",
"example": "1000000"
},
"all": {
"type": "boolean"
}
},
"required": [
"protocol",
"action"
],
"additionalProperties": false
}
}
}
}
}
},
"/api/v1/credits/funding-policy": {
"get": {
"summary": "Read account-wide automatic funding limits and usage",
"operationId": "get_credits_funding-policy",
"security": [
{
"bearerAuth": []
}
],
"parameters": [],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
}
},
"post": {
"summary": "Enable or disable durable funding limits from a wallet session",
"operationId": "post_credits_funding-policy",
"security": [
{
"walletSession": []
}
],
"parameters": [],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"maxTopupUnits": {
"type": "integer"
},
"dailyLimitUnits": {
"type": "integer"
},
"lifetimeLimitUnits": {
"type": "integer"
}
},
"required": [
"enabled",
"maxTopupUnits",
"dailyLimitUnits",
"lifetimeLimitUnits"
],
"additionalProperties": false
}
}
}
}
}
},
"/api/v1/activity": {
"get": {
"summary": "Read request and research receipts; bearer keys see only their own activity",
"operationId": "get_activity",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "1 to 100"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
}
}
},
"/api/v1/research/estimate": {
"post": {
"summary": "Preview coverage and pricing without scanning history; actual charge is unknown until execution",
"operationId": "post_research_estimate",
"security": [
{
"bearerAuth": []
}
],
"parameters": [],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"trader_rankings",
"wallet_performance",
"token_cohorts",
"token_risk"
]
},
"from": {
"type": "string",
"description": "Inclusive UTC date YYYY-MM-DD"
},
"to": {
"type": "string",
"description": "Exclusive UTC date; range must be positive and at most 366 days"
},
"owner": {
"type": "string",
"description": "Required for wallet_performance"
},
"type": {
"type": "string",
"description": "Required for token_cohorts and token_risk"
},
"limit": {
"type": "integer",
"description": "1 to 100, default20"
},
"maxChargeUnits": {
"type": "integer",
"description": "500 to 1000000 micro-USDC; default10000"
}
},
"required": [
"operation",
"from",
"to"
],
"additionalProperties": false
}
}
}
}
}
},
"/api/v1/research/jobs": {
"post": {
"summary": "Reserve a spending cap and enqueue scoped historical research",
"operationId": "post_research_jobs",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Unique per operation and input; reuse for safe retries"
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "Insufficient credit; top up and retry"
},
"409": {
"description": "Idempotency conflict or request still pending"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"trader_rankings",
"wallet_performance",
"token_cohorts",
"token_risk"
]
},
"from": {
"type": "string",
"description": "Inclusive UTC date YYYY-MM-DD"
},
"to": {
"type": "string",
"description": "Exclusive UTC date; range must be positive and at most 366 days"
},
"owner": {
"type": "string",
"description": "Required for wallet_performance"
},
"type": {
"type": "string",
"description": "Required for token_cohorts and token_risk"
},
"limit": {
"type": "integer",
"description": "1 to 100, default20"
},
"maxChargeUnits": {
"type": "integer",
"description": "500 to 1000000 micro-USDC; default10000"
}
},
"required": [
"operation",
"from",
"to"
],
"additionalProperties": false
}
}
}
}
}
},
"/api/v1/research/jobs/{id}": {
"get": {
"summary": "Read research status, result, evidence coverage and usage receipt",
"operationId": "get_research_jobs__id_",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
}
},
"delete": {
"summary": "Request cancellation of a research job",
"operationId": "delete_research_jobs__id_",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
}
}
},
"/api/v1/research/jobs/{id}/cancel": {
"post": {
"summary": "Request cancellation of a research job",
"operationId": "post_research_jobs__id__cancel",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}
}
}
}
}
},
"/api/v1/research/jobs/{id}/events": {
"get": {
"summary": "Stream status events for up to 55 seconds; reconnect or poll status",
"operationId": "get_research_jobs__id__events",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful versioned response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"description": "Authentication required"
},
"429": {
"description": "Rate, free allowance or daily spending limit. Retry-After gives the seconds to wait"
},
"503": {
"description": "Service temporarily unavailable"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
},
"walletSession": {
"type": "apiKey",
"in": "cookie",
"name": "yolo_session"
}
},
"schemas": {
"Response": {
"type": "object",
"required": [
"version",
"requestId",
"data"
],
"properties": {
"version": {
"const": "1"
},
"requestId": {
"type": "string"
},
"data": {},
"usage": {
"type": "object",
"properties": {
"chargedUnits": {
"type": "integer"
},
"balanceUnits": {
"type": "integer"
}
}
}
}
}
}
}
}Guide for models
The whole API in plain text, sized for a model's context.
Text
# yolo API for humans and agents
Base URL: https://yolo.casa/api/v1
Human documentation: https://yolo.casa/api
Hosted MCP: https://yolo.casa/mcp
OAuth issuer: https://yolo.casa/oauth
OpenAPI 3.1: https://yolo.casa/api/openapi.json
Status: https://yolo.casa/status (JSON: GET /api/v1/status)
Stream: wss://yolo.casa/api/v1/stream (SSE: https://yolo.casa/api/v1/stream/sse)
Sui mainnet data, real-time streams, aggregated routing, lending and unsigned transaction building.
## Tiers and limits
No key: 30 requests per minute, 2000 free market-data requests per day, per IP. Market data only.
Free key (no credits needed): 120 requests per minute, 20000 free market-data requests per day.
Funded key (any verified top-up): 600 requests per minute, 20000 free market-data requests per day; past the free allowance each request costs its listed price. Analytics and lending builds always cost their listed price and need credits.
Sui swap quotes and builds are free to call with any key that has the quote or build scope, funded or not. They use no credits and do not count against the free allowance or the daily budget; only the per-minute limit and four running calls per key apply.
## Swaps and fees
Free to call. Each swap pays a 20 bps (0.2%) yolo fee on chain, inside the swap transaction. The fee goes to yolo's fee wallet in USDC: taken from the USDC you pay on a buy, from the USDC you receive on a sell (on the guaranteed minimum), and swapped to USDC from the input when neither side is USDC. The website's own trading fee is separate and unchanged.
swap/quote returns amountOut net of every fee, so you can compare it directly with other routers. It also returns feeBps, fee (bps, mode, coinType, amount taken from the trade, and usdc, its estimate in USDC) and, with a partner fee, partnerFeeBps and partnerFee (bps, recipient, coinType, amount).
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 partnerAddress, on top of yolo's fee. A partner fee is fixed by the quote; swap/build may repeat it but not change it.
swap/build returns fees: each fee step in the transaction or plan (kind yolo or partner, recipient, bps, coinType, amount). In mode commands the fee steps are commands of the plan, and addYoloRoute refuses a plan whose listed fee steps are missing.
Every data response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds). A 429 carries Retry-After with the exact seconds to wait: rate_limit resets each minute, free_limit and budget_limit at 00:00 UTC. GET /usage reports a key's tier, limits and usage.
## Data conventions
Lists return items and nextCursor. Pass nextCursor back as cursor for the next page; null means the last page. A value that is not known is null, never zero. Where data has limits the response includes coverage. Times are Unix milliseconds unless a field says seconds (candle time and before are seconds). Coin types and addresses are normalized to full length.
History: trades, candles and wallet P/L reach back to Sui mainnet's start in May 2023. GET /status reports the time each dataset is complete through. Page candles back with before.
## Real-time stream
Connect a WebSocket to wss://yolo.casa/api/v1/stream. Send Authorization: Bearer YOUR_API_KEY on the upgrade request, or send {"op":"auth","key":"YOUR_API_KEY"} as the first message. Without a key the connection is anonymous.
Subscribe: {"op":"subscribe","topics":["trades:COIN_TYPE","launches"]}. Unsubscribe: {"op":"unsubscribe","topics":[...]}. The reply lists accepted topics and rejected ones with a reason.
Topics:
- trades:<coinType>: Every trade of one coin.
- price:<coinType>: One coin's price, at most two ticks a second.
- wallet:<address>: Trades made by one wallet.
- launches: Every new launchpad coin.
- launches:<launchpad>: New coins on one launchpad.
- graduations: Coins that bonded and left their curve.
- large_trades: Trades of $10,000 or more.
- large_trades:<usd>: Trades of at least this many dollars, 1000 or more.
- firehose: Every trade, launch and graduation. Funded keys only.
- prices: Every coin's price ticks. Funded keys only.
Events: {"type":"event","seq":123,"channel":"trade","topics":["trades:COIN_TYPE"],"ts":1791388805201,"data":{...}}. One event is sent once per connection even when several of your topics match; topics lists them. Trades arrive about half a second after their checkpoint.
Heartbeat: the server sends {"type":"ping","seq":N,"ts":MS} every 15 seconds. If you see nothing for 45 seconds, reconnect.
Resume: the hello message carries epoch and seq. After a reconnect send {"op":"subscribe","topics":[...],"resume":{"epoch":"EPOCH","seq":LAST_SEQ}} to receive what you missed. The buffer holds about two minutes. A resume_failed reply means the gap is gone: refetch over REST.
Slow consumers are disconnected with close code 4008 rather than slowing others. Other close codes: 4001 invalid key, 4009 key revoked, 4029 connection limit, 4000 server restart.
Limits. No key: 2 connections, 10 topics per connection, 3 wallets per connection. Free key: 3 connections, 100 topics per connection, 25 wallets per connection. Funded key: 20 connections, 2000 topics per connection, 500 wallets per connection.
firehose and prices cost 1000 micro-USDC (1 credit) per started minute per connection, charged to the key's account and counted against its daily budget.
SSE fallback: GET https://yolo.casa/api/v1/stream/sse?topics=trades:COIN_TYPE,launches with the same Authorization header. Each event's id is its seq; reconnect with Last-Event-ID to resume.
## Authentication
POST /auth/challenge with {"address":"YOUR_SUI_WALLET"}. Sign the returned message as a Sui personal message with that wallet. POST /auth/keys with address, challengeId and signature. Save the returned key: it is shown once.
Send Authorization: Bearer YOUR_API_KEY on authenticated requests. Keep keys out of URLs and logs. Keys belong to the signing wallet, have a daily spending budget and can be revoked. Browser account management also accepts a signed-in yolo session.
## Credits and payment
1 USDC = 1000 credits. Internally, amounts and prices use integer micro-USDC: 1000000 units = 1 USDC; 1000 units = 1 credit. Read /account for available and reserved balance, the canonical coin type and the configured payment recipient. API credits pay request fees; wallet gas and trading amounts are separate.
1. POST /credits/intent with {"amountUnits":"1000000"} for a 1 USDC top-up.
2. Use your own wallet to sign and execute the returned unsigned transaction kind on Sui mainnet. Preserve its commands exactly; the wallet adds gas.
3. POST /credits/deposit with {"intentId":"RETURNED_INTENT_ID","digest":"FINALIZED_TRANSACTION_DIGEST"}.
The service verifies successful finality, sender, transaction kind and the actual USDC received before crediting the account. Each payment is credited once. An arbitrary transfer or a claimed amount does not create credits.
## Automatic agent top-ups
Use a wallet signing callback in the SDK, with an explicit maximum payment amount. When a request returns 402, create a top-up intent, have the agent's wallet execute it, verify the deposit, then retry the same request using the same Idempotency-Key. The server never holds the agent's wallet key or signs its transactions. Concurrent calls should share one top-up rather than creating duplicate payments. Download the standalone SDK from https://yolo.casa/sdk/yolo-api.js. Supply paymentReceiptStore.load/save backed by durable storage for unattended agents: the SDK persists an intent before invoking your wallet and retains its digest until acknowledged. If the wallet outcome is unknown, recover the original digest with acknowledgePayment; never submit a second payment blindly. maxTotalUnits applies per client instance; enforce a long-term funding budget in your wallet service.
## Historical research
Use a key or OAuth grant with research scope. POST /research/estimate with operation, inclusive UTC from, exclusive UTC to, and maxChargeUnits. Ranges are positive and at most 366 days. estimatedChargeUnits is null: actual scanned bytes are unknown before execution. POST /research/jobs with the same validated body and an Idempotency-Key, poll GET /research/jobs/{id}, and inspect result coverage and receipt.readBytes/chargedUnits before making a decision. Price: 500 micro-USDC base plus 100 micro-USDC per rounded-up MiB. The requested cap is reserved; unused units are released after reconciliation. Status and estimate are free. Cancellation is best effort; completed work may still be charged. token_risk describes known-basis trading activity evidence, not a blanket safety score.
Workflow: research trader_rankings or token_cohorts, inspect evidence and coverage, request a fresh swap quote, then build an unsigned transaction with a bounded slippage setting. Check simulation, signing address, expiry, expected balance changes and gasEstimateMist. Your wallet signs only after your own review.
## Hosted MCP and OAuth
Connect a streamable HTTP MCP client to https://yolo.casa/mcp. Use OAuth at https://yolo.casa/oauth or send a scoped API key as Authorization: Bearer YOUR_API_KEY. Every data operation above is a tool named after its path with slashes and dashes as underscores (token_security, wallet_pnl, smart_money); status and usage are free tools. Browser consent and active grant revocation are managed at https://yolo.casa/api. Request offline_access and prompt=consent explicitly when refresh access is needed. Never send a wallet private key to the service.
Hosted tools: account is free. research_estimate previews coverage and pricing; research_start requires idempotencyKey and reserves maxChargeUnits; research_status reads result/receipt; research_cancel requests cancellation. funding_intent takes amountUnits and idempotencyKey and returns an unsigned automatic payment under the owner policy. The caller wallet signs it; funding_confirm acknowledges intentId and its original digest. Keep the funding request key and receipt when retrying, and never pay again after an unknown outcome. swap_quote and swap_build use the same reviewed routing workflow.
## Durable funding limits
GET /credits/funding-policy reads account-wide limits. Only a signed-in wallet session may POST enabled, maxTopupUnits, dailyLimitUnits and lifetimeLimitUnits. Automatic funding is disabled by default. SDK automatic intents send automatic:true and a dedicated Idempotency-Key; limits persist across keys and restarts. This policy authorizes API top-ups, not trading execution. Unknown wallet outcomes must recover the original receipt. GET /activity exposes fixed request and research accounting receipts.
## Requests, retries and accounting
Send Content-Type: application/json for POST. Idempotency-Key is required for paid POST and recommended for paid GET. A key identifies the same operation and input: reusing it with different input returns 409. Successful replay returns the stored result without charging twice. Failed operations release reserved credits; a refunded request must be retried with a new Idempotency-Key. A pending request can return 409; retry it with the same key. 401 means invalid credentials, 402 insufficient credits, 429 a rate, free allowance or budget limit (read Retry-After), and 503 a temporarily unavailable service. Free requests are not stored for replay; Idempotency-Key matters only on charged requests.
Success envelope: {"version":"1","requestId":"...","data":{},"usage":{"chargedUnits":100,"balanceUnits":999900,"tier":"funded","freeRemaining":0}}. Usage is present on data and metered calls; balanceUnits is null without a key. Error envelope: {"version":"1","requestId":"...","error":{"code":"...","message":"..."}}. Never retry a completed trade by rebuilding and executing it blindly: these endpoints build unsigned transactions, while execution remains your wallet's responsibility.
## Endpoints
- GET /api/v1/discovery: Discover capabilities and current prices; no request charge.
- POST /api/v1/auth/challenge: Request a wallet ownership challenge; no request charge. Fields: address. Required: address.
- POST /api/v1/auth/keys: Sign the challenge and create an API key; no request charge. Fields: address, challengeId, signature, name, dailyBudgetUnits, scopes. Required: address, challengeId, signature.
- GET /api/v1/account: Read credit balance, payment recipient and pricing; no request charge.
- GET /api/v1/keys: List your keys with a wallet session; bearer authentication lists only its own key; no request charge.
- POST /api/v1/keys: Create a key from your signed-in account; no request charge. Fields: name, dailyBudgetUnits, scopes. Required: name.
- DELETE /api/v1/keys/{id}: Revoke a key; no request charge.
- POST /api/v1/credits/intent: Build an unsigned USDC top-up transaction; no request charge. Fields: amountUnits, automatic. Required: amountUnits.
- POST /api/v1/credits/deposit: Verify a completed payment and credit your account once; no request charge. Fields: intentId, digest. Required: intentId, digest.
- GET /api/v1/tokens: List Sui tokens: trending, new, top, gainers, bonding, graduated; free within the daily allowance, then 100 micro-USDC (0.1 credits) per successful request. Fields: list, limit, offset. Required: none.
- GET /api/v1/search: Search tokens by symbol, name or coin type; free within the daily allowance, then 100 micro-USDC (0.1 credits) per successful request. Fields: q, limit. Required: q.
- GET /api/v1/trending: Trending tokens ranked by real traders, each with the reason it ranks; free within the daily allowance, then 100 micro-USDC (0.1 credits) per successful request. Fields: limit, cursor. Required: none.
- GET /api/v1/pulse: Launchpad coins in three columns: new, about to bond, and bonded; free within the daily allowance, then 100 micro-USDC (0.1 credits) per successful request. Fields: sort, launchpad. Required: none.
- GET /api/v1/launches: Newest launches, optionally for one launchpad; free within the daily allowance, then 100 micro-USDC (0.1 credits) per successful request. Fields: launchpad, limit, cursor. Required: none.
- GET /api/v1/token: One token's market data, and whether it is a CTO (community takeover) with its CTO score; free within the daily allowance, then 100 micro-USDC (0.1 credits) per successful request. Fields: type. Required: type.
- GET /api/v1/candles: OHLCV candles. Page back with before; history reaches mid 2023 where the coin existed; free within the daily allowance, then 200 micro-USDC (0.2 credits) per successful request. Fields: type, tf, limit, before. Required: type.
- GET /api/v1/trades: A token's trades, newest first; free within the daily allowance, then 200 micro-USDC (0.2 credits) per successful request. Fields: type, before. Required: type.
- GET /api/v1/token/security: Risk checks: mint, freeze and metadata control, dev, insiders, snipers, bundles, top 10 share, liquidity; free within the daily allowance, then 200 micro-USDC (0.2 credits) per successful request. Fields: type. Required: type.
- GET /api/v1/token/holders: Holders by size with labels, cost basis and P/L; free within the daily allowance, then 200 micro-USDC (0.2 credits) per successful request. Fields: type, limit, cursor. Required: type.
- GET /api/v1/token/bubbles: Bubble map of the top 100 holders: funding clusters, bundles, snipers, insiders; 500 micro-USDC (0.5 credits) per successful request. Fields: type. Required: type.
- GET /api/v1/token/top-traders: A token's top traders in a window; 500 micro-USDC (0.5 credits) per successful request. Fields: type, window, sort, limit. Required: type.
- GET /api/v1/token/pnl: All-time winners and losers of a token by realized, unrealized or total P/L; 500 micro-USDC (0.5 credits) per successful request. Fields: type, side, sort, limit, cursor. Required: type.
- GET /api/v1/token/cost-basis: Where holders bought: cost basis distribution of a token; 500 micro-USDC (0.5 credits) per successful request. Fields: type. Required: type.
- GET /api/v1/wallet/portfolio: A wallet's coins, value, cost basis, perps account and DeFi positions; 500 micro-USDC (0.5 credits) per successful request. Fields: address. Required: address.
- GET /api/v1/wallet/pnl: A wallet's realized and unrealized P/L, win rate, volume and per-coin results in a window; 500 micro-USDC (0.5 credits) per successful request. Fields: address, window. Required: address.
- GET /api/v1/wallet/pnl-series: A wallet's P/L over time, for charts; 200 micro-USDC (0.2 credits) per successful request. Fields: address, window. Required: address.
- GET /api/v1/wallet/trades: A wallet's trades, newest first, back to mid 2023; free within the daily allowance, then 200 micro-USDC (0.2 credits) per successful request. Fields: address, coin, side, minUsd, since, limit, cursor. Required: address.
- GET /api/v1/wallet/labels: Names and labels for up to 50 wallets: KOL, exchange, smart money, whale, SuiNS; free within the daily allowance, then 100 micro-USDC (0.1 credits) per successful request. Fields: addresses. Required: addresses.
- GET /api/v1/wallet/search: Find traders by username, SuiNS name or address; free within the daily allowance, then 100 micro-USDC (0.1 credits) per successful request. Fields: q. Required: q.
- GET /api/v1/wallet/xray: A wallet's trading style and history at a glance; 1000 micro-USDC (1 credits) per successful request. Fields: address. Required: address.
- GET /api/v1/wallet/flows: What a wallet received and sent in transfers, per coin, or its top counterparties; 1000 micro-USDC (1 credits) per successful request. Fields: address, window, coin, counterparties. Required: address.
- GET /api/v1/wallet/copy-backtest: What copying a wallet's trades would have returned; 1000 micro-USDC (1 credits) per successful request. Fields: address, usd, window, delaySec, slippageBps, feeBps. Required: address.
- GET /api/v1/dev/report: A developer wallet's launch record; 500 micro-USDC (0.5 credits) per successful request. Fields: address. Required: address.
- GET /api/v1/smart-money: Trades by smart money, whales and KOLs, newest first; free within the daily allowance, then 200 micro-USDC (0.2 credits) per successful request. Fields: who, minUsd, limit, cursor. Required: none.
- GET /api/v1/leaderboard: Top wallets or teams by realized P/L. A launchpad filter ranks traders of that launchpad's coins; 200 micro-USDC (0.2 credits) per successful request. Fields: window, view, launchpad, limit. Required: none.
- GET /api/v1/launchpads: Launchpads with fees, status and listed coin counts; free within the daily allowance, then 100 micro-USDC (0.1 credits) per successful request.
- GET /api/v1/launchpads/league: Launchpads compared over 7 days, 30 days and all time; 200 micro-USDC (0.2 credits) per successful request.
- GET /api/v1/perps/markets: Perps markets with mark price, open interest, funding rate and next funding time; free within the daily allowance, then 100 micro-USDC (0.1 credits) per successful request.
- GET /api/v1/perps/market: One perps market by id or symbol; free within the daily allowance, then 100 micro-USDC (0.1 credits) per successful request. Fields: id. Required: id.
- GET /api/v1/perps/candles: A perps market's candles; free within the daily allowance, then 200 micro-USDC (0.2 credits) per successful request. Fields: id, tf, limit, before. Required: id.
- GET /api/v1/status: Service status: API, stream, indexer lag and the time each dataset is complete through; no request charge.
- GET /api/v1/usage: This key's tier, limits, free requests used today and credits spent today; no request charge.
- GET /api/v1/lending/markets: Compare available lending markets; 100 micro-USDC (0.1 credits) per successful request.
- GET /api/v1/lending/positions: Read a wallet's lending positions; 1000 micro-USDC (1 credits) per successful request. Fields: owner. Required: none.
- POST /api/v1/swap/quote: Get an aggregated swap quote. amountOut is what the wallet receives after every fee; feeBps, fee and partnerFee show the fees; Free to call. Each swap pays a 20 bps (0.2%) yolo fee on chain, inside the swap transaction. Fields: coinIn, coinOut, amountIn, owner, partnerFeeBps, partnerAddress. Required: coinIn, coinOut, amountIn.
- POST /api/v1/swap/build: Build an unsigned swap, or its route commands, for a wallet; Free to call. Each swap pays a 20 bps (0.2%) yolo fee on chain, inside the swap transaction. Fields: id, mustBeat, slippageBps, owner, mode, partnerFeeBps, partnerAddress. Required: id.
- GET /api/v1/route-commands.ts: TypeScript helper with no dependencies: addYoloRoute(tx, plan, coinIn) appends a commands-mode plan to your Transaction and returns the output coin; no request charge.
- POST /api/v1/lending/build: Build an unsigned lending deposit or withdrawal; 5000 micro-USDC (5 credits) per successful request. Fields: protocol, action, amountUnits, all. Required: protocol, action.
- GET /api/v1/credits/funding-policy: Read account-wide automatic funding limits and usage; no request charge.
- POST /api/v1/credits/funding-policy: Enable or disable durable funding limits from a wallet session; no request charge. Fields: enabled, maxTopupUnits, dailyLimitUnits, lifetimeLimitUnits. Required: enabled, maxTopupUnits, dailyLimitUnits, lifetimeLimitUnits.
- GET /api/v1/activity: Read request and research receipts; bearer keys see only their own activity; no request charge. Fields: limit. Required: none.
- POST /api/v1/research/estimate: Preview coverage and pricing without scanning history; actual charge is unknown until execution; no request charge. Fields: operation, from, to, owner, type, limit, maxChargeUnits. Required: operation, from, to.
- POST /api/v1/research/jobs: Reserve a spending cap and enqueue scoped historical research; 500 micro-USDC base plus 100 micro-USDC per rounded-up MiB read; reserve maxChargeUnits. Fields: operation, from, to, owner, type, limit, maxChargeUnits. Required: operation, from, to.
- GET /api/v1/research/jobs/{id}: Read research status, result, evidence coverage and usage receipt; no request charge.
- DELETE /api/v1/research/jobs/{id}: Request cancellation of a research job; no request charge.
- POST /api/v1/research/jobs/{id}/cancel: Request cancellation of a research job; no request charge.
- GET /api/v1/research/jobs/{id}/events: Stream status events for up to 55 seconds; reconnect or poll status; no request charge.
## Examples
curl 'https://yolo.casa/api/v1/trending?limit=20'
curl 'https://yolo.casa/api/v1/token/security?type=0x2::sui::SUI' \
-H 'Authorization: Bearer YOUR_API_KEY'
curl 'https://yolo.casa/api/v1/wallet/pnl?address=YOUR_SUI_WALLET&window=30d' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Idempotency-Key: wallet-pnl-001'
## 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.
Coin amounts for swaps are strings in integer base units. Lending amountUnits are strings in integer micro-USDC. Preserve all returned transaction kind bytes. Swaps for your users: pass owner (their wallet) to swap/quote and swap/build. Any key can ask swap/build for mode commands and add the plan to their own transaction with addYoloRoute(tx, plan, coinIn) from https://yolo.casa/api/v1/route-commands.ts; coinIn must hold exactly plan.amountIn (fees included), the plan's fee steps run first, the output coin is returned untransferred, and the transaction aborts below plan.minOut. Request limits, deadlines, daily budgets and available credit are enforced server-side. Data carries its available history coverage; token unrealized P/L is estimated from recorded positions and available prices.