{"openapi":"3.1.0","info":{"title":"AgentWallet API","version":"0.1.0","description":"Agent-native wallet API for hosted Solana devnet wallets protected by owner-defined on-chain policy."},"servers":[{"url":"https://agentwallet-web.vercel.app","description":"Production devnet demo"},{"url":"http://localhost:3002","description":"Local development"}],"tags":[{"name":"Agent runtime","description":"Endpoints intended for AI agents and agent frameworks."}],"paths":{"/api/agent-wallet/me":{"get":{"tags":["Agent runtime"],"summary":"Get hosted agent wallet status","description":"Returns the selected hosted agent wallet and basic readiness state.","security":[{"agentApiKey":[]}],"responses":{"200":{"description":"Agent wallet status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentWalletMe"}}}},"401":{"description":"Invalid agent API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}}}}},"/api/agent-wallet/setup-status":{"get":{"tags":["Agent runtime"],"summary":"Get setup status","description":"Returns missing setup steps and the next owner action needed before the agent can spend.","security":[{"agentApiKey":[]}],"responses":{"200":{"description":"Agent setup status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSetupStatus"}}}},"401":{"description":"Invalid agent API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}}}}},"/api/agent-wallet/capabilities":{"get":{"tags":["Agent runtime"],"summary":"Get agent wallet capabilities","description":"Returns policy-derived boundaries including allowed recipients, allowed token mints, spend caps, remaining budget, policy status, and supported actions.","security":[{"agentApiKey":[]}],"responses":{"200":{"description":"Agent capabilities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCapabilities"}}}},"400":{"description":"Policy not initialized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"401":{"description":"Invalid agent API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"404":{"description":"Policy account missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}}}}},"/api/agent-wallet/simulate-payment":{"post":{"tags":["Agent runtime"],"summary":"Simulate a policy-gated payment","description":"Reads the active on-chain policy and returns whether a payment would be approved, rejected, or require owner approval without signing or sending a transaction.","security":[{"agentApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"responses":{"200":{"description":"Payment simulation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSimulationResult"}}}},"400":{"description":"Structured policy or payment rejection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"401":{"description":"Invalid agent API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"404":{"description":"Policy account missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}}}}},"/api/agent-wallet/pay":{"post":{"tags":["Agent runtime"],"summary":"Execute a policy-gated payment","description":"Executes a Solana devnet SPL token transfer using the hosted agent wallet only if the on-chain policy allows it or an owner approval is available.","security":[{"agentApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"responses":{"200":{"description":"Executed payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResult"}}}},"400":{"description":"Structured policy or payment rejection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"401":{"description":"Invalid agent API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"402":{"description":"Owner approval required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}},"504":{"description":"Solana devnet timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}}}}},"/api/agent-wallet/audit":{"get":{"tags":["Agent runtime"],"summary":"Get agent audit log","description":"Returns recent audit events for the authenticated hosted agent.","security":[{"agentApiKey":[]}],"responses":{"200":{"description":"Audit events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditLog"}}}},"401":{"description":"Invalid agent API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredError"}}}}}}}},"components":{"securitySchemes":{"agentApiKey":{"type":"http","scheme":"bearer","bearerFormat":"AgentWallet API key"}},"schemas":{"AgentWalletMe":{"type":"object","additionalProperties":false,"required":["agent","status"],"properties":{"agent":{"$ref":"#/components/schemas/Agent"},"status":{"$ref":"#/components/schemas/AgentWalletStatus"}}},"AgentSetupStatus":{"type":"object","additionalProperties":false,"required":["agent","setup"],"properties":{"agent":{"$ref":"#/components/schemas/Agent"},"setup":{"type":"object","additionalProperties":false,"required":["ready","missing","ownerActionRequired","nextAction","availableActions","summary"],"properties":{"ready":{"type":"boolean"},"missing":{"type":"array","items":{"type":"string"}},"ownerActionRequired":{"type":"boolean"},"nextAction":{"type":"string"},"availableActions":{"type":"array","items":{"type":"string"}},"summary":{"type":"string"}}}}},"AgentCapabilities":{"type":"object","additionalProperties":false,"required":["ok","agent","policy","allowed","spend","canSpendNow","supportedActions","nextAction"],"properties":{"ok":{"const":true},"agent":{"$ref":"#/components/schemas/Agent"},"policy":{"type":"object","additionalProperties":false,"required":["pda","status","owner","programId","periodStartedAt","periodSeconds"],"properties":{"pda":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"owner":{"type":"string"},"programId":{"type":"string"},"periodStartedAt":{"type":"string"},"periodSeconds":{"type":"string"}}},"allowed":{"type":"object","additionalProperties":false,"required":["recipients","tokenMints"],"properties":{"recipients":{"type":"array","items":{"type":"string"}},"tokenMints":{"type":"array","items":{"type":"string"}}}},"spend":{"type":"object","additionalProperties":false,"required":["maxPerPaymentUnits","dailyBudgetUnits","spentInPeriodUnits","remainingBudgetUnits","approvalThresholdUnits"],"properties":{"maxPerPaymentUnits":{"type":"string"},"dailyBudgetUnits":{"type":"string"},"spentInPeriodUnits":{"type":"string"},"remainingBudgetUnits":{"type":"string"},"approvalThresholdUnits":{"type":"string"}}},"canSpendNow":{"type":"boolean"},"supportedActions":{"type":"array","items":{"type":"string"}},"nextAction":{"type":"string"}}},"PaymentRequest":{"type":"object","additionalProperties":false,"required":["recipient","amount"],"properties":{"recipient":{"type":"string","minLength":32},"amount":{"type":"string","minLength":1},"tokenMint":{"type":"string","minLength":32},"decimals":{"type":"integer","minimum":0,"maximum":9},"policyPda":{"type":"string","minLength":32},"programId":{"type":"string","minLength":32}}},"PaymentSimulationResult":{"type":"object","additionalProperties":false,"required":["ok","decision","code","message","humanMessage","agentMessage","suggestedAction","amount","amountUnits","tokenMint","recipient","policyPda","remainingBudgetUnits"],"properties":{"ok":{"const":true},"decision":{"type":"string","enum":["approved","requires_approval","rejected"]},"code":{"type":"string"},"message":{"type":"string"},"humanMessage":{"type":"string"},"agentMessage":{"type":"string"},"suggestedAction":{"type":"string"},"amount":{"type":"string"},"amountUnits":{"type":"string"},"tokenMint":{"type":"string"},"recipient":{"type":"string"},"policyPda":{"type":"string"},"remainingBudgetUnits":{"type":"string"}}},"PaymentResult":{"type":"object","additionalProperties":false,"required":["ok","cluster","agent","policyPda","tokenMint","amount","signature","explorerUrl","agentTokenAccount","recipientTokenAccount","approvalId"],"properties":{"ok":{"const":true},"cluster":{"const":"devnet"},"agent":{"type":"string"},"policyPda":{"type":"string"},"tokenMint":{"type":"string"},"amount":{"type":"string"},"signature":{"type":"string"},"explorerUrl":{"type":"string"},"agentTokenAccount":{"type":"string"},"recipientTokenAccount":{"type":"string"},"approvalId":{"type":"string"}}},"AuditLog":{"type":"object","additionalProperties":false,"required":["events"],"properties":{"events":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","type","status","message","createdAt","signature","explorerUrl"],"properties":{"id":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"message":{"type":"string"},"createdAt":{"type":"string"},"signature":{"type":"string"},"explorerUrl":{"type":"string"}}}}}},"Agent":{"type":"object","additionalProperties":false,"required":["id","owner","name","publicKey","apiKeyPrefix","programId","policyPda","tokenMint","decimals","telegramChatId","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"owner":{"type":"string"},"name":{"type":"string"},"publicKey":{"type":"string"},"apiKeyPrefix":{"type":"string"},"programId":{"type":"string"},"policyPda":{"type":["string","null"]},"tokenMint":{"type":"string"},"decimals":{"type":"integer"},"telegramChatId":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}}},"AgentWalletStatus":{"type":"object","additionalProperties":false,"required":["readyForPayments","policyConfigured","tokenMintConfigured","telegramLinked","missing"],"properties":{"readyForPayments":{"type":"boolean"},"policyConfigured":{"type":"boolean"},"tokenMintConfigured":{"type":"boolean"},"telegramLinked":{"type":"boolean"},"missing":{"type":"array","items":{"type":"string"}}}},"StructuredError":{"type":"object","additionalProperties":false,"required":["ok","error","code","message","humanMessage","agentMessage","suggestedAction"],"properties":{"ok":{"const":false},"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"humanMessage":{"type":"string"},"agentMessage":{"type":"string"},"suggestedAction":{"type":"string"}}}}}}