{ "openapi": "3.1.0", "info": { "title": "AI.GG Agent API", "version": "0.1.0", "description": "Agent-readable sketch of the AI.GG TEE-aware account-level payment and gateway surface. Authenticated endpoints, exact schemas, provider TEE policy, and model availability depend on deployment configuration." }, "servers": [ { "url": "https://api.ai.gg", "description": "AI.GG production surface" } ], "paths": { "/llms.txt": { "get": { "summary": "Get concise AI.GG agent context", "responses": { "200": { "description": "Markdown agent context" } } } }, "/facts.json": { "get": { "summary": "Get canonical AI.GG product facts", "responses": { "200": { "description": "Canonical product facts" } } } }, "/api/v1/auth/login": { "post": { "summary": "Authenticate a user session", "description": "Returns a bearer access token for user-facing account, wallet, payment, CCA, ledger, and setup APIs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "Authenticated session token and user profile" }, "401": { "description": "Invalid credentials" } } } }, "/api/v1/agent/setup/manifest": { "get": { "summary": "Get the authenticated agent setup manifest", "description": "Machine-readable contract for model-family API keys, wallet funding, x402 settlement, CCA bid/claim, platform asset ledger, and skill consumption endpoints.", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Agent setup manifest" }, "401": { "description": "Authentication required" } } } }, "/api/v1/opencode/api-key/find-or-create": { "post": { "summary": "Find or create an AI.GG API key for an agent model family", "description": "Lets an authenticated agent create or reuse an API key for gateway calls without relying on the browser UI.", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "group_id": { "type": "integer", "format": "int64" } }, "required": [ "name", "group_id" ] } } } }, "responses": { "200": { "description": "Existing API key" }, "201": { "description": "New API key" } } } }, "/api/v1/payment/checkout-info": { "get": { "summary": "Get payment and x402 checkout capability", "description": "Returns enabled funding methods, x402 network, GCC support, limits, and subscription purchase options.", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Checkout configuration" } } } }, "/api/v1/payment/x402/top-up": { "post": { "summary": "Create or settle an x402 top-up for ordinary balance or GCC", "description": "Used by wallet-enabled clients to top up AI.GG account balance with USDC or deposit GCC into the platform GCC balance. The request may receive an x402 payment challenge before settlement.", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Requested top-up amount." }, "asset": { "type": "string", "enum": [ "balance", "usdc", "gcc" ], "description": "Target asset. Use gcc for direct GCC top-up." } }, "required": [ "amount" ] } } } }, "responses": { "200": { "description": "Top-up settled or accepted" }, "402": { "description": "x402 payment challenge" }, "401": { "description": "Authentication required" } } } }, "/api/v1/payment/x402/okx/status": { "get": { "summary": "Get linked OKX Agentic Wallet status and balances", "description": "Returns the user's linked OKX Agentic Wallet email, EVM address where available, and external wallet ETH/USDC/GCC balances. These wallet balances are separate from the AI.GG platform ledger.", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "OKX Agentic Wallet status" } } } }, "/api/v1/payment/x402/okx/login": { "post": { "summary": "Start OKX Agentic Wallet email login", "description": "Sends an email OTP for linking the authenticated AI.GG account to an OKX Agentic Wallet.", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "locale": { "type": "string" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "OTP sent" } } } }, "/api/v1/payment/x402/okx/verify": { "post": { "summary": "Verify OKX Agentic Wallet email OTP", "description": "Completes Agentic Wallet linking and returns wallet status.", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "otp": { "type": "string" } }, "required": [ "otp" ] } } } }, "responses": { "200": { "description": "Wallet linked" } } } }, "/api/v1/payment/x402/okx/top-up": { "post": { "summary": "Settle wallet USDC or GCC into the AI.GG platform ledger with OKX Agentic Wallet", "description": "Uses the linked OKX Agentic Wallet to sign and settle x402. USDC credits the platform USDC ledger; GCC credits the platform GCC ledger for skill consumption.", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number" }, "asset": { "type": "string", "enum": [ "usdc", "gcc" ] } }, "required": [ "amount" ] } } } }, "responses": { "200": { "description": "Settlement complete and platform ledger credited" }, "402": { "description": "Payment authorization required or settlement failed" } } } }, "/api/v1/gcc/cca/status": { "get": { "summary": "Get current GCC CCA auction status", "description": "Returns current auction, network, token, currency, wallet, limits, and auction phase. Returns CCA_NOT_CONFIGURED when no current auction is configured.", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "CCA auction status" }, "503": { "description": "CCA is not configured" } } } }, "/api/v1/gcc/cca/bid-preview": { "post": { "summary": "Preview a GCC CCA bid from OKX Agentic Wallet", "description": "Checks wallet gas, currency balance, allowance needs, and estimated transactions before submitting a CCA bid.", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency_amount": { "type": "string", "description": "USDC bid amount as a decimal string." }, "max_price_usdc_per_gcc": { "type": "string", "description": "Optional max USDC per GCC." } }, "required": [ "currency_amount" ] } } } }, "responses": { "200": { "description": "Bid preview" }, "503": { "description": "CCA is not configured" } } } }, "/api/v1/gcc/cca/bids": { "get": { "summary": "List authenticated user's GCC CCA bids", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "CCA bid list" } } }, "post": { "summary": "Submit a GCC CCA bid from OKX Agentic Wallet", "description": "Calls the CCA contract using the linked OKX Agentic Wallet. Filled GCC lands in the wallet first; use x402 GCC top-up afterwards to move GCC into the AI.GG platform ledger.", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency_amount": { "type": "string" }, "max_price_usdc_per_gcc": { "type": "string" } }, "required": [ "currency_amount" ] } } } }, "responses": { "200": { "description": "Bid submitted" }, "503": { "description": "CCA is not configured" } } } }, "/api/v1/gcc/cca/bids/{id}/claim": { "post": { "summary": "Claim a filled GCC CCA bid", "description": "Claims filled GCC to the OKX Agentic Wallet. Agents should then settle GCC to the platform ledger before skill consumption.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Claim transaction submitted or bid already claimable/claimed" } } } }, "/api/v1/gcc/cca/bids/{id}": { "get": { "summary": "Get a GCC CCA bid", "description": "Returns one authenticated user's GCC CCA bid by ID.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "CCA bid detail" } } } }, "/api/v1/gcc/cca/bids/{id}/refresh": { "post": { "summary": "Refresh a GCC CCA bid", "description": "Refreshes on-chain status for one authenticated user's GCC CCA bid.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Refreshed CCA bid status" } } } }, "/api/v1/subscriptions/erc8257/current": { "get": { "summary": "Get current ERC-8257 subscription entitlement", "description": "Returns the authenticated user's latest ERC-8257 subscription access snapshot. This access unlocks the AI.GG gateway tool; GCC in the platform ledger remains the spendable capacity balance.", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Current ERC-8257 entitlement snapshot" }, "401": { "description": "Authentication required" }, "503": { "description": "Entitlement verification is not configured or unavailable" } } } }, "/api/v1/subscriptions/erc8257/refresh": { "post": { "summary": "Refresh ERC-8257 subscription entitlement from Base", "description": "Reads the linked OKX Agentic Wallet or supplied wallet address against the Base ERC-8257 subscription predicate, then stores the entitlement snapshot used by gateway access checks.", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet_address": { "type": "string", "description": "Optional wallet address. If omitted, AI.GG uses the linked OKX Agentic Wallet address." } } } } } }, "responses": { "200": { "description": "Refreshed ERC-8257 entitlement snapshot" }, "400": { "description": "Wallet address does not match the linked Agentic Wallet" }, "401": { "description": "Authentication required" }, "503": { "description": "Entitlement verification is not configured or unavailable" } } } }, "/api/v1/assets/ledger": { "get": { "summary": "List platform asset ledger entries", "description": "Returns USD, USDC, and GCC platform ledger entries. Platform ledger balances are separate from OKX Agentic Wallet balances.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "asset", "in": "query", "schema": { "type": "string", "enum": [ "usd", "usdc", "gcc" ] } }, { "name": "entry_type", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "page_size", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paginated platform asset ledger entries" } } } }, "/api/v1/usage/dashboard/stats": { "get": { "summary": "Get authenticated user's usage statistics", "description": "Returns request and cost statistics for API and agent skill consumption.", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Usage dashboard statistics" } } } }, "/api/v1/admin/tee/image-hashes": { "get": { "summary": "List trusted TEE image hashes for provider capacity", "description": "Administrative surface for reviewing the TEE image hash allowlist used by provider endpoint trust policy.", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Trusted TEE image hash list" }, "401": { "description": "Authentication required" }, "403": { "description": "Admin permission required" } } } }, "/v1/chat/completions": { "post": { "summary": "OpenAI-compatible chat completion through AI.GG", "description": "Representative OpenAI-compatible gateway path for agent skill model calls. Exact route availability depends on deployment and account configuration.", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Model response" }, "401": { "description": "Invalid or missing API key" }, "402": { "description": "Insufficient GCC or ordinary balance" } } } } }, "components": { "securitySchemes": { "apiKeyAuth": { "type": "http", "scheme": "bearer", "description": "AI.GG API key used by agent skills." }, "sessionAuth": { "type": "http", "scheme": "bearer", "description": "Authenticated user bearer token returned by /api/v1/auth/login." } } } }