{"openapi":"3.0.0","info":{"title":"Naven API","version":"1.0.0","description":"Backend API for Naven web and x402 facilitator workflows."},"servers":[{"url":"https://api.naven.network"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Privy identity token used by signed-in Naven users."},"ProjectApiKey":{"type":"http","scheme":"bearer","bearerFormat":"naven_api_...","description":"Server-side Project API key. Never expose this key in browser code."}},"schemas":{"Version":{"type":"object","properties":{"commit":{"type":"string","example":"d948d9e"},"branch":{"type":"string","example":"main"},"buildTime":{"type":"string","example":"2026-03-18T16:03:33Z"}},"required":["commit","branch","buildTime"]},"VersionSuccessResponse":{"type":"object","properties":{"code":{"type":"number","example":0},"message":{"type":"string","example":"ok"},"data":{"$ref":"#/components/schemas/Version"}},"required":["code","message","data"]},"PaymentIntent":{"type":"object","properties":{"id":{"type":"string","example":"pi_01JABC"},"merchantId":{"type":"string","example":"cmerchant123"},"externalId":{"type":"string","example":"topup_01JABC"},"customerRef":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"status":{"type":"string","enum":["pending","settling","settled","failed","expired"]},"amountUsdCents":{"type":"integer","example":9900},"currency":{"type":"string","enum":["USD"]},"paymentUrl":{"type":"string","format":"uri"},"network":{"type":"string","example":"eip155:4663"},"asset":{"type":"string","example":"0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168"},"payTo":{"type":"string","example":"0x2222222222222222222222222222222222222222"},"transactionHash":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"settledAt":{"type":"string","nullable":true,"format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"failureCode":{"type":"string","nullable":true},"failureMessage":{"type":"string","nullable":true}},"required":["id","merchantId","externalId","customerRef","description","metadata","status","amountUsdCents","currency","paymentUrl","network","asset","payTo","transactionHash","createdAt","settledAt","expiresAt","failureCode","failureMessage"]},"PaymentIntentError":{"type":"object","properties":{"code":{"type":"string","example":"intent_not_found"},"message":{"type":"string"},"details":{"nullable":true}},"required":["code","message"]},"CreatePaymentIntentRequest":{"type":"object","properties":{"merchantId":{"type":"string","minLength":1,"maxLength":200,"example":"cmerchant123"},"amountUsdCents":{"type":"integer","minimum":100,"maximum":100000000,"example":9900},"externalId":{"type":"string","minLength":1,"maxLength":200,"example":"topup_01JABC"},"customerRef":{"type":"string","minLength":1,"maxLength":200,"example":"privy_user_01JABC"},"description":{"type":"string","minLength":1,"maxLength":500,"example":"Workspace credit top-up"},"metadata":{"type":"object","additionalProperties":{"nullable":true},"example":{"workspaceId":"workspace_01JABC"}}},"required":["merchantId","amountUsdCents","externalId"]},"PaymentIntentSettlement":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","settling","settled","failed","expired"]},"amountUsdCents":{"type":"integer"},"currency":{"type":"string","enum":["USD"]},"settlement":{"type":"object","nullable":true,"properties":{"transaction":{"type":"string"},"network":{"type":"string"},"payer":{"type":"string","nullable":true},"settledAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["transaction","network","payer","settledAt"]}},"required":["id","status","amountUsdCents","currency","settlement"]},"X402PaymentRequired":{"type":"object","properties":{"x402Version":{"type":"number","enum":[2]},"resource":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"mimeType":{"type":"string"},"serviceName":{"type":"string"}},"required":["url","description","mimeType","serviceName"]},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string","enum":["exact"]},"network":{"type":"string","example":"eip155:4663"},"asset":{"type":"string"},"amount":{"type":"string","example":"99000000"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"}},"required":["name","version"]}},"required":["scheme","network","asset","amount","payTo","maxTimeoutSeconds","extra"]}},"error":{"type":"string"}},"required":["x402Version","resource","accepts"]},"ProjectApiKey":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"prefix":{"type":"string","example":"naven_api_abc1234567890"},"status":{"type":"string","example":"active"},"lastUsedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","prefix","status","lastUsedAt","createdAt"]},"Merchant":{"type":"object","properties":{"id":{"type":"string","example":"cmerchant123"},"name":{"type":"string","example":"Workspace Credits"},"enabled":{"type":"boolean"},"payTo":{"type":"string","example":"0x2222222222222222222222222222222222222222"},"network":{"type":"string","example":"eip155:4663"},"asset":{"type":"string","example":"0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","enabled","payTo","network","asset","createdAt","updatedAt"]},"Project":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Vanta"},"status":{"type":"string","example":"active"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"apiKeys":{"type":"array","items":{"$ref":"#/components/schemas/ProjectApiKey"}},"merchants":{"type":"array","items":{"$ref":"#/components/schemas/Merchant"}}},"required":["id","name","status","createdAt","updatedAt","apiKeys","merchants"]},"ListProjectsResponse":{"type":"object","properties":{"code":{"type":"number","enum":[0]},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}}},"required":["code","message","data"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"number","example":1001},"message":{"type":"string","example":"Unauthorized"},"data":{"nullable":true}},"required":["code","message","data"]},"CreateProjectResponse":{"type":"object","properties":{"code":{"type":"number","enum":[0]},"message":{"type":"string"},"data":{"type":"object","properties":{"project":{"$ref":"#/components/schemas/Project"},"apiKey":{"allOf":[{"$ref":"#/components/schemas/ProjectApiKey"},{"type":"object","properties":{"secret":{"type":"string","example":"naven_api_..."}},"required":["secret"]}]}},"required":["project","apiKey"]}},"required":["code","message","data"]},"CreateProjectRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"example":"Vanta"}},"required":["name"]},"CreateProjectApiKeyResponse":{"type":"object","properties":{"code":{"type":"number","enum":[0]},"message":{"type":"string"},"data":{"allOf":[{"$ref":"#/components/schemas/ProjectApiKey"},{"type":"object","properties":{"secret":{"type":"string","example":"naven_api_..."}},"required":["secret"]}]}},"required":["code","message","data"]},"CreateProjectApiKeyRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"example":"production"}},"required":["name"]},"CreateMerchantResponse":{"type":"object","properties":{"code":{"type":"number","enum":[0]},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Merchant"}},"required":["code","message","data"]},"CreateMerchantRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"example":"Workspace Credits"},"payTo":{"type":"string","example":"0x2222222222222222222222222222222222222222"}},"required":["name","payTo"]},"AgentRuntimeInstanceSummary":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"appName":{"type":"string"},"url":{"type":"string"},"cpus":{"type":"integer"},"memoryMb":{"type":"integer"},"volumeSizeGb":{"type":"integer"},"startedAt":{"type":"string","nullable":true,"format":"date-time"},"expiresAt":{"type":"string","nullable":true,"format":"date-time"},"stoppedAt":{"type":"string","nullable":true,"format":"date-time"},"removedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","appName","url","cpus","memoryMb","volumeSizeGb","startedAt","expiresAt","stoppedAt","removedAt"]},"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"userId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["openclaw","hermes"],"example":"openclaw"},"spec":{"type":"string","enum":["monthly"]},"status":{"type":"string","example":"pending"},"attempts":{"type":"integer"},"lastError":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","userId","name","type","spec","status","attempts","lastError","createdAt","updatedAt"]},"AgentWithRuntimeInstance":{"allOf":[{"$ref":"#/components/schemas/Agent"},{"type":"object","properties":{"openclawInstance":{"$ref":"#/components/schemas/AgentRuntimeInstanceSummary"}},"required":["openclawInstance"]}]},"ListAgentsSuccessResponse":{"type":"object","properties":{"code":{"type":"number","example":0},"message":{"type":"string","example":"ok"},"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentWithRuntimeInstance"}}},"required":["code","message","data"]},"CreateAgentSuccessResponse":{"type":"object","properties":{"code":{"type":"number","example":0},"message":{"type":"string","example":"ok"},"data":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/Agent"},"charge":{"type":"object","properties":{"amountUsdCents":{"type":"integer","example":1000},"balanceAfterUsdCents":{"type":"integer","example":0}},"required":["amountUsdCents","balanceAfterUsdCents"]}},"required":["agent","charge"]}},"required":["code","message","data"]},"CreateAgentRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"example":"Research Agent"},"type":{"type":"string","enum":["openclaw","hermes"],"example":"openclaw"}},"required":["name","type"]},"AgentChatSuccessResponse":{"type":"object","properties":{"code":{"type":"number","example":0},"message":{"type":"string","example":"ok"},"data":{"type":"object","properties":{"message":{"nullable":true},"raw":{"nullable":true},"text":{"type":"string"}},"required":["text"]}},"required":["code","message","data"]},"AgentChatMessage":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"],"example":"user"},"content":{"type":"string","example":"Summarize today's plan."}},"required":["role","content"]},"AgentChatRequest":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/AgentChatMessage"},"minItems":1},"session":{"type":"string","minLength":1,"maxLength":100,"default":"main","example":"main"}},"required":["messages"]},"OpenClawConfigSuccessResponse":{"type":"object","properties":{"code":{"type":"number","example":0},"message":{"type":"string","example":"ok"},"data":{"type":"object","properties":{"createdAt":{"type":"string"},"id":{"type":"string"},"instanceId":{"type":"string"},"models":{"nullable":true},"telegramBot":{"nullable":true},"updatedAt":{"type":"string"}},"required":["createdAt","id","instanceId","updatedAt"]}},"required":["code","message","data"]},"ConfigureModelProviderRequest":{"type":"object","properties":{"provider":{"type":"string","enum":["openai","deepseek","anthropic"],"example":"openai"},"apiKey":{"type":"string","minLength":1,"example":"sk-..."}},"required":["provider","apiKey"]},"OpenClawModelProvidersSuccessResponse":{"type":"object","properties":{"code":{"type":"number","example":0},"message":{"type":"string","example":"ok"},"data":{"type":"array","items":{"type":"object","properties":{"apiKey":{"type":"string","example":"sk-proj***abcde"},"provider":{"type":"string","example":"openai"}},"required":["apiKey","provider"]}}},"required":["code","message","data"]},"AgentChatHistorySuccessResponse":{"type":"object","properties":{"code":{"type":"number","example":0},"message":{"type":"string","example":"ok"},"data":{"type":"object","properties":{"messages":{"type":"array","items":{"nullable":true}},"raw":{"nullable":true}},"required":["messages"]}},"required":["code","message","data"]},"CreditsBalance":{"type":"object","properties":{"balanceUsdCents":{"type":"integer","example":1000}},"required":["balanceUsdCents"]},"CreditsBalanceSuccessResponse":{"type":"object","properties":{"code":{"type":"number","example":0},"message":{"type":"string","example":"ok"},"data":{"$ref":"#/components/schemas/CreditsBalance"}},"required":["code","message","data"]}},"parameters":{}},"paths":{"/health":{"get":{"tags":["Health"],"summary":"Health check","description":"Returns service status and current version.","responses":{"200":{"description":"Service is healthy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionSuccessResponse"}}}}}}},"/v1/payment-intents":{"post":{"tags":["Payment Intents"],"summary":"Create a Payment Intent","description":"Creates an immutable x402 payment request for a Merchant in the authenticated Project. The Project API key must remain on the server.","security":[{"ProjectApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentIntentRequest"}}}},"responses":{"200":{"description":"An idempotent retry returned the existing intent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntent"}}}},"201":{"description":"Payment Intent was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntent"}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentError"}}}},"401":{"description":"Missing or invalid Project API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentError"}}}},"403":{"description":"Project or API key is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentError"}}}},"404":{"description":"Merchant was not found in this Project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentError"}}}},"409":{"description":"The Merchant external ID was reused with different immutable input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentError"}}}}}}},"/v1/payment-intents/{intentId}/reconcile":{"post":{"tags":["Payment Intents"],"summary":"Reconcile a Payment Intent","description":"Idempotently checks a settling Payment Intent against indexed Robinhood USDG settlements.","security":[{"ProjectApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"intentId","in":"path"}],"responses":{"200":{"description":"The current Payment Intent state was returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntent"}}}},"401":{"description":"Missing or invalid Project API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentError"}}}},"404":{"description":"Intent was not found in this Project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentError"}}}},"503":{"description":"Reconciliation is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentError"}}}}}}},"/v1/payment-intents/{intentId}":{"get":{"tags":["Payment Intents"],"summary":"Get Payment Intent status","description":"Returns authoritative payment status for an intent belonging to the authenticated Project.","security":[{"ProjectApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"intentId","in":"path"}],"responses":{"200":{"description":"Payment Intent was returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntent"}}}},"401":{"description":"Missing or invalid Project API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentError"}}}},"403":{"description":"Project or API key is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentError"}}}},"404":{"description":"Intent was not found in this Project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentError"}}}}}}},"/v1/payment-intents/{intentId}/pay":{"post":{"tags":["Payment Intents"],"summary":"Pay a Payment Intent","description":"Public x402 v2 endpoint. Call without a payment header to receive a 402 requirement, then sign it and retry with PAYMENT-SIGNATURE.","parameters":[{"schema":{"type":"string"},"required":true,"name":"intentId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"PAYMENT-SIGNATURE","in":"header"},{"schema":{"type":"string"},"required":false,"name":"X-PAYMENT","in":"header"}],"responses":{"200":{"description":"Payment was settled or the existing settled result was returned.","headers":{"PAYMENT-RESPONSE":{"description":"Base64-encoded x402 settlement response.","schema":{"type":"string"}},"X-PAYMENT-RESPONSE":{"description":"Legacy alias for PAYMENT-RESPONSE.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentSettlement"}}}},"402":{"description":"Payment is required or the submitted payment was invalid.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 v2 requirements.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402PaymentRequired"}}}},"403":{"description":"Merchant is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentError"}}}},"404":{"description":"Intent was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentError"}}}},"409":{"description":"Intent is failed, malformed, already used, or currently settling.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentError"}}}},"410":{"description":"Intent expired before settlement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentError"}}}},"429":{"description":"Too many payment attempts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentError"}}}},"503":{"description":"Facilitator verification or settlement is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentError"}}}}}}},"/v1/projects":{"get":{"tags":["Projects"],"summary":"List projects","description":"Lists Projects owned by the signed-in Privy user, including API key metadata and Merchants.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Projects were returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListProjectsResponse"}}}},"401":{"description":"Missing or invalid Privy identity token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Projects"],"summary":"Create a project","description":"Creates a Project and returns its default Project API key secret exactly once.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectRequest"}}}},"responses":{"201":{"description":"Project and default API key were created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectResponse"}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid Privy identity token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/api-keys":{"post":{"tags":["Projects"],"summary":"Create a Project API key","description":"Creates a server-side key and returns its secret exactly once.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"projectId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectApiKeyRequest"}}}},"responses":{"201":{"description":"Project API key was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectApiKeyResponse"}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid Privy identity token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Project was not found for this user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/merchants":{"post":{"tags":["Projects"],"summary":"Create a Merchant","description":"Creates an isolated x402 receiver under the Project. Naven supplies network, asset, and facilitator configuration.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"projectId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMerchantRequest"}}}},"responses":{"201":{"description":"Merchant was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMerchantResponse"}}}},"400":{"description":"Invalid request body or payTo address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid Privy identity token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Project was not found for this user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/agents":{"get":{"tags":["Agents"],"summary":"List agents","description":"Returns the authenticated user's deployed agent runtimes.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Agents were returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListAgentsSuccessResponse"}}}},"401":{"description":"Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Privy is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Agents"],"summary":"Create an agent","description":"Charges $10 of internal credits and queues a one-month OpenClaw or Hermes runtime deployment.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentRequest"}}}},"responses":{"201":{"description":"Agent was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentSuccessResponse"}}}},"401":{"description":"Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Privy is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/agents/{agentId}/chat":{"post":{"tags":["Agents"],"summary":"Chat with an agent","description":"Proxies a non-streaming chat request to the authenticated user's running agent.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"agentId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentChatRequest"}}}},"responses":{"200":{"description":"Agent chat response was returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentChatSuccessResponse"}}}},"400":{"description":"Invalid chat request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Agent was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Agent gateway failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/agents/{agentId}/config/model-provider":{"put":{"tags":["Agents"],"summary":"Configure an agent model provider","description":"Configures an AI model provider API key for a running agent. The key is scoped to this agent runtime.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"agentId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigureModelProviderRequest"}}}},"responses":{"200":{"description":"Agent model provider was configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenClawConfigSuccessResponse"}}}},"400":{"description":"Invalid model provider request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Agent was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Agent gateway failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/agents/{agentId}/config/model-providers":{"get":{"tags":["Agents"],"summary":"Get agent model providers","description":"Returns the configured AI model providers for an agent with API keys masked.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"agentId","in":"path"}],"responses":{"200":{"description":"Agent model providers were returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenClawModelProvidersSuccessResponse"}}}},"401":{"description":"Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Agent was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Agent config lookup failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/agents/{agentId}/chat/history":{"get":{"tags":["Agents"],"summary":"Get agent chat history","description":"Fetches the authenticated user's OpenClaw agent chat transcript from the Gateway session history.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"agentId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":100,"example":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100,"default":"main","example":"main"},"required":false,"name":"session","in":"query"}],"responses":{"200":{"description":"Agent chat history was returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentChatHistorySuccessResponse"}}}},"400":{"description":"Invalid chat history request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Agent was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Agent gateway failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/user":{"get":{"tags":["User"],"summary":"Get user module version","description":"Example authenticated endpoint protected by Privy.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Request succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionSuccessResponse"}}}},"401":{"description":"Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Authenticated but forbidden.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Privy is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/credits":{"get":{"tags":["Credits"],"summary":"Get Naven Credits balance","description":"Returns the authenticated user's internal USD credit balance.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Credits balance was returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsBalanceSuccessResponse"}}}},"401":{"description":"Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Privy or credits x402 is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}