{"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"},"creditBalanceUsdMicros":{"type":"string","example":"10000000"},"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","creditBalanceUsdMicros","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"]},"TransferProjectCreditsResponse":{"type":"object","properties":{"code":{"type":"number","enum":[0]},"message":{"type":"string"},"data":{"type":"object","properties":{"balanceUsdCents":{"type":"integer"},"projectBalanceUsdMicros":{"type":"string"}},"required":["balanceUsdCents","projectBalanceUsdMicros"]}},"required":["code","message","data"]},"TransferProjectCreditsRequest":{"type":"object","properties":{"amountUsdCents":{"type":"integer","minimum":1,"maximum":100000000,"example":100}},"required":["amountUsdCents"]},"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/ipfs/config":{"get":{"tags":["IPFS Storage"],"responses":{"200":{"description":"Upload result","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{}}},"required":["code","message","data"]}}}}}}},"/v1/ipfs/upload":{"post":{"tags":["IPFS Storage"],"summary":"Pay once and store an image on IPFS and R2; no account required","parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"orderId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"idempotency-key","in":"header"},{"schema":{"type":"string"},"required":false,"name":"payment-signature","in":"header"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"200":{"description":"Upload result","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{}}},"required":["code","message","data"]}}}},"402":{"description":"x402 payment required","content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"number"},"resource":{"type":"object","properties":{}},"accepts":{"type":"array","items":{"type":"object","properties":{}}}},"required":["x402Version","resource","accepts"]}}}},"default":{"description":"Upload or payment failed; reuse the same Idempotency-Key"}}}},"/v1/ipfs/orders/{id}":{"get":{"tags":["IPFS Storage"],"summary":"Recover an upload using its original Idempotency-Key","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Upload result","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{}}},"required":["code","message","data"]}}}},"default":{"description":"Order unavailable"}}}},"/v1/ipfs/orders/{id}/reconcile":{"post":{"tags":["IPFS Storage"],"summary":"Recover an uncertain payment from the internal transaction index","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"transactionHash":{"type":"string","pattern":"^0x[\\da-f]{64}$"}},"required":["transactionHash"],"additionalProperties":false}}}},"responses":{"200":{"description":"Upload result","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","properties":{}}},"required":["code","message","data"]}}}},"default":{"description":"Payment could not be reconciled"}}}},"/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"}}}}}}},"/v1/projects/{projectId}/credits/transfer":{"post":{"tags":["Projects"],"summary":"Transfer personal Credits to a project","description":"Moves prepaid Credits owned by the signed-in user into an active project's API balance. No new payment is made.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"projectId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferProjectCreditsRequest"}}}},"responses":{"200":{"description":"Credits were transferred to the project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferProjectCreditsResponse"}}}},"400":{"description":"Invalid amount or insufficient personal Credits.","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":"Active 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"}}}}}}},"/chat/conversations":{"get":{"tags":["Chat"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Chat conversations.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"400":{"description":"Invalid chat request.","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":"Chat resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Chat state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Marketplace request was too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Chat request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream chat or marketplace service failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Chat is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Marketplace request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Chat"],"security":[{"BearerAuth":[]}],"responses":{"201":{"description":"Conversation created.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"400":{"description":"Invalid chat request.","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":"Chat resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Chat state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Marketplace request was too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Chat request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream chat or marketplace service failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Chat is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Marketplace request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/chat/conversations/{conversationId}":{"get":{"tags":["Chat"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversationId","in":"path"}],"responses":{"200":{"description":"Conversation details.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"400":{"description":"Invalid chat request.","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":"Chat resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Chat state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Marketplace request was too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Chat request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream chat or marketplace service failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Chat is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Marketplace request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Chat"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversationId","in":"path"}],"responses":{"200":{"description":"Conversation deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"400":{"description":"Invalid chat request.","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":"Chat resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Chat state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Marketplace request was too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Chat request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream chat or marketplace service failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Chat is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Marketplace request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/chat/services":{"get":{"tags":["Chat"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","maxLength":120,"default":""},"required":false,"name":"q","in":"query"}],"responses":{"200":{"description":"Verified Robinhood USDG services.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"400":{"description":"Invalid chat request.","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":"Chat resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Chat state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Marketplace request was too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Chat request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream chat or marketplace service failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Chat is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Marketplace request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/chat/settings":{"get":{"tags":["Chat"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Chat payment settings.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"400":{"description":"Invalid chat request.","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":"Chat resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Chat state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Marketplace request was too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Chat request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream chat or marketplace service failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Chat is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Marketplace request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Chat"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"autoApproveLimit":{"type":"string","pattern":"^(?:0|[1-9]\\d*)(?:\\.\\d{1,6})?$"}},"required":["autoApproveLimit"]}}}},"responses":{"200":{"description":"Updated chat payment settings.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"400":{"description":"Invalid chat request.","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":"Chat resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Chat state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Marketplace request was too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Chat request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream chat or marketplace service failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Chat is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Marketplace request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/chat/wallet":{"get":{"tags":["Chat"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Chat wallet or null.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"400":{"description":"Invalid chat request.","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":"Chat resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Chat state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Marketplace request was too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Chat request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream chat or marketplace service failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Chat is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Marketplace request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Chat"],"security":[{"BearerAuth":[]}],"responses":{"201":{"description":"Chat wallet provisioned.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"400":{"description":"Invalid chat request.","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":"Chat resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Chat state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Marketplace request was too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Chat request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream chat or marketplace service failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Chat is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Marketplace request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/chat/conversations/{conversationId}/messages":{"post":{"tags":["Chat"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversationId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1,"maxLength":20000},"selectedServiceIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":20,"default":[]}},"required":["content"]}}}},"responses":{"200":{"description":"Assistant response or proposed service call.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"400":{"description":"Invalid chat request.","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":"Chat resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Chat state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Marketplace request was too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Chat request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream chat or marketplace service failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Chat is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Marketplace request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/chat/conversations/{conversationId}/tool-calls/{toolCallId}/confirm":{"post":{"tags":["Chat"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversationId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"toolCallId","in":"path"}],"responses":{"200":{"description":"Service paid and called.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"400":{"description":"Invalid chat request.","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":"Chat resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Chat state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Marketplace request was too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Chat request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream chat or marketplace service failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Chat is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Marketplace request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/chat/conversations/{conversationId}/tool-calls/{toolCallId}/cancel":{"post":{"tags":["Chat"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversationId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"toolCallId","in":"path"}],"responses":{"200":{"description":"Service call cancelled.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"400":{"description":"Invalid chat request.","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":"Chat resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Chat state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Marketplace request was too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Chat request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream chat or marketplace service failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Chat is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Marketplace request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/stocks/catalog":{"get":{"tags":["Stocks"],"summary":"List verified Robinhood Chain stock tokens and their logos","responses":{"200":{"description":"Verified stock token directory.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","enum":[0]},"message":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"source":{"type":"string","enum":["naven"]},"chainId":{"type":"number","enum":[4663]},"items":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"symbol":{"type":"string"},"name":{"type":"string"},"iconUrl":{"type":"string","format":"uri"}},"required":["address","symbol","name","iconUrl"]}}},"required":["source","chainId","items"]}},"required":["code","message","data"]}}}},"400":{"description":"Invalid symbol or query parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"401":{"description":"Invalid project API key.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"402":{"description":"x402 payment required, or project credits are insufficient. Read PAYMENT-REQUIRED for x402 calls; fund the project for API-key calls.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"404":{"description":"The stock symbol was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"502":{"description":"The upstream stock data provider failed.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"503":{"description":"Stock data is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}}}}},"/v1/stocks/quote/{symbol}":{"get":{"tags":["Stocks"],"summary":"Get a real-time stock quote","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9.-]{0,11}$","example":"AAPL"},"required":true,"name":"symbol","in":"path"}],"responses":{"200":{"description":"Latest quote and market session metrics.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","enum":[0]},"message":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"source":{"type":"string","enum":["naven"]},"symbol":{"type":"string"},"name":{"type":"string","nullable":true},"price":{"type":"number","nullable":true},"change":{"type":"number","nullable":true},"changePercent":{"type":"number","nullable":true},"volume":{"type":"number","nullable":true},"dayLow":{"type":"number","nullable":true},"dayHigh":{"type":"number","nullable":true},"yearLow":{"type":"number","nullable":true},"yearHigh":{"type":"number","nullable":true},"marketCap":{"type":"number","nullable":true},"averagePrice50Day":{"type":"number","nullable":true},"averagePrice200Day":{"type":"number","nullable":true},"exchange":{"type":"string","nullable":true},"open":{"type":"number","nullable":true},"previousClose":{"type":"number","nullable":true},"asOf":{"type":"string","nullable":true}},"required":["source","symbol","name","price","change","changePercent","volume","dayLow","dayHigh","yearLow","yearHigh","marketCap","averagePrice50Day","averagePrice200Day","exchange","open","previousClose","asOf"]}},"required":["code","message","data"]}}}},"400":{"description":"Invalid symbol or query parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"401":{"description":"Invalid project API key.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"402":{"description":"x402 payment required, or project credits are insufficient. Read PAYMENT-REQUIRED for x402 calls; fund the project for API-key calls.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"404":{"description":"The stock symbol was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"502":{"description":"The upstream stock data provider failed.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"503":{"description":"Stock data is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}}}}},"/v1/stocks/profile/{symbol}":{"get":{"tags":["Stocks"],"summary":"Get a company profile","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9.-]{0,11}$","example":"AAPL"},"required":true,"name":"symbol","in":"path"}],"responses":{"200":{"description":"Company identity and operating profile.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","enum":[0]},"message":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"source":{"type":"string","enum":["naven"]},"symbol":{"type":"string"},"companyName":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"exchange":{"type":"string","nullable":true},"industry":{"type":"string","nullable":true},"sector":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"ceo":{"type":"string","nullable":true},"website":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"imageUrl":{"type":"string","nullable":true},"marketCap":{"type":"number","nullable":true},"beta":{"type":"number","nullable":true},"priceRange":{"type":"string","nullable":true},"averageVolume":{"type":"number","nullable":true},"fullTimeEmployees":{"type":"number","nullable":true},"headquarters":{"type":"string","nullable":true},"ipoDate":{"type":"string","nullable":true},"activelyTrading":{"type":"boolean","nullable":true}},"required":["source","symbol","companyName","currency","exchange","industry","sector","country","ceo","website","description","imageUrl","marketCap","beta","priceRange","averageVolume","fullTimeEmployees","headquarters","ipoDate","activelyTrading"]}},"required":["code","message","data"]}}}},"400":{"description":"Invalid symbol or query parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"401":{"description":"Invalid project API key.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"402":{"description":"x402 payment required, or project credits are insufficient. Read PAYMENT-REQUIRED for x402 calls; fund the project for API-key calls.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"404":{"description":"The stock symbol was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"502":{"description":"The upstream stock data provider failed.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"503":{"description":"Stock data is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}}}}},"/v1/stocks/history/{symbol}":{"get":{"tags":["Stocks"],"summary":"Get daily or intraday stock price history","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9.-]{0,11}$","example":"AAPL"},"required":true,"name":"symbol","in":"path"},{"schema":{"type":"string","enum":["5m","15m","30m","1h","4h","1d"],"default":"1d","example":"5m"},"required":false,"name":"interval","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-08-01"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-09-01"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"OHLCV history. Intraday bars cover regular sessions for the verified stock-token catalog; dates are UTC bar-start timestamps. Daily dates remain YYYY-MM-DD.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","enum":[0]},"message":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"interval":{"type":"string","enum":["5m","15m","30m","1h","4h","1d"]},"timezone":{"type":"string","enum":["UTC"]},"sessionTimezone":{"type":"string","enum":["America/New_York"]},"session":{"type":"string","enum":["regular"]},"source":{"type":"string","enum":["naven"]},"symbol":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"open":{"type":"number","nullable":true},"high":{"type":"number","nullable":true},"low":{"type":"number","nullable":true},"close":{"type":"number","nullable":true},"volume":{"type":"number","nullable":true},"change":{"type":"number","nullable":true},"changePercent":{"type":"number","nullable":true},"vwap":{"type":"number","nullable":true}},"required":["date","open","high","low","close","volume","change","changePercent","vwap"]}}},"required":["source","symbol","from","to","items"]}},"required":["code","message","data"]}}}},"400":{"description":"Invalid symbol or query parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"401":{"description":"Invalid project API key.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"402":{"description":"x402 payment required, or project credits are insufficient. Read PAYMENT-REQUIRED for x402 calls; fund the project for API-key calls.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"404":{"description":"The stock symbol was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"502":{"description":"The upstream stock data provider failed.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"503":{"description":"Stock data is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}}}}},"/v1/stocks/earnings/{symbol}":{"get":{"tags":["Stocks"],"summary":"Get reported and estimated earnings","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9.-]{0,11}$","example":"AAPL"},"required":true,"name":"symbol","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Earnings events ordered by the provider.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","enum":[0]},"message":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"source":{"type":"string","enum":["naven"]},"symbol":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"epsActual":{"type":"number","nullable":true},"epsEstimate":{"type":"number","nullable":true},"epsSurprisePercent":{"type":"number","nullable":true},"revenueActual":{"type":"number","nullable":true},"revenueEstimate":{"type":"number","nullable":true},"revenueSurprisePercent":{"type":"number","nullable":true}},"required":["date","epsActual","epsEstimate","epsSurprisePercent","revenueActual","revenueEstimate","revenueSurprisePercent"]}}},"required":["source","symbol","items"]}},"required":["code","message","data"]}}}},"400":{"description":"Invalid symbol or query parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"401":{"description":"Invalid project API key.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"402":{"description":"x402 payment required, or project credits are insufficient. Read PAYMENT-REQUIRED for x402 calls; fund the project for API-key calls.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"404":{"description":"The stock symbol was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"502":{"description":"The upstream stock data provider failed.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"503":{"description":"Stock data is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}}}}},"/v1/stocks/financials/{symbol}":{"get":{"tags":["Stocks"],"summary":"Get normalized company financial statements","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9.-]{0,11}$","example":"AAPL"},"required":true,"name":"symbol","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":20,"default":8},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["quarter","annual"],"default":"quarter"},"required":false,"name":"period","in":"query"}],"responses":{"200":{"description":"Income, balance sheet, and cash flow values aligned by reporting period.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","enum":[0]},"message":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"source":{"type":"string","enum":["naven"]},"symbol":{"type":"string"},"period":{"type":"string","enum":["quarter","annual"]},"items":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"fiscalYear":{"type":"string","nullable":true},"fiscalPeriod":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"filingDate":{"type":"string","nullable":true},"acceptedDate":{"type":"string","nullable":true},"income":{"type":"object","properties":{"revenue":{"type":"number","nullable":true},"grossProfit":{"type":"number","nullable":true},"operatingIncome":{"type":"number","nullable":true},"netIncome":{"type":"number","nullable":true},"dilutedEps":{"type":"number","nullable":true}},"required":["revenue","grossProfit","operatingIncome","netIncome","dilutedEps"]},"balanceSheet":{"type":"object","properties":{"cashAndShortTermInvestments":{"type":"number","nullable":true},"totalAssets":{"type":"number","nullable":true},"totalDebt":{"type":"number","nullable":true},"totalLiabilities":{"type":"number","nullable":true},"stockholdersEquity":{"type":"number","nullable":true}},"required":["cashAndShortTermInvestments","totalAssets","totalDebt","totalLiabilities","stockholdersEquity"]},"cashFlow":{"type":"object","properties":{"operatingCashFlow":{"type":"number","nullable":true},"capitalExpenditure":{"type":"number","nullable":true},"freeCashFlow":{"type":"number","nullable":true}},"required":["operatingCashFlow","capitalExpenditure","freeCashFlow"]}},"required":["date","fiscalYear","fiscalPeriod","currency","filingDate","acceptedDate","income","balanceSheet","cashFlow"]}}},"required":["source","symbol","period","items"]}},"required":["code","message","data"]}}}},"400":{"description":"Invalid symbol or query parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"401":{"description":"Invalid project API key.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"402":{"description":"x402 payment required, or project credits are insufficient. Read PAYMENT-REQUIRED for x402 calls; fund the project for API-key calls.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"404":{"description":"The stock symbol was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"502":{"description":"The upstream stock data provider failed.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"503":{"description":"Stock data is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}}}}},"/v1/stocks/news/{symbol}":{"get":{"tags":["Stocks"],"summary":"Get recent company news","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9.-]{0,11}$","example":"AAPL"},"required":true,"name":"symbol","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Recent articles associated with the company.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","enum":[0]},"message":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"source":{"type":"string","enum":["naven"]},"symbol":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"publishedAt":{"type":"string"},"publisher":{"type":"string","nullable":true},"title":{"type":"string"},"summary":{"type":"string","nullable":true},"site":{"type":"string","nullable":true},"imageUrl":{"type":"string","nullable":true},"sourceUrl":{"type":"string"}},"required":["publishedAt","publisher","title","summary","site","imageUrl","sourceUrl"]}}},"required":["source","symbol","items"]}},"required":["code","message","data"]}}}},"400":{"description":"Invalid symbol or query parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"401":{"description":"Invalid project API key.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"402":{"description":"x402 payment required, or project credits are insufficient. Read PAYMENT-REQUIRED for x402 calls; fund the project for API-key calls.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"404":{"description":"The stock symbol was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"502":{"description":"The upstream stock data provider failed.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}},"503":{"description":"Stock data is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]}}}}}}},"/v1/perps/arcus/funding":{"get":{"tags":["Perpetual market data"],"security":[{"ProjectApiKey":[]}],"summary":"Arcus historical funding rates","description":"Hourly rates as decimals, newest first. ISO timestamps are normalized from Arcus microseconds. Page backwards using nextTo as to, keeping from fixed. Maximum window: 366 days; no inferred rates or trading execution.","parameters":[{"schema":{"type":"string","pattern":"^[A-Z0-9][A-Z0-9._-]{0,63}$"},"required":true,"name":"market","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"to","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Arcus mainnet data","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","enum":[0]},"message":{"type":"string"},"data":{"type":"object","properties":{"source":{"type":"string","enum":["naven"]},"venue":{"type":"string","enum":["arcus"]},"network":{"type":"string","enum":["mainnet"]},"market":{"type":"string","pattern":"^[A-Z0-9][A-Z0-9._-]{0,63}$"},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"ratePeriod":{"type":"string","enum":["1h"]},"order":{"type":"string","enum":["desc"]},"items":{"type":"array","items":{"type":"object","properties":{"marketId":{"type":"number"},"time":{"type":"string","format":"date-time"},"fundingRate":{"type":"string"}},"required":["marketId","time","fundingRate"]}},"nextTo":{"type":"string","nullable":true,"format":"date-time"}},"required":["source","venue","network","market","from","to","ratePeriod","order","items","nextTo"]}},"required":["code","message","data"]}}}},"400":{"description":"Invalid query"},"401":{"description":"A valid Naven project API key is required"},"503":{"description":"The data source or history store is unavailable"}}}},"/v1/perps/arcus/open-interest":{"get":{"tags":["Perpetual market data"],"security":[{"ProjectApiKey":[]}],"summary":"Sampled Arcus open-interest history","description":"OI collected once per minute, never backfilled. Coarser intervals return the last actual observation per UTC bucket; observedAt is when the value became available. Missing buckets remain absent. Maximum window: 31 days. Page forwards using nextCursor with identical from/to/interval.","parameters":[{"schema":{"type":"string","pattern":"^[A-Z0-9][A-Z0-9._-]{0,63}$"},"required":true,"name":"market","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"to","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["1m","5m","15m","1h","4h","1d"],"default":"1m"},"required":false,"name":"interval","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Arcus mainnet data","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","enum":[0]},"message":{"type":"string"},"data":{"type":"object","properties":{"source":{"type":"string","enum":["naven"]},"venue":{"type":"string","enum":["arcus"]},"network":{"type":"string","enum":["mainnet"]},"market":{"type":"string","pattern":"^[A-Z0-9][A-Z0-9._-]{0,63}$"},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"interval":{"type":"string","enum":["1m","5m","15m","1h","4h","1d"]},"order":{"type":"string","enum":["asc"]},"aggregation":{"type":"string","enum":["last_observation"]},"coverage":{"type":"object","properties":{"firstObservedAt":{"type":"string","nullable":true,"format":"date-time"},"lastObservedAt":{"type":"string","nullable":true,"format":"date-time"},"samplingIntervalSeconds":{"type":"number"},"backfilled":{"type":"boolean","enum":[false]}},"required":["firstObservedAt","lastObservedAt","samplingIntervalSeconds","backfilled"]},"items":{"type":"array","items":{"type":"object","properties":{"bucketStart":{"type":"string","format":"date-time"},"observedAt":{"type":"string","format":"date-time"},"marketId":{"type":"number"},"baseAsset":{"type":"string"},"quoteAsset":{"type":"string"},"openInterest":{"type":"string"},"markPrice":{"type":"string","nullable":true},"openInterestNotional":{"type":"string","nullable":true},"samples":{"type":"number"}},"required":["bucketStart","observedAt","marketId","baseAsset","quoteAsset","openInterest","markPrice","openInterestNotional","samples"]}},"nextCursor":{"type":"string","nullable":true,"format":"date-time"}},"required":["source","venue","network","market","from","to","interval","order","aggregation","coverage","items","nextCursor"]}},"required":["code","message","data"]}}}},"400":{"description":"Invalid query"},"401":{"description":"A valid Naven project API key is required"},"503":{"description":"The data source or history store is unavailable"}}}},"/v1/perps/arcus/status":{"get":{"tags":["Perpetual market data"],"security":[{"ProjectApiKey":[]}],"summary":"Arcus OI collection freshness","responses":{"200":{"description":"Arcus mainnet data","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","enum":[0]},"message":{"type":"string"},"data":{"type":"object","properties":{"source":{"type":"string","enum":["naven"]},"venue":{"type":"string","enum":["arcus"]},"network":{"type":"string","enum":["mainnet"]},"status":{"type":"string","enum":["not_started","fresh","stale"]},"samplingIntervalSeconds":{"type":"number"},"lastObservedAt":{"type":"string","nullable":true,"format":"date-time"},"marketCount":{"type":"number"},"skippedMarkets":{"type":"number"}},"required":["source","venue","network","status","samplingIntervalSeconds","lastObservedAt","marketCount","skippedMarkets"]}},"required":["code","message","data"]}}}},"400":{"description":"Invalid query"},"401":{"description":"A valid Naven project API key is required"},"503":{"description":"The data source or history store is unavailable"}}}},"/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"}}}}}}}}}