{ "openapi": "3.1.0", "info": { "title": "Shield Swap API", "description": "Shield Swap REST API for pools, positions, swaps, routes, quotes, settlement status, and transaction input schemas. Transactions target the configured shield_swap program and `token_registry.aleo`.\n\n## Numeric wire format\n\nExact financial values are JSON strings, not JSON numbers. Unsigned decimal inputs use ASCII digits and an optional `.` fraction, for example `\"1234.50\"`; base-unit integers use ASCII digits only. Grouping separators, localized decimal commas, signs, exponent notation, whitespace, Unicode digits, and redundant leading zeros are not accepted for those inputs. Signed response metrics may include a leading `-`. Clients should localize only for display and convert user input back to this canonical form before sending it.\n\n## Authentication\n\nMost endpoints require credentials from an invited wallet. Public routes are `/health`, `/ready`, `/metrics`, `/auth/*`, `/protocol/state`, `/compliance*`, `GET /tokens*`, `GET /pools`, `GET /pools/stats`, and `GET /pools/{key}`.\n\nBrowsers use HTTP-only session cookies issued by `/auth/verify`. Access sessions last 15 minutes and are renewed through `/auth/refresh`. Programmatic clients use a long-lived token from `POST /api-tokens` as `Authorization: Bearer ss_…`. API tokens cover data and trading routes and can request WebSocket tickets. Token management, code redemption, and admin routes require a browser session.\n\n## WebSocket feed\n\nThe live feed runs on the separate websocket gateway at `GET /ws`.\n\n1. Request a ticket from `GET /auth/ws-ticket` using a browser session or API token.\n2. Open the socket and send the `authenticate` frame within 5 seconds.\n3. Subscribe to each required room.\n4. Before the 60-second ticket expires, request a new ticket and send another `authenticate` frame.\n\nThe socket accepts WebSocket tickets only. Session JWTs and API tokens are rejected.\n\n```json\n{\"action\": \"authenticate\", \"token\": \"\"}\n{\"action\": \"subscribe\", \"room\": \"trades:\"}\n{\"action\": \"unsubscribe\", \"room\": \"\"}\n{\"action\": \"synchronize\"}\n```\n\nAfter reconnecting, resend subscriptions and then send `synchronize`. The gateway replies `{\"control\": \"synchronized\"}` when those subscriptions are active. Refetch any REST data that depends on the stream after receiving the reply.\n\nEach connection allows 32 rooms, 240 client frames per minute, and 2 KB per frame. A client may subscribe only to the balance room for its ticket subject.\n\nRooms:\n- `pool_launches`: newly created pools\n- `pool_stats:`: price & liquidity updates\n- `ohlcv:`: candle updates\n- `trades:`: swaps / mints / burns\n- `balances:
`: balance-change hints for an address\n\n- `protocol_config`: revisioned protocol-configuration invalidations\n\nServer messages are either events (`{\"type\": , \"data\": { … }}`) or control messages (`{\"control\": }`). Event types are `PoolLaunch`, `PoolStats`, `Ohlcv`, `Trade`, `BalanceChange`, and `ProtocolConfigChanged`. Its data contains `revision`, `observed_block`, and the changed `scope`/`key` pairs. Financial fields use the numeric format described above.\n\nTreat `ProtocolConfigChanged` as an invalidation, not as the new configuration. Fetch `GET /protocol/state?minimum_revision=`; retry a `503 protocol_revision_pending` after the advertised `Retry-After`; and discard or requote any `/route` result whose `protocol_revision` is older. Subscribe to `pool_stats:` separately when live price and liquidity updates matter.\n\nThe gateway currently sends `synchronized` and `resync_required` controls. `resync_required` means the stream may have missed updates, so refetch affected data over REST. Ignore unknown control values.\n\nEvent delivery is at most once. Treat REST as the source of truth. During a deployment the gateway may close the socket with code 1012 (service restart); reconnect and restore the subscriptions.", "contact": { "name": "Shield Swap" }, "license": { "name": "" }, "version": "0.1.0" }, "servers": [ { "url": "https://api.swap.shield.fi", "description": "Shield Swap mainnet API" } ], "paths": { "/access/codes": { "get": { "tags": [ "access" ], "operationId": "access_list_codes", "parameters": [ { "name": "limit", "in": "query", "description": "Page size (1-2000)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Page offset", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Access-code inventory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessListResponseDoc" } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "403": { "description": "Administrator authorization required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "List access codes", "x-mint": { "metadata": { "title": "List access codes", "sidebarTitle": "List access codes", "description": "List application access codes with administrator authorization." } } } }, "/access/generate": { "post": { "tags": [ "access" ], "operationId": "access_generate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessGenerateRequest" } } }, "required": true }, "responses": { "200": { "description": "Generated access codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessGenerateResponseDoc" } } } }, "400": { "description": "Malformed JSON request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "403": { "description": "Administrator authorization required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "422": { "description": "Request body does not match schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Generate access codes", "x-mint": { "metadata": { "title": "Generate access codes", "sidebarTitle": "Generate access codes", "description": "Generate application access codes with administrator authorization." } } } }, "/access/redeem": { "post": { "tags": [ "access" ], "operationId": "access_redeem", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessRedeemRequest" } } }, "required": true }, "responses": { "200": { "description": "Access code redeemed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessRedeemResponseDoc" } } } }, "400": { "description": "Invalid or already-used code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "422": { "description": "Request body does not match schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Redeem an access code", "x-mint": { "metadata": { "title": "Redeem an access code", "sidebarTitle": "Redeem an access code", "description": "Redeem an application access code for the authenticated wallet." } } } }, "/access/status": { "get": { "tags": [ "access" ], "operationId": "access_status", "responses": { "200": { "description": "Wallet access status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessStatusResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Get access status", "x-mint": { "metadata": { "title": "Get access status", "sidebarTitle": "Get access status", "description": "Get the authenticated wallet's current application access status." } } } }, "/admin/sessions/revoke": { "post": { "tags": [ "auth" ], "operationId": "admin_revoke_sessions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeSessionsRequest" } } }, "required": true }, "responses": { "200": { "description": "All of the wallet's sessions revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeSessionsResponseDoc" } } } }, "400": { "description": "Malformed JSON or invalid address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "403": { "description": "Administrator authorization required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "422": { "description": "Request body does not match schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Admin revoke sessions", "x-mint": { "metadata": { "title": "Admin revoke sessions", "sidebarTitle": "Admin revoke sessions", "description": "Revoke sessions through the protected administrator operation." } } } }, "/airdrop": { "post": { "tags": [ "airdrop" ], "summary": "Request test tokens", "description": "Delivers configured amounts of ALEO, USDCx, and ETH to the given address as\nrecords via `transfer_public_to_private`, spent from the\ntreasury's public balance in each target's underlying program. One claim\nper recipient address per 15 minutes (429 after that).\n\nProving each token takes ~15-30s, so this returns immediately with\n`status: \"running\"` + a `job_id`. The transfers run in a detached worker\n(capped concurrency, per-token timeout); poll `GET /airdrop/{job_id}` until\n`status == \"complete\"` to read per-token results.\n\nRequired env: `DEPLOYER_PRIVATE_KEY` (the treasury key whose public balances\nfund every airdrop; `AIRDROP_PRIVATE_KEY` honored as a fallback),\n`RPC_URLS` (first entry used).", "operationId": "airdrop", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AirdropRequest" } } }, "required": true }, "responses": { "200": { "description": "Airdrop job started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AirdropStartResponseDoc" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "422": { "description": "Request body does not match schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "429": { "description": "Airdrop already claimed for this address in the last 15 minutes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Misconfigured server (missing env vars)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "x-mint": { "metadata": { "title": "Request test tokens", "sidebarTitle": "Request test tokens", "description": "Start a background request for the configured test token set." } } } }, "/airdrop/{job_id}": { "get": { "tags": [ "airdrop" ], "summary": "Get a test-token request", "description": "Returns the current state of a background airdrop job: `status`\n(`\"running\"` | `\"complete\"`), the expected `total`, and the per-token\n`results` collected so far.", "operationId": "airdrop_status", "parameters": [ { "name": "job_id", "in": "path", "description": "Job id returned by POST /airdrop", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current airdrop job state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AirdropJobResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "404": { "description": "Unknown job id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal job-store error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "x-mint": { "metadata": { "title": "Get a test-token request", "sidebarTitle": "Get a test-token request", "description": "Retrieve the current state and per-token results for a test-token request." } } } }, "/api-tokens": { "get": { "tags": [ "api-tokens" ], "operationId": "api_tokens_list", "responses": { "200": { "description": "API tokens for the authenticated wallet (no secrets)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTokenListResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "403": { "description": "Invite access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "List API tokens", "x-mint": { "metadata": { "title": "List API tokens", "sidebarTitle": "List API tokens", "description": "List API tokens owned by the authenticated wallet without returning their secrets." } } }, "post": { "tags": [ "api-tokens" ], "operationId": "api_tokens_create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTokenCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "API token created; the token value is shown only once", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTokenCreatedResponseDoc" } } } }, "400": { "description": "Invalid name, expiry, or active-token limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "403": { "description": "Invite access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "422": { "description": "Request body does not match schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "429": { "description": "Too many attempts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Create an API token", "x-mint": { "metadata": { "title": "Create an API token", "sidebarTitle": "Create an API token", "description": "Create an API token whose secret is returned once." } } } }, "/api-tokens/{id}": { "delete": { "tags": [ "api-tokens" ], "operationId": "api_tokens_revoke", "parameters": [ { "name": "id", "in": "path", "description": "Token id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "API token revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTokenRevokeResponseDoc" } } } }, "400": { "description": "Malformed token id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "403": { "description": "Invite access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "404": { "description": "Token not found or already revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Revoke an API token", "x-mint": { "metadata": { "title": "Revoke an API token", "sidebarTitle": "Revoke an API token", "description": "Revoke one API token owned by the authenticated wallet." } } } }, "/auth/challenge": { "post": { "tags": [ "auth" ], "operationId": "challenge", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChallengeRequestDoc" } } }, "required": true }, "responses": { "200": { "description": "Challenge nonce + message to sign", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChallengeResponseDoc" } } } }, "400": { "description": "Malformed JSON or invalid address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "422": { "description": "Request body schema mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "summary": "Request a sign-in challenge", "x-mint": { "metadata": { "title": "Request a sign-in challenge", "sidebarTitle": "Request a sign-in challenge", "description": "Create the nonce and message a wallet must sign to start a session." } } } }, "/auth/logout": { "post": { "tags": [ "auth" ], "operationId": "logout", "responses": { "200": { "description": "Presented refresh-token family ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogoutResponseDoc" } } } }, "400": { "description": "Invalid session binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "403": { "description": "Missing or invalid CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "409": { "description": "Session identity changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "summary": "Sign out this session", "x-mint": { "metadata": { "title": "Sign out this session", "sidebarTitle": "Sign out this session", "description": "Revoke the current browser session and clear its authentication cookies." } } } }, "/auth/logout-all": { "post": { "tags": [ "auth" ], "operationId": "logout_all", "responses": { "200": { "description": "Every wallet session revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogoutAllResponseDoc" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "403": { "description": "Missing or invalid CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "409": { "description": "Session identity changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "503": { "description": "Session revocation state unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "summary": "Sign out all sessions", "x-mint": { "metadata": { "title": "Sign out all sessions", "sidebarTitle": "Sign out all sessions", "description": "Revoke every session for the authenticated wallet." } } } }, "/auth/refresh": { "post": { "tags": [ "auth" ], "operationId": "refresh", "responses": { "200": { "description": "Refresh token rotated; fresh access + refresh cookies set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponseDoc" } } } }, "401": { "description": "Missing, invalid, expired, or revoked refresh token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "409": { "description": "Session identity changed or a concurrent refresh already rotated this token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "summary": "Refresh a session", "x-mint": { "metadata": { "title": "Refresh a session", "sidebarTitle": "Refresh a session", "description": "Rotate the refresh token and issue fresh browser session cookies." } } } }, "/auth/session": { "get": { "tags": [ "auth" ], "operationId": "session", "responses": { "200": { "description": "Current session identity + access expiry; re-seeds the CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponseDoc" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "503": { "description": "Session revocation state unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "summary": "Get the current session", "x-mint": { "metadata": { "title": "Get the current session", "sidebarTitle": "Get the current session", "description": "Retrieve the current wallet session and reseed its CSRF token." } } } }, "/auth/sessions": { "get": { "tags": [ "auth" ], "operationId": "list_sessions", "responses": { "200": { "description": "Active sessions for the signed-in wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActiveSessionsResponseDoc" } } } }, "401": { "description": "Missing or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "429": { "description": "Session management rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Session lookup failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "503": { "description": "Session validation unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "summary": "List wallet sessions", "x-mint": { "metadata": { "title": "List wallet sessions", "sidebarTitle": "List wallet sessions", "description": "List active sessions for the authenticated wallet." } } } }, "/auth/sessions/{session_id}/revoke": { "post": { "tags": [ "auth" ], "operationId": "revoke_session", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Session revoked, or already inactive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeSessionResponseDoc" } } } }, "401": { "description": "Missing or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "403": { "description": "Missing or mismatched CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "429": { "description": "Session management rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Revocation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "503": { "description": "Session validation unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "summary": "Revoke a wallet session", "x-mint": { "metadata": { "title": "Revoke a wallet session", "sidebarTitle": "Revoke a wallet session", "description": "Revoke one session owned by the authenticated wallet." } } } }, "/auth/verify": { "post": { "tags": [ "auth" ], "operationId": "verify", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequestDoc" } } }, "required": true }, "responses": { "200": { "description": "Session established via httpOnly cookies; body carries the CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponseDoc" } } } }, "400": { "description": "Malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "401": { "description": "Invalid / expired signature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "409": { "description": "Session state changed during verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "422": { "description": "Request body schema mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "summary": "Verify a wallet signature", "x-mint": { "metadata": { "title": "Verify a wallet signature", "sidebarTitle": "Verify a wallet signature", "description": "Verify the signed challenge and establish the browser session cookies." } } } }, "/auth/ws-ticket": { "get": { "tags": [ "auth" ], "operationId": "ws_ticket", "responses": { "200": { "description": "Short-lived (60s) JWT the WebSocket client presents in its authenticate frame", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenResponseDoc" } } } }, "400": { "description": "Invalid identity binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "401": { "description": "No valid session or API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "409": { "description": "Credential identity changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "429": { "description": "API token rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "503": { "description": "Session revocation state unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "summary": "Create a WebSocket ticket", "x-mint": { "metadata": { "title": "Create a WebSocket ticket", "sidebarTitle": "Create a WebSocket ticket", "description": "Create the short-lived ticket used in the first WebSocket authentication frame." } } } }, "/balances": { "get": { "tags": [ "balances" ], "operationId": "list_balances", "responses": { "200": { "description": "Per-token on-chain authorized balances", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceListResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal database or RPC error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Get balances", "x-mint": { "metadata": { "title": "Get balances", "sidebarTitle": "Get balances", "description": "List authorized on-chain token balances for the authenticated wallet." } } } }, "/compliance": { "get": { "tags": [ "compliance" ], "operationId": "get_config", "responses": { "200": { "description": "Global pause / pool-creation gating state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalConfigResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "summary": "Get protocol controls", "x-mint": { "metadata": { "title": "Get protocol controls", "sidebarTitle": "Get protocol controls", "description": "Retrieve global pause and pool-creation control state." } } } }, "/compliance/pairs/{token0}/{token1}": { "get": { "tags": [ "compliance" ], "operationId": "get_pair_status", "parameters": [ { "name": "token0", "in": "path", "description": "First token id (Aleo field)", "required": true, "schema": { "type": "string" } }, { "name": "token1", "in": "path", "description": "Second token id (Aleo field)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pause state for a token pair (order-independent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairComplianceResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "summary": "Get pair controls", "x-mint": { "metadata": { "title": "Get pair controls", "sidebarTitle": "Get pair controls", "description": "Retrieve pause state for a token pair in either token order." } } } }, "/compliance/tokens/{token_id}": { "get": { "tags": [ "compliance" ], "operationId": "get_token_status", "parameters": [ { "name": "token_id", "in": "path", "description": "On-chain token id (Aleo field)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Allowlist / pause state for a single token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenComplianceResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "summary": "Get token controls", "x-mint": { "metadata": { "title": "Get token controls", "sidebarTitle": "Get token controls", "description": "Retrieve allowlist and pause state for one token." } } } }, "/debug/pool": { "get": { "tags": [ "debug" ], "operationId": "pool_debug", "parameters": [ { "name": "pool_key", "in": "query", "description": "Pool key", "required": true, "schema": { "type": "string" } }, { "name": "ticks", "in": "query", "description": "Comma-separated list of tick values to verify", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Raw on-chain pool slot + optional tick statuses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolDebugResponseDoc" } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal RPC error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Inspect pool state", "x-mint": { "metadata": { "title": "Inspect pool state", "sidebarTitle": "Inspect pool state", "description": "Retrieve the raw on-chain pool slot and optional tick status for debugging." } } } }, "/fee-tiers": { "get": { "tags": [ "protocol" ], "operationId": "list_fee_tiers", "responses": { "200": { "description": "Registered fee tiers and current tick-spacing bindings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeTierListResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "List fee tiers", "x-mint": { "metadata": { "title": "List fee tiers", "sidebarTitle": "List fee tiers", "description": "List the fee tiers registered for the configured deployment." } } } }, "/pools": { "get": { "tags": [ "pools" ], "operationId": "list_pools", "parameters": [ { "name": "limit", "in": "query", "description": "Page size (1-100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Page offset", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "include_valuation", "in": "query", "description": "Include the server USDC/USD valuation", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Paginated pools with token metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolListResponseDoc" } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "summary": "List pools", "x-mint": { "metadata": { "title": "List pools", "sidebarTitle": "List pools", "description": "List registered pools with token metadata, fees, enabled state, and pagination." } } } }, "/pools/stats": { "get": { "tags": [ "pools" ], "summary": "Batch pool statistics", "description": "Return rolling-24h stats for multiple pools in one request. The pools page\nuses this endpoint to avoid `N + 1` requests. The response omits unknown\nkeys and keys that fail. Callers treat an absent key as unavailable stats.\nThe endpoint accepts at most 100 unique keys to limit database and RPC load.\nAt most eight pool calculations run across all requests.\nEach calculation has a 10-second deadline, including capacity wait time.", "operationId": "get_pool_24h_stats_batch", "parameters": [ { "name": "keys", "in": "query", "description": "Comma-separated pool keys (max 100)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Map of pool key to 24h stats; failed or unknown keys can be absent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolStats24hBatchResponseDoc" } } } }, "400": { "description": "Empty / too-large keys list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "x-mint": { "metadata": { "title": "Batch pool statistics", "sidebarTitle": "Batch pool statistics", "description": "Retrieve rolling 24-hour statistics for up to 100 pools in one request." } } } }, "/pools/{key}": { "get": { "tags": [ "pools" ], "operationId": "get_pool", "parameters": [ { "name": "key", "in": "path", "description": "On-chain pool field key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pool state + stats + token metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolWithStatsResponseDoc" } } } }, "404": { "description": "Pool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "summary": "Get a pool", "x-mint": { "metadata": { "title": "Get a pool", "sidebarTitle": "Get a pool", "description": "Retrieve one pool by its canonical pool key." } } } }, "/pools/{key}/initialized-ticks": { "get": { "tags": [ "pools" ], "summary": "List initialized ticks", "description": "Used by the frontend mint flow to compute the correct\n`tick_lower_hint` / `tick_upper_hint` for the AMM's hint-walk asserts.", "operationId": "get_pool_initialized_ticks", "parameters": [ { "name": "key", "in": "path", "description": "Pool key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sorted initialized ticks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitializedTicksResponseDoc" } } } }, "404": { "description": "Pool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "x-mint": { "metadata": { "title": "List initialized ticks", "sidebarTitle": "List initialized ticks", "description": "List the initialized tick boundaries for a pool." } } } }, "/pools/{key}/liquidity-distribution": { "get": { "tags": [ "pools" ], "operationId": "get_pool_liquidity_distribution", "parameters": [ { "name": "key", "in": "path", "description": "Pool key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Initialized tick liquidity deltas", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiquidityDistributionResponseDoc" } } } }, "404": { "description": "Pool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Get liquidity distribution", "x-mint": { "metadata": { "title": "Get liquidity distribution", "sidebarTitle": "Get liquidity distribution", "description": "Retrieve the liquidity distributed across a pool's initialized ranges." } } } }, "/pools/{key}/ohlcv": { "get": { "tags": [ "pools" ], "operationId": "get_pool_ohlcv", "parameters": [ { "name": "key", "in": "path", "description": "Pool key", "required": true, "schema": { "type": "string" } }, { "name": "granularity", "in": "query", "description": "Candle bucket", "required": true, "schema": { "$ref": "#/components/schemas/GranularityDoc" } }, { "name": "from", "in": "query", "description": "Inclusive unix-second start", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "to", "in": "query", "description": "Exclusive unix-second end", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "orientation", "in": "query", "description": "`raw` (default) keeps stored token1-per-token0 prices; `display` inverts candles when the pool's canonical display orientation is flipped", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OHLCV candles for the range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OhlcvResponseDoc" } } } }, "400": { "description": "Invalid granularity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Get pool OHLCV", "x-mint": { "metadata": { "title": "Get pool OHLCV", "sidebarTitle": "Get pool OHLCV", "description": "Retrieve indexed open, high, low, close, and volume candles for a pool." } } } }, "/pools/{key}/stats": { "get": { "tags": [ "pools" ], "operationId": "get_pool_24h_stats", "parameters": [ { "name": "key", "in": "path", "description": "Pool key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rolling 24h price/volume summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolStats24hResponseDoc" } } } }, "404": { "description": "Pool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Get pool statistics", "x-mint": { "metadata": { "title": "Get pool statistics", "sidebarTitle": "Get pool statistics", "description": "Retrieve rolling 24-hour statistics for one pool." } } } }, "/pools/{key}/trades": { "get": { "tags": [ "pools" ], "operationId": "get_pool_trades", "parameters": [ { "name": "key", "in": "path", "description": "Pool key", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size (1-100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Page offset", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "trade_type", "in": "query", "description": "Indexed pool trade type filter", "required": false, "schema": { "$ref": "#/components/schemas/PoolTradeFilterDoc" } } ], "responses": { "200": { "description": "Paginated trade history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolTradesResponseDoc" } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "404": { "description": "Pool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "List pool trades", "x-mint": { "metadata": { "title": "List pool trades", "sidebarTitle": "List pool trades", "description": "List indexed trades for a pool." } } } }, "/positions": { "get": { "tags": [ "positions" ], "operationId": "list_positions", "parameters": [ { "name": "limit", "in": "query", "description": "Page size (1-100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Page offset", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Paginated LP positions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PositionListResponseDoc" } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "List positions", "x-mint": { "metadata": { "title": "List positions", "sidebarTitle": "List positions", "description": "List indexed liquidity positions available to the authenticated client." } } } }, "/positions/{token_id}": { "get": { "tags": [ "positions" ], "operationId": "get_position", "parameters": [ { "name": "token_id", "in": "path", "description": "On-chain position NFT token_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Position details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PositionResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "404": { "description": "Position not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Get a position", "x-mint": { "metadata": { "title": "Get a position", "sidebarTitle": "Get a position", "description": "Retrieve one indexed liquidity position by token ID." } } } }, "/protocol/state": { "get": { "tags": [ "protocol" ], "operationId": "get_protocol_state", "parameters": [ { "name": "minimum_revision", "in": "path", "required": true, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Canonical versioned protocol state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolStateResponse" } } } }, "304": { "description": "Protocol state matches If-None-Match" }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "503": { "description": "The requested protocol revision has not been indexed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolRevisionPending" } } } } }, "summary": "Get protocol state", "x-mint": { "metadata": { "title": "Get protocol state", "sidebarTitle": "Get protocol state", "description": "Get a revisioned snapshot of protocol controls and routing configuration." } } } }, "/referral/admin": { "get": { "tags": [ "referral" ], "operationId": "admin_check", "responses": { "200": { "description": "Wallet administrator status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralAdminResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "403": { "description": "Invite access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Get referral administration", "x-mint": { "metadata": { "title": "Get referral administration", "sidebarTitle": "Get referral administration", "description": "Get referral administration data for an authorized administrator." } } } }, "/referral/codes": { "get": { "tags": [ "referral" ], "operationId": "referral_list_codes", "parameters": [ { "name": "limit", "in": "query", "description": "Page size (1-2000)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Page offset", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Referral-code inventory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralListResponseDoc" } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "403": { "description": "Administrator authorization required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "List referral codes", "x-mint": { "metadata": { "title": "List referral codes", "sidebarTitle": "List referral codes", "description": "List referral codes for an authorized administrator." } } } }, "/referral/generate": { "post": { "tags": [ "referral" ], "operationId": "referral_generate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralGenerateRequest" } } }, "required": true }, "responses": { "200": { "description": "Generated referral codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralGenerateResponseDoc" } } } }, "400": { "description": "Malformed JSON request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "403": { "description": "Administrator authorization required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "422": { "description": "Request body does not match schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Generate referral codes", "x-mint": { "metadata": { "title": "Generate referral codes", "sidebarTitle": "Generate referral codes", "description": "Generate referral codes for an authorized administrator." } } } }, "/referral/my-codes": { "get": { "tags": [ "referral" ], "operationId": "my_codes", "responses": { "200": { "description": "Codes issued to the wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralMyCodesResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "403": { "description": "Invite access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "List my referral codes", "x-mint": { "metadata": { "title": "List my referral codes", "sidebarTitle": "List my referral codes", "description": "List referral codes owned by the authenticated wallet." } } } }, "/referral/redeem": { "post": { "tags": [ "referral" ], "operationId": "referral_redeem", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralRedeemRequest" } } }, "required": true }, "responses": { "200": { "description": "Referral code redeemed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralRedeemResponseDoc" } } } }, "400": { "description": "Invalid, used, or capacity-limited code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "422": { "description": "Request body does not match schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Redeem a referral code", "x-mint": { "metadata": { "title": "Redeem a referral code", "sidebarTitle": "Redeem a referral code", "description": "Redeem a referral code for the authenticated wallet." } } } }, "/referral/settings": { "get": { "tags": [ "referral" ], "operationId": "get_settings", "responses": { "200": { "description": "Referral settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralSettingsResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "403": { "description": "Administrator authorization required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Get referral settings", "x-mint": { "metadata": { "title": "Get referral settings", "sidebarTitle": "Get referral settings", "description": "Get the current referral program settings." } } }, "put": { "tags": [ "referral" ], "operationId": "update_settings", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralUpdateSettingsRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated referral settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralSettingsResponseDoc" } } } }, "400": { "description": "Malformed JSON request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "403": { "description": "Administrator authorization required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "422": { "description": "Request body does not match schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Update referral settings", "x-mint": { "metadata": { "title": "Update referral settings", "sidebarTitle": "Update referral settings", "description": "Update referral program settings with administrator authorization." } } } }, "/referral/status": { "get": { "tags": [ "referral" ], "operationId": "referral_status", "responses": { "200": { "description": "Wallet referral status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralStatusResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Get referral status", "x-mint": { "metadata": { "title": "Get referral status", "sidebarTitle": "Get referral status", "description": "Get referral and reward status for the authenticated wallet." } } } }, "/route": { "get": { "tags": [ "route" ], "operationId": "find_route", "parameters": [ { "name": "token_in", "in": "query", "description": "Input token ID", "required": true, "schema": { "type": "string" } }, { "name": "token_out", "in": "query", "description": "Output token ID", "required": true, "schema": { "type": "string" } }, { "name": "amount_in", "in": "query", "description": "Optional positive canonical decimal amount for output estimation", "required": false, "schema": { "type": "string" } }, { "name": "pool_key", "in": "query", "description": "Optional pool key. The route uses only this pool, as a single hop, with no fallback.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Best swap route (max 3 hops)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteResponseDoc" } } } }, "400": { "description": "Invalid amount_in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "404": { "description": "No route or executable quote for the given tokens", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "503": { "description": "The live deployment is incompatible, routing dependencies are unavailable, or the quote candidate set exceeds the safe limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Find a route", "x-mint": { "metadata": { "title": "Find a route", "sidebarTitle": "Find a route", "description": "Find an indexed Shield Swap route between two tokens." } } } }, "/route/topology": { "get": { "tags": [ "route" ], "operationId": "route_topology", "responses": { "200": { "description": "All routable pool edges", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteTopologyResponseDoc" } } } }, "503": { "description": "The live deployment is incompatible or routing dependencies are unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Get route topology", "x-mint": { "metadata": { "title": "Get route topology", "sidebarTitle": "Get route topology", "description": "Get the current token and pool graph used for route discovery." } } } }, "/schema/trading": { "get": { "tags": [ "schema" ], "summary": "List transaction schemas", "description": "Returns the full list of on-chain trading, liquidity, and token operations\nwith their input signatures. Clients can use this to build transaction\npayloads without hardcoding the Leo function signatures.", "operationId": "list_trading_schemas", "responses": { "200": { "description": "List of all on-chain operation schemas", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TradingSchemaListResponse" } } } } }, "security": [ { "bearer_auth": [] } ], "x-mint": { "metadata": { "title": "List transaction schemas", "sidebarTitle": "List transaction schemas", "description": "List the supported trading, liquidity, and token operations with their input signatures." } } } }, "/schema/trading/{id}": { "get": { "tags": [ "schema" ], "summary": "Get a transaction schema", "description": "Returns the input schema for a single operation (e.g. `swap`, `mint`, `collect`).", "operationId": "get_trading_schema", "parameters": [ { "name": "id", "in": "path", "description": "Operation ID (swap, mint, create_pool, burn, collect, decrease_liquidity, swap_multi_hop, claim_swap_output, register_token, mint_public, mint_private, transfer_public_to_private, add_fee_tier, add_tick_spacing, bind_fee_to_tick_spacing, set_pool_enabled)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Schema for the requested operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TradingSchemaResponse" } } } }, "404": { "description": "Unknown operation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "x-mint": { "metadata": { "title": "Get a transaction schema", "sidebarTitle": "Get a transaction schema", "description": "Retrieve the current input schema for one transaction operation." } } } }, "/swaps": { "get": { "tags": [ "swaps" ], "operationId": "list_swaps", "parameters": [ { "name": "limit", "in": "query", "description": "Page size (1-100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Page offset", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "pool", "in": "query", "description": "Filter by any pool in the route", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated swap history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapListResponseDoc" } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "404": { "description": "Pool filter not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "List swaps", "x-mint": { "metadata": { "title": "List swaps", "sidebarTitle": "List swaps", "description": "List indexed swaps available to the authenticated client." } } } }, "/swaps/{swap_id}": { "get": { "tags": [ "swaps" ], "operationId": "get_swap", "parameters": [ { "name": "swap_id", "in": "path", "description": "On-chain swap ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Swap details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "404": { "description": "Swap not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Get a swap", "x-mint": { "metadata": { "title": "Get a swap", "sidebarTitle": "Get a swap", "description": "Retrieve one indexed swap by swap ID." } } } }, "/tick-spacings": { "get": { "tags": [ "protocol" ], "operationId": "list_tick_spacings", "responses": { "200": { "description": "Registered tick spacings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TickSpacingListResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "List tick spacings", "x-mint": { "metadata": { "title": "List tick spacings", "sidebarTitle": "List tick spacings", "description": "List the tick spacings registered for the configured deployment." } } } }, "/tokens": { "get": { "tags": [ "tokens" ], "operationId": "list_tokens", "responses": { "200": { "description": "All registered tokens", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenListResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "summary": "List tokens", "x-mint": { "metadata": { "title": "List tokens", "sidebarTitle": "List tokens", "description": "List registered Shield Swap tokens and wrapper metadata." } } }, "post": { "tags": [ "tokens" ], "operationId": "create_token", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTokenRequestDoc" } } }, "required": true }, "responses": { "200": { "description": "Token stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponseDoc" } } } }, "400": { "description": "Invalid token decimals or request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "401": { "description": "Administrator authorization required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "403": { "description": "Administrator authorization required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "422": { "description": "Request body does not match schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "summary": "Register token metadata", "x-mint": { "metadata": { "title": "Register token metadata", "sidebarTitle": "Register token metadata", "description": "Register token metadata and an optional wrapper program with the API." } } } }, "/tokens/deploy": { "post": { "tags": [ "tokens" ], "summary": "Deploy a token", "description": "Deploys a fresh self-contained ARC-20 token (the treasury/deployer key is its\nbaked-in admin) and mints the initial supply to the creator (`recipient`),\nthen registers it (with `amm_token_program`) so it is swap- and airdrop-ready.\n\nDeploy + mint are two on-chain txs that take minutes, so this returns\nimmediately with `status: \"deploying\"` and finishes in the background. Poll\n`GET /tokens` for a row whose `amm_token_program` equals the returned\n`program_id` to know it completed.\n\nRequired env: `DEPLOYER_PRIVATE_KEY` (treasury/admin; `AIRDROP_PRIVATE_KEY`\nhonored as fallback), `RPC_URLS`. `leo` must be on the server PATH.", "operationId": "deploy_token", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeployTokenRequest" } } }, "required": true }, "responses": { "200": { "description": "Deploy started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeployTokenResponseDoc" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "403": { "description": "Administrator authorization required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "422": { "description": "Request body does not match schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Misconfigured server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "x-mint": { "metadata": { "title": "Deploy a token", "sidebarTitle": "Deploy a token", "description": "Start deployment and initial minting for a new ARC-20 wrapper token." } } } }, "/tokens/mint": { "post": { "tags": [ "tokens" ], "summary": "Mint a token", "description": "Admin-mints `amount` (base units) of an existing AMM token to `recipient`.", "operationId": "mint_token", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MintTokenRequest" } } }, "required": true }, "responses": { "200": { "description": "Mint broadcast", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MintTokenResponseDoc" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "403": { "description": "Administrator authorization required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "422": { "description": "Request body does not match schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Misconfigured server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "x-mint": { "metadata": { "title": "Mint a token", "sidebarTitle": "Mint a token", "description": "Admin-mint an existing wrapper token to a recipient." } } } }, "/tokens/{address}": { "get": { "tags": [ "tokens" ], "operationId": "get_token", "parameters": [ { "name": "address", "in": "path", "description": "Token address (Aleo field ID)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Token details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponseDoc" } } } }, "404": { "description": "Token not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "summary": "Get a token", "x-mint": { "metadata": { "title": "Get a token", "sidebarTitle": "Get a token", "description": "Retrieve one registered token by its Aleo field address." } } } }, "/unclaimed": { "get": { "tags": [ "unclaimed" ], "summary": "List unclaimed outputs", "description": "Returns everything the user can still claim:\n - Swaps with `claimed_at IS NULL` (user can drive `claim_swap_output`).\n - Positions with `tokens_owed0 > 0` or `tokens_owed1 > 0`\n (post-`decrease_liquidity` accumulations; user calls `collect`).\n\nThe indexer is the source of truth: it stamps `claimed_at` for every claim\nvariant, and the `swaps` row already carries every field the claim tx needs.\nSo we do zero on-chain mapping reads here: that earlier per-swap RPC loop\nwas both slow (N sequential reads) and wrong (reads went through a balancer\nhitting nodes at different heights, so freshly-claimed swaps flapped back).", "operationId": "get_unclaimed", "responses": { "200": { "description": "Pending swap and liquidity claims", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnclaimedResponseDoc" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDoc" } } } } }, "security": [ { "bearer_auth": [] } ], "x-mint": { "metadata": { "title": "List unclaimed outputs", "sidebarTitle": "List unclaimed outputs", "description": "List swap outputs and position proceeds the authenticated wallet can still claim." } } } } }, "components": { "schemas": { "AccessCodeRow": { "type": "object", "required": [ "code", "created_at" ], "properties": { "code": { "type": "string" }, "created_at": { "type": "string" }, "redeemed_at": { "type": [ "string", "null" ] }, "redeemed_by": { "type": [ "string", "null" ] } } }, "AccessGenerateRequest": { "type": "object", "required": [ "count" ], "properties": { "count": { "type": "integer", "format": "int32", "minimum": 0 } } }, "AccessGenerateResponse": { "type": "object", "required": [ "codes" ], "properties": { "codes": { "type": "array", "items": { "type": "string" } } } }, "AccessGenerateResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AccessGenerateResponse" } } }, "AccessListResponse": { "type": "object", "required": [ "total", "redeemed", "available", "codes" ], "properties": { "available": { "type": "integer", "format": "int64" }, "codes": { "type": "array", "items": { "$ref": "#/components/schemas/AccessCodeRow" } }, "redeemed": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } } }, "AccessListResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AccessListResponse" } } }, "AccessRedeemRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } }, "AccessRedeemResponse": { "type": "object", "required": [ "code", "status" ], "properties": { "code": { "type": "string" }, "status": { "type": "string" } } }, "AccessRedeemResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AccessRedeemResponse" } } }, "AccessStatusResponse": { "type": "object", "required": [ "has_access" ], "properties": { "has_access": { "type": "boolean" } } }, "AccessStatusResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AccessStatusResponse" } } }, "ActiveSessionPayload": { "type": "object", "required": [ "session_id", "started_at", "last_refreshed_at", "expires_at", "current" ], "properties": { "current": { "type": "boolean" }, "expires_at": { "type": "integer", "format": "int64" }, "last_refreshed_at": { "type": "integer", "format": "int64" }, "session_id": { "type": "string", "format": "uuid" }, "started_at": { "type": "integer", "format": "int64" }, "user_agent": { "type": [ "string", "null" ] } } }, "ActiveSessionsResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActiveSessionPayload" } } } }, "AirdropJob": { "type": "object", "description": "Status of a background airdrop job. `status` is `\"running\"` until every token\nhas resolved, then `\"complete\"`. `results` grows as each per-token transfer\nlands, so a poller sees live progress (`results.len()` of `total`).", "required": [ "status", "total", "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/AirdropResult" } }, "status": { "type": "string" }, "total": { "type": "integer", "minimum": 0 } } }, "AirdropJobResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AirdropJob" } } }, "AirdropRequest": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string", "description": "Aleo address (`aleo1...`) to receive the airdrop." } } }, "AirdropResult": { "type": "object", "required": [ "symbol", "amm_token_program", "amount", "status" ], "properties": { "amm_token_program": { "type": "string" }, "amount": { "type": "string", "description": "Base-unit amount delivered." }, "error": { "type": [ "string", "null" ] }, "status": { "type": "string", "description": "`\"accepted\"` | `\"rejected\"` (broadcast but aborted at finalize, e.g.\ninsufficient treasury balance) | `\"pending\"` (broadcast, not yet\nconfirmed) | `\"failed\"` (never broadcast: see `error`)." }, "symbol": { "type": "string" }, "tx_id": { "type": [ "string", "null" ] } } }, "AirdropStartResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AirdropStartResult" } } }, "AirdropStartResult": { "type": "object", "description": "Returned by `POST /airdrop`: the airdrop now runs in the background, so the\ncaller gets a `job_id` to poll `GET /airdrop/{job_id}` with.", "required": [ "job_id", "status" ], "properties": { "job_id": { "type": "string" }, "status": { "type": "string" } } }, "ApiTokenCreateRequest": { "type": "object", "required": [ "name" ], "properties": { "expires_in_days": { "type": [ "integer", "null" ], "format": "int64" }, "name": { "type": "string" } } }, "ApiTokenCreatedResponse": { "type": "object", "required": [ "id", "name", "token", "token_prefix", "created_at" ], "properties": { "created_at": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "token": { "type": "string", "description": "Full secret, returned only once at creation." }, "token_prefix": { "type": "string" } } }, "ApiTokenCreatedResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApiTokenCreatedResponse" } } }, "ApiTokenListResponse": { "type": "object", "required": [ "tokens" ], "properties": { "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/ApiTokenRow" } } } }, "ApiTokenListResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApiTokenListResponse" } } }, "ApiTokenRevokeResponse": { "type": "object", "required": [ "id", "revoked" ], "properties": { "id": { "type": "string", "format": "uuid" }, "revoked": { "type": "boolean" } } }, "ApiTokenRevokeResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApiTokenRevokeResponse" } } }, "ApiTokenRow": { "type": "object", "required": [ "id", "name", "token_prefix", "created_at" ], "properties": { "created_at": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "last_used_at": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "revoked_at": { "type": [ "string", "null" ] }, "token_prefix": { "type": "string" } } }, "AuthTokenPayload": { "type": "object", "required": [ "token", "expires_at" ], "properties": { "expires_at": { "type": "integer", "format": "int64" }, "token": { "type": "string" } } }, "AuthTokenResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AuthTokenPayload" } } }, "BalanceListResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TokenBalanceDoc" } } } }, "ChallengePayload": { "type": "object", "required": [ "challenge_id", "nonce", "message" ], "properties": { "challenge_id": { "type": "string" }, "message": { "type": "string" }, "nonce": { "type": "string" } } }, "ChallengeRequestDoc": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" } } }, "ChallengeResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ChallengePayload" } } }, "CreateTokenRequestDoc": { "type": "object", "required": [ "address", "name", "symbol", "decimals" ], "properties": { "address": { "type": "string", "description": "Aleo field ID (e.g. `1234567890field`)." }, "amm_token_program": { "type": [ "string", "null" ], "description": "Program for the token representation used by the AMM; the wrapper program for wrapped assets." }, "decimals": { "type": "integer", "format": "int32", "maximum": 18, "minimum": 0 }, "name": { "type": "string" }, "symbol": { "type": "string" } } }, "DeployTokenRequest": { "type": "object", "required": [ "name", "symbol", "decimals", "recipient" ], "properties": { "decimals": { "type": "integer", "format": "int32", "maximum": 18, "minimum": 0 }, "name": { "type": "string" }, "recipient": { "type": "string", "description": "Aleo address (`aleo1...`) of the creator: receives the initial supply." }, "supply": { "type": [ "string", "null" ], "description": "Initial supply in whole units (default 1_000_000), minted to `recipient`." }, "symbol": { "type": "string" } } }, "DeployTokenResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeployTokenResult" } } }, "DeployTokenResult": { "type": "object", "required": [ "program_id", "status", "recipient" ], "properties": { "program_id": { "type": "string", "description": "`_.aleo`: the deployed AMM token program id." }, "recipient": { "type": "string" }, "status": { "type": "string", "description": "Always `\"deploying\"`. Deploy + initial mint run in the background\n(minutes); poll `GET /tokens` until a token with this `amm_token_program`\nappears to know it finished and was registered." } } }, "ErrorResponseDoc": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "ref": { "type": [ "string", "null" ] } } }, "FeeBinding": { "type": "object", "required": [ "fee_tier", "tick_spacing" ], "properties": { "fee_tier": { "type": "integer", "format": "int32" }, "tick_spacing": { "type": "integer", "format": "int32" } } }, "FeeTierDoc": { "type": "object", "required": [ "id", "fee_tier", "created_at", "transaction" ], "properties": { "created_at": { "type": "string" }, "fee_tier": { "type": "integer", "format": "int32", "description": "Raw hundredths of a basis point; the fee fraction is this value divided by 1,000,000.", "maximum": 65535, "minimum": 0 }, "id": { "type": "string" }, "tick_spacing": { "type": [ "integer", "null" ], "format": "int32", "description": "Current binding, or null when the registered fee has not been bound." }, "transaction": { "type": "string" } } }, "FeeTierListResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeeTierDoc" } } } }, "FunctionSchema": { "type": "object", "description": "Full schema for one Shield transaction.", "required": [ "id", "program", "function", "visibility", "description", "inputs" ], "properties": { "description": { "type": "string", "description": "One-line human summary." }, "follow_up": { "type": "array", "items": { "type": "string" }, "description": "Optional follow-up transactions that must be executed after this one." }, "function": { "type": "string", "description": "Function name on-chain." }, "id": { "type": "string", "description": "Short identifier (`swap`, `mint`, `create_pool`, ...)." }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/SchemaField" }, "description": "Ordered list of inputs: index in this array == positional argument index." }, "program": { "type": "string", "description": "Aleo program ID the function lives on (e.g. `shield_swap.aleo`, `token_registry.aleo`)." }, "visibility": { "type": "string", "description": "`public` (clear inputs) or `private` (hidden inputs using records)." } } }, "GlobalConfigResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/GlobalConfigStatus" } } }, "GlobalConfigStatus": { "type": "object", "required": [ "global_paused", "pool_creation_is_open" ], "properties": { "global_paused": { "type": "boolean" }, "pool_creation_is_open": { "type": "boolean" } } }, "GranularityDoc": { "type": "string", "enum": [ "1m", "5m", "15m", "30m", "1h", "6h", "12h", "1d" ] }, "InitializedTicksResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "integer", "format": "int32" } } } }, "LiquidityDistributionResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TickLiquidityDoc" } } } }, "LiveCompatibility": { "type": "object", "required": [ "status", "checked_at", "artifacts_checked", "failures" ], "properties": { "artifacts_checked": { "type": "integer", "minimum": 0 }, "checked_at": { "type": "string", "format": "date-time" }, "failures": { "type": "array", "items": { "$ref": "#/components/schemas/LiveCompatibilityFailure" } }, "status": { "$ref": "#/components/schemas/LiveCompatibilityStatus" } } }, "LiveCompatibilityFailure": { "type": "object", "required": [ "code" ], "properties": { "code": { "$ref": "#/components/schemas/LiveCompatibilityFailureCode" }, "program_id": { "type": [ "string", "null" ] } } }, "LiveCompatibilityFailureCode": { "type": "string", "enum": [ "cache_unavailable", "edition_mismatch", "edition_unavailable", "rate_limited", "rpc_unavailable", "source_mismatch", "source_unavailable", "verification_timeout" ] }, "LiveCompatibilityStatus": { "type": "string", "enum": [ "compatible", "incompatible", "unavailable" ] }, "LogoutAllResponse": { "type": "object", "required": [ "ok", "ended", "address", "session_version" ], "properties": { "address": { "type": "string" }, "ended": { "type": "boolean" }, "ok": { "type": "boolean" }, "session_version": { "type": "integer", "format": "int64" } } }, "LogoutAllResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LogoutAllResponse" } } }, "LogoutResponse": { "type": "object", "required": [ "ok", "ended" ], "properties": { "ended": { "type": "boolean" }, "ok": { "type": "boolean" }, "session_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "LogoutResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LogoutResponse" } } }, "MintTokenRequest": { "type": "object", "required": [ "amm_token_program", "recipient", "amount" ], "properties": { "amm_token_program": { "type": "string", "description": "Program for the token representation used by the AMM." }, "amount": { "type": "string", "description": "Amount in BASE units (already scaled by 10^decimals), as a string." }, "recipient": { "type": "string", "description": "Recipient Aleo address (`aleo1...`)." } } }, "MintTokenResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MintTokenResult" } } }, "MintTokenResult": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" }, "tx_id": { "type": [ "string", "null" ] } } }, "OhlcvDoc": { "type": "object", "required": [ "o", "h", "l", "c", "v", "timestamp", "granularity", "pool" ], "properties": { "c": { "type": "string", "description": "Last raw atomic token1-per-token0 execution price." }, "granularity": { "$ref": "#/components/schemas/GranularityDoc" }, "h": { "type": "string", "description": "Highest raw atomic token1-per-token0 execution price." }, "l": { "type": "string", "description": "Lowest raw atomic token1-per-token0 execution price." }, "o": { "type": "string", "description": "First raw atomic token1-per-token0 execution price." }, "pool": { "type": "string" }, "timestamp": { "type": "integer", "format": "int64" }, "v": { "type": "string", "description": "Raw token0 units consumed." } } }, "OhlcvResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OhlcvDoc" } } } }, "PaginationMeta": { "type": "object", "required": [ "total", "limit", "offset" ], "properties": { "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } } }, "PairComplianceResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PairComplianceStatus" } } }, "PairComplianceStatus": { "type": "object", "required": [ "token0", "token1", "paused" ], "properties": { "paused": { "type": "boolean" }, "token0": { "type": "string" }, "token1": { "type": "string" } } }, "PendingSwapDoc": { "type": "object", "required": [ "swap_id", "swap_tx_hash", "is_private", "is_multi_hop", "output" ], "properties": { "is_multi_hop": { "type": "boolean" }, "is_private": { "type": "boolean" }, "output": { "$ref": "#/components/schemas/PendingSwapOutputDoc" }, "swap_id": { "type": "string" }, "swap_tx_hash": { "type": "string" }, "token_in_info": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenDoc" } ] }, "token_out_info": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenDoc" } ] } } }, "PendingSwapOutputDoc": { "type": "object", "required": [ "recipient", "token_in", "token_out", "amount_out", "amount_remaining" ], "properties": { "amount_out": { "type": "string" }, "amount_remaining": { "type": "string" }, "recipient": { "type": "string" }, "token_in": { "type": "string" }, "token_out": { "type": "string" } } }, "PoolDebugInfoDoc": { "type": "object", "required": [ "pool_key", "tick_statuses" ], "properties": { "active_tick": { "type": [ "integer", "null" ], "format": "int32" }, "liquidity": { "type": [ "string", "null" ] }, "pool_key": { "type": "string" }, "slot_raw": { "type": [ "string", "null" ] }, "sqrt_price": { "type": [ "string", "null" ] }, "tick_spacing": { "type": [ "string", "null" ] }, "tick_statuses": { "type": "array", "items": { "$ref": "#/components/schemas/TickStatusDoc" } } } }, "PoolDebugResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PoolDebugInfoDoc" } } }, "PoolFeeProtocol": { "type": "object", "required": [ "pool_key", "fee_protocol" ], "properties": { "fee_protocol": { "type": "integer", "format": "int32" }, "pool_key": { "type": "string" } } }, "PoolListResponseDoc": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PoolResponseDoc" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "valuation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UsdcUsdQuote" } ] } } }, "PoolResponseDoc": { "allOf": [ { "$ref": "#/components/schemas/PoolStateDoc" }, { "type": "object", "required": [ "display_flipped" ], "properties": { "base_token": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenDoc", "description": "token0_info/token1_info reordered so the quote (denominator) token is\nalways `quote_token` (priority: USD stables > ETH > BTC > ALEO)." } ] }, "display_flipped": { "type": "boolean", "description": "True when the canonical display orientation is (token1, token0)." }, "quote_token": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenDoc" } ] }, "token0_info": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenDoc" } ] }, "token1_info": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenDoc" } ] } } } ] }, "PoolStateDoc": { "type": "object", "required": [ "id", "key", "token0", "token1", "enabled", "creator", "fee_percent", "created_at", "init_tx" ], "properties": { "created_at": { "type": "string" }, "creator": { "type": "string" }, "enabled": { "type": "boolean" }, "fee_percent": { "type": "string" }, "id": { "type": "string" }, "init_tx": { "type": "string" }, "key": { "type": "string" }, "token0": { "type": "string" }, "token1": { "type": "string" } } }, "PoolStats24hBatchResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PoolStats24hDoc" }, "propertyNames": { "type": "string" } } } }, "PoolStats24hDoc": { "type": "object", "required": [ "price", "price_reversed", "liquidity", "reserve0", "reserve1", "open_24h", "high_24h", "low_24h", "volume_24h", "display_flipped", "display_price", "display_open_24h", "display_high_24h", "display_low_24h" ], "properties": { "change_24h_pct": { "type": [ "string", "null" ] }, "display_change_24h_pct": { "type": [ "string", "null" ] }, "display_flipped": { "type": "boolean", "description": "True when display fields are inverted relative to token0/token1 order." }, "display_high_24h": { "type": "string", "description": "Inverted windows swap extremes: display_high = 1 / low_24h." }, "display_low_24h": { "type": "string" }, "display_open_24h": { "type": "string" }, "display_price": { "type": "string", "description": "Current price in canonical display orientation (quote per base)." }, "high_24h": { "type": "string", "description": "Highest raw atomic execution price." }, "liquidity": { "type": "string" }, "low_24h": { "type": "string", "description": "Lowest raw atomic execution price." }, "open_24h": { "type": "string", "description": "Earliest raw atomic execution price." }, "price": { "type": "string" }, "price_reversed": { "type": "string" }, "reserve0": { "type": "string" }, "reserve1": { "type": "string" }, "volume_24h": { "type": "string", "description": "Raw token0 units consumed." } } }, "PoolStats24hResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PoolStats24hDoc" } } }, "PoolStatsDoc": { "type": "object", "required": [ "id", "price", "price_reversed", "active_tick", "tick_spacing", "liquidity", "pool", "fee_protocol", "protocol_fees0", "protocol_fees1", "fee_growth_global0_x_128", "fee_growth_global1_x_128", "max_liquidity_per_tick", "next_init_below", "next_init_above" ], "properties": { "active_tick": { "type": "integer", "format": "int32" }, "fee_growth_global0_x_128": { "type": "string" }, "fee_growth_global1_x_128": { "type": "string" }, "fee_protocol": { "type": "integer", "format": "int32" }, "id": { "type": "string" }, "liquidity": { "type": "string" }, "max_liquidity_per_tick": { "type": "string" }, "next_init_above": { "type": "integer", "format": "int32" }, "next_init_below": { "type": "integer", "format": "int32" }, "pool": { "type": "string" }, "price": { "type": "string" }, "price_reversed": { "type": "string" }, "protocol_fees0": { "type": "string" }, "protocol_fees1": { "type": "string" }, "tick_spacing": { "type": "integer", "format": "int32" } } }, "PoolTradeDoc": { "type": "object", "required": [ "id", "tradeType", "amount0", "amount1", "executedAt", "transactionHash", "pool" ], "properties": { "amount0": { "type": "string" }, "amount1": { "type": "string" }, "executedAt": { "type": "string" }, "id": { "type": "string" }, "pool": { "type": "string" }, "tradeType": { "$ref": "#/components/schemas/PoolTradeTypeDoc" }, "transactionHash": { "type": "string" } } }, "PoolTradeFilterDoc": { "type": "string", "enum": [ "mint", "add_liquidity", "remove_liquidity", "burn", "collect", "swap" ] }, "PoolTradeTypeDoc": { "type": "string", "enum": [ "mint", "add_liquidity", "remove_liquidity", "burn", "collect", "swap", "swap_multi_hop" ] }, "PoolTradesResponseDoc": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PoolTradeDoc" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } }, "PoolWithStatsDoc": { "allOf": [ { "$ref": "#/components/schemas/PoolStateDoc" }, { "type": "object", "required": [ "reserve0", "reserve1", "display_flipped" ], "properties": { "base_token": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenDoc" } ] }, "display_flipped": { "type": "boolean", "description": "True when the canonical display orientation is (token1, token0)." }, "quote_token": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenDoc" } ] }, "reserve0": { "type": "string" }, "reserve1": { "type": "string" }, "stats": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PoolStatsDoc" } ] }, "token0_info": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenDoc" } ] }, "token1_info": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenDoc" } ] } } } ] }, "PoolWithStatsResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PoolWithStatsDoc" } } }, "PositionDoc": { "type": "object", "required": [ "id", "token_id", "tick_lower", "tick_upper", "liquidity", "amount0", "amount1", "user", "pool", "created_at", "created_transaction", "last_transaction", "is_burned", "fee_growth_inside0_last_x_128", "fee_growth_inside1_last_x_128", "tokens_owed0", "tokens_owed1", "is_private", "is_frozen" ], "properties": { "amount0": { "type": "string" }, "amount1": { "type": "string" }, "created_at": { "type": "string" }, "created_transaction": { "type": "string" }, "created_transaction_hash": { "type": [ "string", "null" ] }, "fee_growth_inside0_last_x_128": { "type": "string" }, "fee_growth_inside1_last_x_128": { "type": "string" }, "frozen_at": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "is_burned": { "type": "boolean" }, "is_frozen": { "type": "boolean" }, "is_private": { "type": "boolean" }, "last_transaction": { "type": "string" }, "last_transaction_hash": { "type": [ "string", "null" ] }, "liquidity": { "type": "string" }, "pool": { "type": "string" }, "tick_lower": { "type": "integer", "format": "int32" }, "tick_upper": { "type": "integer", "format": "int32" }, "token_id": { "type": "string" }, "tokens_owed0": { "type": "string" }, "tokens_owed1": { "type": "string" }, "user": { "type": "string" } } }, "PositionListResponseDoc": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PositionDoc" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } }, "PositionResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PositionDoc" } } }, "PositionWithOwedDoc": { "type": "object", "required": [ "token_id", "pool", "tick_lower", "tick_upper", "tokens_owed0", "tokens_owed1", "is_private", "is_frozen" ], "properties": { "frozen_at": { "type": [ "string", "null" ] }, "is_frozen": { "type": "boolean" }, "is_private": { "type": "boolean" }, "last_transaction_hash": { "type": [ "string", "null" ] }, "pool": { "type": "string" }, "tick_lower": { "type": "integer", "format": "int32" }, "tick_upper": { "type": "integer", "format": "int32" }, "token0_info": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenDoc" } ] }, "token1_info": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenDoc" } ] }, "token_id": { "type": "string" }, "tokens_owed0": { "type": "string" }, "tokens_owed1": { "type": "string" } } }, "ProtocolCapabilities": { "type": "object", "required": [ "faucet", "token_admin", "debug_api", "freezelist_proofs", "protocol_config_websocket" ], "properties": { "debug_api": { "type": "boolean" }, "faucet": { "type": "boolean" }, "freezelist_proofs": { "type": "string" }, "protocol_config_websocket": { "type": "boolean" }, "token_admin": { "type": "boolean" } } }, "ProtocolControls": { "type": "object", "required": [ "global_paused", "pool_creation_is_open", "allowed_tokens", "paused_tokens", "paused_pairs", "disabled_pools" ], "properties": { "allowed_tokens": { "type": "array", "items": { "type": "string" } }, "disabled_pools": { "type": "array", "items": { "type": "string" } }, "global_paused": { "type": "boolean" }, "paused_pairs": { "type": "array", "items": { "$ref": "#/components/schemas/ProtocolPair" } }, "paused_tokens": { "type": "array", "items": { "type": "string" } }, "pool_creation_is_open": { "type": "boolean" } } }, "ProtocolDeployment": { "type": "object", "required": [ "profile", "network", "verified_at", "amm_start_block", "contract_repository", "contract_ref", "protocol_version", "abi_version", "math_version", "freezelist_proof_version", "deployment_fingerprint", "programs" ], "properties": { "abi_version": { "type": "integer", "format": "int32", "minimum": 0 }, "amm_start_block": { "type": "integer", "format": "int64", "minimum": 0 }, "contract_ref": { "type": "string" }, "contract_repository": { "type": "string" }, "deployment_fingerprint": { "type": "string" }, "freezelist_proof_version": { "type": "string" }, "math_version": { "type": "string" }, "network": { "type": "string" }, "profile": { "type": "string" }, "programs": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ProtocolProgram" }, "propertyNames": { "type": "string" } }, "protocol_version": { "type": "integer", "format": "int32", "minimum": 0 }, "verified_at": { "type": "string" } } }, "ProtocolFeeConfiguration": { "type": "object", "required": [ "registered_fee_tiers", "registered_tick_spacings", "valid_bindings", "pool_fee_protocols" ], "properties": { "pool_fee_protocols": { "type": "array", "items": { "$ref": "#/components/schemas/PoolFeeProtocol" } }, "registered_fee_tiers": { "type": "array", "items": { "type": "integer", "format": "int32" } }, "registered_tick_spacings": { "type": "array", "items": { "type": "integer", "format": "int32" } }, "valid_bindings": { "type": "array", "items": { "$ref": "#/components/schemas/FeeBinding" } } } }, "ProtocolFreshness": { "type": "object", "required": [ "ready_for_entry" ], "properties": { "confirmed_head": { "type": [ "integer", "null" ], "format": "int64" }, "indexed_block": { "type": [ "integer", "null" ], "format": "int64" }, "lag_blocks": { "type": [ "integer", "null" ], "format": "int64" }, "ready_for_entry": { "type": "boolean" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ProtocolPair": { "type": "object", "required": [ "token0", "token1" ], "properties": { "token0": { "type": "string" }, "token1": { "type": "string" } } }, "ProtocolProgram": { "type": "object", "required": [ "program_id", "role", "source_sha256" ], "properties": { "edition": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "program_id": { "type": "string" }, "role": { "type": "string" }, "source_sha256": { "type": "string" } } }, "ProtocolRevisionPending": { "type": "object", "required": [ "error", "code", "minimum_revision", "current_revision" ], "properties": { "code": { "type": "string" }, "current_revision": { "type": "integer", "format": "int64" }, "error": { "type": "string" }, "minimum_revision": { "type": "integer", "format": "int64" } } }, "ProtocolStateResponse": { "type": "object", "required": [ "revision", "freshness", "live_compatibility", "deployment", "controls", "fee_configuration", "capabilities" ], "properties": { "capabilities": { "$ref": "#/components/schemas/ProtocolCapabilities" }, "changed_at": { "type": [ "string", "null" ], "format": "date-time" }, "controls": { "$ref": "#/components/schemas/ProtocolControls" }, "deployment": { "$ref": "#/components/schemas/ProtocolDeployment" }, "fee_configuration": { "$ref": "#/components/schemas/ProtocolFeeConfiguration" }, "freshness": { "$ref": "#/components/schemas/ProtocolFreshness" }, "live_compatibility": { "$ref": "#/components/schemas/LiveCompatibility" }, "observed_block": { "type": [ "integer", "null" ], "format": "int64" }, "revision": { "type": "integer", "format": "int64" } } }, "ReferralAdminCheckResponse": { "type": "object", "required": [ "is_admin" ], "properties": { "is_admin": { "type": "boolean" } } }, "ReferralAdminResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ReferralAdminCheckResponse" } } }, "ReferralCodeRow": { "type": "object", "required": [ "code", "created_at" ], "properties": { "code": { "type": "string" }, "created_at": { "type": "string" }, "issued_to": { "type": [ "string", "null" ] }, "redeemed_at": { "type": [ "string", "null" ] }, "redeemed_by": { "type": [ "string", "null" ] } } }, "ReferralGenerateRequest": { "type": "object", "required": [ "count" ], "properties": { "count": { "type": "integer", "format": "int32", "minimum": 0 } } }, "ReferralGenerateResponse": { "type": "object", "required": [ "codes" ], "properties": { "codes": { "type": "array", "items": { "type": "string" } } } }, "ReferralGenerateResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ReferralGenerateResponse" } } }, "ReferralListResponse": { "type": "object", "required": [ "total", "redeemed", "available", "codes" ], "properties": { "available": { "type": "integer", "format": "int64" }, "codes": { "type": "array", "items": { "$ref": "#/components/schemas/ReferralCodeRow" } }, "redeemed": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } } }, "ReferralListResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ReferralListResponse" } } }, "ReferralMyCodeRow": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "redeemed_at": { "type": [ "string", "null" ] }, "redeemed_by": { "type": [ "string", "null" ] } } }, "ReferralMyCodesResponse": { "type": "object", "required": [ "quota", "codes" ], "properties": { "codes": { "type": "array", "items": { "$ref": "#/components/schemas/ReferralMyCodeRow" } }, "quota": { "type": "integer", "format": "int32" } } }, "ReferralMyCodesResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ReferralMyCodesResponse" } } }, "ReferralRedeemRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } }, "ReferralRedeemResponse": { "type": "object", "required": [ "code", "status" ], "properties": { "code": { "type": "string" }, "status": { "type": "string" } } }, "ReferralRedeemResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ReferralRedeemResponse" } } }, "ReferralSettingsResponse": { "type": "object", "required": [ "codes_per_user", "codes_per_user_limit" ], "properties": { "codes_per_user": { "type": "integer", "format": "int32" }, "codes_per_user_limit": { "type": "integer", "format": "int32" }, "max_users": { "type": [ "integer", "null" ], "format": "int32" } } }, "ReferralSettingsResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ReferralSettingsResponse" } } }, "ReferralStatusResponse": { "type": "object", "required": [ "has_access" ], "properties": { "code": { "type": [ "string", "null" ] }, "has_access": { "type": "boolean" } } }, "ReferralStatusResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ReferralStatusResponse" } } }, "ReferralUpdateSettingsRequest": { "type": "object", "required": [ "codes_per_user" ], "properties": { "codes_per_user": { "type": "integer", "format": "int32" }, "max_users": { "type": [ "integer", "null" ], "format": "int32" } } }, "RevokeSessionPayload": { "type": "object", "required": [ "ok", "revoked", "current" ], "properties": { "current": { "type": "boolean" }, "ok": { "type": "boolean" }, "revoked": { "type": "boolean" } } }, "RevokeSessionResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RevokeSessionPayload" } } }, "RevokeSessionsRequest": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" } } }, "RevokeSessionsResponse": { "type": "object", "required": [ "session_version", "refresh_tokens_revoked" ], "properties": { "refresh_tokens_revoked": { "type": "integer", "format": "int64", "minimum": 0 }, "session_version": { "type": "integer", "format": "int64" } } }, "RevokeSessionsResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RevokeSessionsResponse" } } }, "RouteHopDoc": { "type": "object", "required": [ "pool_key", "token_in", "token_out", "zero_for_one", "fee", "initialized_ticks" ], "properties": { "active_tick": { "type": [ "integer", "null" ], "format": "int32" }, "fee": { "type": "string" }, "initialized_ticks": { "type": "array", "items": { "type": "integer", "format": "int32" } }, "liquidity": { "type": [ "string", "null" ] }, "pool_key": { "type": "string" }, "price": { "type": [ "string", "null" ] }, "sqrt_price_raw": { "type": [ "string", "null" ] }, "tick_spacing": { "type": [ "integer", "null" ], "format": "int32" }, "token_in": { "type": "string" }, "token_out": { "type": "string" }, "zero_for_one": { "type": "boolean" } } }, "RouteResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RouteResultDoc" } } }, "RouteResultDoc": { "type": "object", "required": [ "hops", "token_in", "token_out", "protocol_revision" ], "properties": { "estimated_amount_out": { "type": [ "string", "null" ] }, "hops": { "type": "array", "items": { "$ref": "#/components/schemas/RouteHopDoc" } }, "protocol_config_observed_block": { "type": [ "integer", "null" ], "format": "int64" }, "protocol_revision": { "type": "integer", "format": "int64" }, "token_in": { "type": "string" }, "token_out": { "type": "string" } } }, "RouteTopologyDoc": { "type": "object", "required": [ "edges", "max_hops", "protocol_revision" ], "properties": { "edges": { "type": "array", "items": { "$ref": "#/components/schemas/TopologyEdgeDoc" } }, "max_hops": { "type": "integer", "minimum": 0 }, "protocol_config_observed_block": { "type": [ "integer", "null" ], "format": "int64" }, "protocol_revision": { "type": "integer", "format": "int64" } } }, "RouteTopologyResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RouteTopologyDoc" } } }, "SchemaField": { "type": "object", "description": "Describes a single input field of an on-chain function or struct.", "required": [ "name", "type", "visibility", "description" ], "properties": { "description": { "type": "string", "description": "Human-readable explanation of the field." }, "fields": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/SchemaField" }, "description": "For struct-typed inputs, the nested field list." }, "name": { "type": "string", "description": "Parameter/field name as used in the Leo/Aleo program." }, "type": { "type": "string", "description": "Aleo type: `field`, `u128`, `u64`, `u32`, `u16`, `u8`, `i128`, `i32`, `bool`, `address`,\na struct name (e.g. `SwapRequest`), or `record` for Aleo records." }, "visibility": { "type": "string", "description": "`public` or `private`: controls whether the value is revealed on-chain." } } }, "SessionPayload": { "type": "object", "description": "Session identity returned on verify/refresh/session. The access + refresh\ntokens are set as httpOnly cookies (not in the body); `csrf_token` is held in\nmemory by the SPA and echoed in the `X-CSRF-Token` header.", "required": [ "address", "expires_at", "csrf_token", "session_version" ], "properties": { "address": { "type": "string" }, "csrf_token": { "type": "string" }, "expires_at": { "type": "integer", "format": "int64" }, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "session_version": { "type": "integer", "format": "int64" } } }, "SessionResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SessionPayload" } } }, "SwapDoc": { "type": "object", "required": [ "id", "swap_id", "hops", "pool", "input_amount", "output_amount", "input_token", "output_token", "user", "nonce", "recipient", "executed_at", "amount_remaining", "transaction", "is_private" ], "properties": { "amount_remaining": { "type": "string" }, "claim_tx": { "type": [ "string", "null" ] }, "claimed_at": { "type": [ "string", "null" ] }, "executed_at": { "type": "string" }, "hops": { "type": "array", "items": { "$ref": "#/components/schemas/SwapHopDoc" }, "description": "Full ordered route for single-hop and multi-hop swaps." }, "id": { "type": "string" }, "input_amount": { "type": "string" }, "input_token": { "type": "string" }, "input_token_info": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenDoc" } ] }, "is_private": { "type": "boolean" }, "nonce": { "type": "string" }, "output_amount": { "type": "string" }, "output_token": { "type": "string" }, "output_token_info": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenDoc" } ] }, "pool": { "type": "string", "description": "First-hop pool retained for compatibility; use `hops` for the full route." }, "recipient": { "type": "string" }, "swap_id": { "type": "string" }, "trade": { "type": [ "string", "null" ], "description": "Pool analytics trade; absent when a route lacks authoritative per-hop amounts." }, "transaction": { "type": "string" }, "user": { "type": "string" } } }, "SwapHopDoc": { "type": "object", "required": [ "pool", "zero_for_one" ], "properties": { "pool": { "type": "string" }, "zero_for_one": { "type": "boolean" } } }, "SwapListResponseDoc": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SwapDoc" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } }, "SwapResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SwapDoc" } } }, "TickLiquidityDoc": { "type": "object", "required": [ "tick", "liquidity_net" ], "properties": { "liquidity_net": { "type": "string" }, "tick": { "type": "integer", "format": "int32" } } }, "TickSpacingDoc": { "type": "object", "required": [ "id", "tick_spacing" ], "properties": { "id": { "type": "string" }, "tick_spacing": { "type": "integer", "format": "int32" } } }, "TickSpacingListResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TickSpacingDoc" } } } }, "TickStatusDoc": { "type": "object", "required": [ "tick", "tick_mapping_key", "exists" ], "properties": { "exists": { "type": "boolean" }, "raw_value": { "type": [ "string", "null" ] }, "tick": { "type": "integer", "format": "int32" }, "tick_mapping_key": { "type": "string" } } }, "TokenBalanceDoc": { "type": "object", "required": [ "token_id", "token_address", "symbol", "name", "decimals", "balance" ], "properties": { "balance": { "type": "string", "description": "Base-unit balance (no decimals applied)." }, "decimals": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "token_address": { "type": "string" }, "token_id": { "type": "string" } } }, "TokenComplianceResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TokenComplianceStatus" } } }, "TokenComplianceStatus": { "type": "object", "required": [ "token_id", "allowed", "paused" ], "properties": { "allowed": { "type": "boolean" }, "paused": { "type": "boolean" }, "token_id": { "type": "string" } } }, "TokenDoc": { "type": "object", "required": [ "id", "address", "name", "symbol", "decimals" ], "properties": { "address": { "type": "string" }, "amm_token_program": { "type": [ "string", "null" ], "description": "Program for the token representation used by the AMM; the wrapper program for wrapped assets." }, "decimals": { "type": "integer", "format": "int32" }, "id": { "type": "string" }, "image": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "symbol": { "type": "string" }, "underlying_program": { "type": [ "string", "null" ] }, "underlying_token_id": { "type": [ "string", "null" ] } } }, "TokenListResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TokenDoc" } } } }, "TokenResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TokenDoc" } } }, "TopologyEdgeDoc": { "type": "object", "required": [ "token0", "token1" ], "properties": { "token0": { "type": "string" }, "token1": { "type": "string" } } }, "TradingSchemaListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FunctionSchema" } } } }, "TradingSchemaResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/FunctionSchema" } } }, "UnclaimedPayloadDoc": { "type": "object", "required": [ "pending_swaps", "positions_with_owed" ], "properties": { "pending_swaps": { "type": "array", "items": { "$ref": "#/components/schemas/PendingSwapDoc" } }, "positions_with_owed": { "type": "array", "items": { "$ref": "#/components/schemas/PositionWithOwedDoc" } } } }, "UnclaimedResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UnclaimedPayloadDoc" } } }, "UsdcUsdQuote": { "type": "object", "required": [ "price", "decimals", "publishTime", "validUntil", "serverTime", "source", "corroborated" ], "properties": { "corroborated": { "type": "boolean" }, "decimals": { "type": "integer", "format": "int32", "minimum": 0 }, "price": { "type": "string" }, "publishTime": { "type": "integer", "format": "int64" }, "serverTime": { "type": "integer", "format": "int64" }, "source": { "type": "string" }, "validUntil": { "type": "integer", "format": "int64" } } }, "VerifyRequestDoc": { "type": "object", "required": [ "address", "signature", "challenge_id" ], "properties": { "address": { "type": "string" }, "challenge_id": { "type": "string" }, "signature": { "type": "string" } } } }, "securitySchemes": { "bearer_auth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Session JWT (browsers receive it as an httpOnly cookie from `POST /auth/verify`; 15 min, silently renewed via `POST /auth/refresh`), or a long-lived API token (`ss_…`) minted at `POST /api-tokens`. API tokens work on data and trading endpoints and can request WebSocket tickets; token management and admin endpoints accept session JWTs only." } } }, "tags": [ { "name": "schema", "description": "On-chain function input schemas for trading / liquidity / token operations" }, { "name": "auth", "description": "Wallet sign-in, sessions, logout, and WebSocket tickets" }, { "name": "access", "description": "Invite access redemption and administration" }, { "name": "api-tokens", "description": "Long-lived API tokens for programmatic access; send as `Authorization: Bearer ss_…` on any gated endpoint" }, { "name": "referral", "description": "Referral redemption and administration" }, { "name": "pools", "description": "Pool metadata, stats, trades, OHLCV" }, { "name": "positions", "description": "LP positions" }, { "name": "swaps", "description": "Historical swaps" }, { "name": "tokens", "description": "Token registry" }, { "name": "balances", "description": "On-chain token balances" }, { "name": "compliance", "description": "Token/pair allowlist, pause, and pool-creation gating state" }, { "name": "protocol", "description": "Fee tiers and tick spacings" }, { "name": "route", "description": "Swap routing" }, { "name": "debug", "description": "On-chain introspection helpers" }, { "name": "airdrop", "description": "Faucet: sends ALEO, USDCx, and ETH to a user address as records, once per address per 15 min" }, { "name": "unclaimed", "description": "Pending swap outputs and position fees" } ] }