{"openapi":"3.1.0","info":{"title":"InkCheck Agent API","version":"1.5.0","description":"Non-custodial API for user-authorized CLI agents on Ink Mainnet. Private keys never leave the local agent environment."},"servers":[{"url":"https://inkcheck.xyz"}],"paths":{"/api/agent/inkarena":{"get":{"operationId":"getInkArenaChallenge","summary":"Read a verified personal arena and suggested formation without authentication","parameters":[{"name":"address","in":"query","required":true,"schema":{"$ref":"#/components/schemas/Address"}},{"name":"difficulty","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":2}},{"name":"contractAddress","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Address"}}],"responses":{"200":{"description":"Current opponent, units, rules, expectedGameId, recommendation, preparePayload, confirmation fields and three reward tiers"},"400":{"$ref":"#/components/responses/Error"},"404":{"description":"Deploy and verify the personal arena first"},"503":{"description":"RPC temporarily unavailable"}}}},"/api/agent/manifest":{"get":{"operationId":"getAgentManifest","responses":{"200":{"description":"Capabilities and game registry"}}}},"/api/agent/advice":{"get":{"operationId":"getPublicAgentAdvice","summary":"Get a wallet's InkCheck position and recommended actions without authentication","parameters":[{"name":"address","in":"query","required":true,"schema":{"$ref":"#/components/schemas/Address"}}],"responses":{"200":{"description":"Rank, XP, daily and weekly opportunities, projections, and ordered recommendations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentAdvice"}}}},"400":{"$ref":"#/components/responses/Error"}}}},"/api/agent/auth/challenge":{"post":{"operationId":"createAgentChallenge","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address"],"properties":{"address":{"$ref":"#/components/schemas/Address"},"scopes":{"type":"array","items":{"enum":["read","deploy","play","checkin","claim","purchase"]}}}}}}},"responses":{"201":{"description":"Message to sign locally"},"400":{"$ref":"#/components/responses/Error"}}}},"/api/agent/auth/verify":{"post":{"operationId":"verifyAgentChallenge","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["challengeId","signature"],"properties":{"challengeId":{"type":"string","format":"uuid"},"signature":{"type":"string","pattern":"^0x[0-9a-fA-F]+$"}}}}}},"responses":{"200":{"description":"One-hour bearer token"},"401":{"$ref":"#/components/responses/Error"}}}},"/api/agent/state":{"get":{"operationId":"getAgentState","summary":"Get consolidated wallet state publicly by address or from an authenticated session","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"address","in":"query","required":false,"description":"Required when no bearer session is supplied","schema":{"$ref":"#/components/schemas/Address"}}],"responses":{"200":{"description":"Wallet, deployments, quests, XP, check-in, claims, and Season Pass offer state"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}}}},"/api/agent/actions/prepare":{"post":{"operationId":"prepareAgentAction","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["action","game"],"properties":{"action":{"const":"deploy"},"game":{"enum":["rps","lucky","rugpull","mastermind","blackjack","diceroll","slotmachine","higherorlower","minesweeper","plinko","tower","dungeonrun","keno","roulette","luckywheel","inkarena","containerclash"]},"maxTotalCost":{"$ref":"#/components/schemas/HumanBudget"}}},{"type":"object","required":["action","game","contractAddress","functionName"],"properties":{"action":{"const":"play"},"game":{"enum":["rps","lucky","rugpull","mastermind","blackjack","diceroll","slotmachine","higherorlower","minesweeper","plinko","tower","dungeonrun","keno","roulette","luckywheel","inkarena","containerclash"]},"contractAddress":{"$ref":"#/components/schemas/Address"},"functionName":{"type":"string"},"args":{"type":"array","items":{}},"maxTotalCost":{"$ref":"#/components/schemas/HumanBudget"}}},{"type":"object","required":["action"],"properties":{"action":{"const":"checkin"},"maxTotalCost":{"$ref":"#/components/schemas/HumanBudget"}}},{"type":"object","required":["action","currency","userApproved"],"properties":{"action":{"const":"seasonPass"},"currency":{"enum":["ETH","USDC"]},"userApproved":{"const":true,"description":"True only after the user explicitly approved the quoted purchase"},"maxTotalCost":{"$ref":"#/components/schemas/HumanBudget"}}},{"type":"object","required":["action","game","gameContract","gameId","signature"],"properties":{"action":{"const":"claim"},"game":{"enum":["rps","lucky","rugpull","mastermind","blackjack","diceroll","slotmachine","higherorlower","minesweeper","plinko","tower","dungeonrun","keno","roulette","luckywheel","inkarena","containerclash"]},"gameContract":{"$ref":"#/components/schemas/Address"},"gameId":{"type":"string"},"signature":{"type":"string"},"tierIndex":{"type":"integer","minimum":0,"maximum":255},"maxTotalCost":{"$ref":"#/components/schemas/HumanBudget"}}}]}}}},"responses":{"200":{"description":"Unsigned transaction request with a human-readable USD, USDC, or ETH budget verdict. Low-level transaction quantities are machine-only signing fields and must not be displayed to users."},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"description":"Estimated maximum total transaction cost exceeds the user's human-readable limit"},"503":{"description":"Budget cannot be enforced because gas, fee, or currency conversion is unavailable"}}}},"/api/agent/actions/confirm":{"post":{"operationId":"confirmAgentAction","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","transactionHash"],"properties":{"kind":{"enum":["deployment","game","checkin","claim","seasonPassApproval","seasonPass"]},"game":{"enum":["rps","lucky","rugpull","mastermind","blackjack","diceroll","slotmachine","higherorlower","minesweeper","plinko","tower","dungeonrun","keno","roulette","luckywheel","inkarena","containerclash"]},"contractAddress":{"$ref":"#/components/schemas/Address"},"gameId":{"type":"string"},"transactionHash":{"$ref":"#/components/schemas/TransactionHash"},"tier":{"oneOf":[{"type":"string"},{"type":"integer"}]}}}}}},"responses":{"200":{"description":"Validated and recorded action result"},"202":{"description":"Deployment recorded; bytecode verification pending"},"409":{"$ref":"#/components/responses/Error"}}}},"/api/agent/dungeonrun":{"post":{"operationId":"runDungeonOperation","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["operation","gameContract"],"properties":{"operation":{"enum":["seed","start","move","scan","reveal"]},"gameContract":{"$ref":"#/components/schemas/Address"},"payload":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"Dungeon operation result"},"403":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"opaque"}},"schemas":{"Address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","examples":["0x0000000000000000000000000000000000000001"]},"TransactionHash":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"HumanBudget":{"type":"object","required":["amount","currency"],"default":{"amount":"6","currency":"USD"},"properties":{"amount":{"type":"string","pattern":"^(?:0|[1-9][0-9]*)(?:\\.[0-9]{1,18})?$","description":"Positive human-readable decimal amount"},"currency":{"enum":["USD","USDC","ETH"]}},"description":"Maximum total transaction cost. InkCheck defaults omitted budgets to 6 USD and performs conversion internally; agents must never display wei."},"AgentAdvice":{"type":"object","required":["address","profile","today","recommendations","authorization","fetchedAt"],"properties":{"address":{"$ref":"#/components/schemas/Address"},"chainId":{"type":"integer","const":57073},"profile":{"type":"object","required":["xp","rank","totalPlayers","streak"],"properties":{"xp":{"type":"integer"},"rank":{"type":["integer","null"]},"totalPlayers":{"type":"integer"},"xpToTieNextRank":{"type":["integer","null"]},"xpToPassNextRank":{"type":["integer","null"]},"wins":{"type":"integer"},"games":{"type":"integer"},"streak":{"type":"integer"},"longestStreak":{"type":"integer"}}},"today":{"type":"object","required":["checkedIn","dailyGameXpRemaining","quests"],"properties":{"checkedIn":{"type":"boolean"},"checkinXpAvailable":{"type":"integer"},"dailyGameXpEarned":{"type":"integer"},"dailyGameXpCap":{"type":"integer"},"dailyGameXpRemaining":{"type":"integer"},"remainingQuestXp":{"type":"integer"},"maximumKnownXpAvailable":{"type":"integer"},"quests":{"type":"array","items":{"type":"object"}},"note":{"type":"string"}}},"weekly":{"type":"object","required":["quests","remainingQuestXp","resetAt"],"properties":{"quests":{"type":"array","items":{"type":"object"}},"remainingQuestXp":{"type":"integer"},"resetAt":{"type":["string","null"],"format":"date-time"}}},"recommendations":{"type":"array","items":{"type":"object","required":["priority","action","reason","expectedXp","transactionCount","estimatedCost","requiresAuthorization"],"properties":{"priority":{"type":"integer"},"action":{"enum":["fund","checkin","deploy","play","claim","seasonPass"]},"game":{"type":"string"},"reason":{"type":"string"},"expectedXp":{},"transactionCount":{"type":"object"},"estimatedCost":{"type":"object"},"budgetGuidance":{"type":"object","properties":{"recommendedMaximumUsd":{"type":"number"},"recommendedMinimumUsd":{"type":"number"},"rule":{"type":"string"}}},"requiresAuthorization":{"type":"boolean"},"preparePayload":{"type":["object","null"]},"questKeys":{"type":"array","items":{"type":"string"}}}}},"authorization":{"type":"object","properties":{"requiredForRead":{"const":false},"requiredForActions":{"const":true},"challengeEndpoint":{"type":"string"},"localExecutionOnboarding":{"type":"object","properties":{"trigger":{"const":"afterUserChoosesRealTransaction"},"discloseDuringReadOnly":{"const":false},"envTemplate":{"type":"string"},"publicWalletVariable":{"const":"INKCHECK_AGENT_WALLET_ADDRESS"},"privateKeyVariable":{"type":"string"},"perTransactionBudgetVariables":{"type":"array","items":{"type":"string"}},"seasonPassBudgetVariables":{"type":"array","items":{"type":"string"}},"optionalSessionBudgetVariables":{"type":"array","items":{"type":"string"}},"prepareBudgetField":{"const":"maxTotalCost"},"supportedBudgetCurrencies":{"type":"array","items":{"enum":["USD","USDC","ETH"]}},"autoPopulateDefaults":{"const":true},"onlyManualField":{"const":"INKCHECK_AGENT_PRIVATE_KEY"},"envPrefill":{"type":"object","additionalProperties":{"type":"string"}},"defaultTransactionLimit":{"$ref":"#/components/schemas/HumanBudget"},"userFacingUnitPolicy":{"type":"string"}}}}},"fetchedAt":{"type":"string","format":"date-time"}}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}}