{"openapi":"3.0.0","paths":{"/api/v1/organizations/{orgId}/llms.txt":{"get":{"description":"Returns the agent-discoverable llms.txt index listing the organization's payment plans, agents, and Nevermined reference links, rendered as plain text. Only active Premium/Enterprise organizations are served; any other org (Lapsed or non-existent) returns 404 without leaking the reason. Public endpoint — no authentication required.","operationId":"OrganizationsIntegrationController_llmsTxt","parameters":[{"name":"orgId","required":true,"in":"path","description":"Organization identifier","schema":{"example":"org-abc123","type":"string"}}],"responses":{"200":{"description":"llms.txt content rendered as plain text","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Organization not found or not on a paid tier"}},"summary":"Public llms.txt index for an organization","tags":["Organizations - Integration"]}},"/api/v1/organizations/{orgId}/agentic-instructions.md":{"get":{"description":"Returns a markdown document instructing autonomous AI agents how to discover and pay for the organization's plans and agents via Nevermined. Only active Premium/Enterprise organizations are served; any other org (Lapsed or non-existent) returns 404 without leaking the reason. Public endpoint — no authentication required.","operationId":"OrganizationsIntegrationController_agenticInstructionsMd","parameters":[{"name":"orgId","required":true,"in":"path","description":"Organization identifier","schema":{"example":"org-abc123","type":"string"}}],"responses":{"200":{"description":"agentic-instructions.md content rendered as markdown","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Organization not found or not on a paid tier"}},"summary":"Public agentic instructions for an organization","tags":["Organizations - Integration"]}},"/api/v1/delegation/create":{"post":{"description":"Creates a spending delegation for the authenticated user against a previously enrolled payment method. For fiat-backed delegations (stripe/braintree/visa) the response includes a signed JWT (`delegationToken`); for crypto (erc4337) flows the token is held client-side and omitted. Requires a Nevermined API key.","operationId":"DelegationController_createDelegation","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDelegationDto"}}}},"responses":{"201":{"description":"The created delegation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDelegationResponseDto"}}}},"401":{"description":"Unauthorized"}},"security":[{"Authorization":[]}],"summary":"Create a spending delegation and return a signed JWT token","tags":["Delegation"]}},"/api/v1/delegation":{"get":{"description":"Returns a paginated list of the authenticated user's spending delegations. Use `accessible=true` to return only delegations the requesting API key may spend against. Requires a Nevermined API key.","operationId":"DelegationController_listDelegations","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based). Defaults to 1.","schema":{"type":"integer","default":1}},{"name":"offset","required":false,"in":"query","description":"Number of items per page. Defaults to 10.","schema":{"type":"integer","default":10}},{"name":"accessible","required":false,"in":"query","description":"When \"true\", return only delegations accessible to the requesting API key (filters by apiKeyId, Active status, expiry, and remaining budget)","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegationListDto"}}}}},"security":[{"Authorization":[]}],"summary":"List all delegations for the authenticated user","tags":["Delegation"]}},"/api/v1/delegation/{delegationId}":{"get":{"description":"Returns the full details of a single delegation owned by the authenticated user, including remaining budget and last-used timestamp. Requires a Nevermined API key.","operationId":"DelegationController_getDelegation","parameters":[{"name":"delegationId","required":true,"in":"path","description":"UUID v4 of the delegation to fetch.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegationDetailsDto"}}}},"404":{"description":"Delegation not found"}},"security":[{"Authorization":[]}],"summary":"Get delegation details including remaining budget","tags":["Delegation"]},"delete":{"description":"Revokes a delegation owned by the authenticated user and cascade-revokes its linked permissions. For Visa delegations the linked VGS intent is cancelled best-effort. Requires a Nevermined API key.","operationId":"DelegationController_revokeDelegation","parameters":[{"name":"delegationId","required":true,"in":"path","description":"UUID v4 of the delegation to revoke.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The revoke result (`{ success: true }`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/_NvmAPIResultDto"}}}},"404":{"description":"Delegation not found"}},"security":[{"Authorization":[]}],"summary":"Revoke a delegation","tags":["Delegation"]}},"/api/v1/delegation/{delegationId}/transactions":{"get":{"description":"Returns a paginated list of charge transactions recorded against a delegation owned by the authenticated user. Requires a Nevermined API key.","operationId":"DelegationController_getTransactions","parameters":[{"name":"delegationId","required":true,"in":"path","description":"UUID v4 of the delegation whose transactions are listed.","schema":{"type":"string","format":"uuid"}},{"name":"page","required":false,"in":"query","description":"Page number (1-based). Defaults to 1.","schema":{"type":"integer","default":1}},{"name":"offset","required":false,"in":"query","description":"Number of items per page. Defaults to 10.","schema":{"type":"integer","default":10}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegationTransactionListDto"}}}},"404":{"description":"Delegation not found"}},"security":[{"Authorization":[]}],"summary":"List transactions for a delegation","tags":["Delegation"]}},"/":{"get":{"description":"Returns API metadata: version, contract addresses, network configuration, and related service URLs. Public endpoint — no authentication required.","operationId":"InfoController_getInfo","parameters":[],"responses":{"200":{"description":"Return API Info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetInfoDto"}}}}},"summary":"Get API info","tags":["Info"]}},"/health":{"get":{"description":"Liveness probe that returns `{ status: \"ok\" }` when the API is up. Public endpoint — no authentication required.","operationId":"InfoController_health","parameters":[],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"}}}}}}},"summary":"Health check","tags":["Info"]}},"/api/v1/protocol/plans/{planId}":{"get":{"description":"Retrieve complete payment plan details including metadata, pricing configuration, credits configuration, and associated agents. Public endpoint — no authentication required.","operationId":"ProtocolController_getPlan","parameters":[{"name":"planId","required":true,"in":"path","description":"Unique identifier of the payment plan (BigInt as string)","schema":{"format":"int64","example":"43298432984329","type":"integer"}}],"responses":{"200":{"description":"Payment plan details retrieved successfully","content":{"application/json":{"schema":{"example":{"planId":"43298432984329","metadata":{"main":{"name":"Premium AI Access","description":"Pay-as-you-go AI agent access","author":"Nevermined AI Inc.","tags":["AI","Premium","Credits"]},"plan":{"isTrialPlan":false,"recurringSubscription":false,"accessLimit":"credits"}},"registry":{"price":{"isCrypto":true,"amounts":["1000000000000000000"],"receivers":["0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"],"tokenAddress":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","templateAddress":"0x0000000000000000000000000000000000000000"},"credits":{"isRedemptionAmountFixed":true,"redemptionType":2,"amount":"1000","minAmount":"1","maxAmount":"1"}},"owner":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"}}}}},"400":{"description":"Bad Request - Invalid planId (must be a uint256)","content":{"application/json":{"schema":{"example":{"code":"BCK.COMMON.0026","httpStatus":400,"message":"Invalid uint256 identifier (must be a decimal in [0, 2^256 - 1])"}}}}},"404":{"description":"Not found - Plan does not exist","content":{"application/json":{"schema":{"example":{"code":"BCK.PROTOCOL.0003","httpStatus":404,"message":"Unable to get payment plan by planId","params":{"planId":"43298432984329"}}}}}}},"summary":"Get payment plan details","tags":["Protocol"]},"put":{"description":"Update the payment plan's metadata. Requires a Nevermined API key.","operationId":"ProtocolController_updatePlan","parameters":[{"name":"planId","required":true,"in":"path","description":"the unique identifier of the plan","schema":{"format":"int64","type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataMainAttributesPlanDto"}}}},"responses":{"201":{"description":"Result of the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/_NvmAPIResultDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"}},"security":[{"Authorization":[]}],"summary":"Update a payment plan's metadata","tags":["Protocol"]}},"/api/v1/protocol/agents/{agentId}":{"get":{"description":"Retrieve complete AI agent details including metadata, API endpoints, authentication configuration, and associated payment plans. Public endpoint — no authentication required.","operationId":"ProtocolController_getAgent","parameters":[{"name":"agentId","required":true,"in":"path","description":"Unique identifier (DID) of the agent","schema":{"example":"112715147946069636715282379221777166315490656636137176534659157141164168807749","type":"string"}}],"responses":{"200":{"description":"Agent details retrieved successfully","content":{"application/json":{"schema":{"example":{"data":{"agentId":"112715147946069636715282379221777166315490656636137176534659157141164168807749"},"metadata":{"main":{"name":"Data Analysis Agent","description":"AI agent specialized in data analysis","author":"Nevermined AI","tags":["AI","Data Analysis"]},"agent":{"endpoints":[{"POST":"https://myagent.ai/api/v1/agents/(.*)/tasks"},{"GET":"https://myagent.ai/api/v1/agents/(.*)/status"}],"openEndpoints":["https://myagent.ai/docs"],"agentDefinitionUrl":"https://myagent.ai/openapi.json","authentication":{"type":"bearer","encrypted":true}}},"registry":{"plans":["43298432984329","12345678901234"]}}}}}},"400":{"description":"Bad Request - Invalid agentId (must be a uint256)","content":{"application/json":{"schema":{"example":{"code":"BCK.COMMON.0026","httpStatus":400,"message":"Invalid uint256 identifier (must be a decimal in [0, 2^256 - 1])"}}}}},"404":{"description":"Not found - Agent does not exist","content":{"application/json":{"schema":{"example":{"code":"BCK.PROTOCOL.0004","httpStatus":404,"message":"Unable to get agent by agentId","params":{"agentId":"112715147946069636715282379221777166315490656636137176534659157141164168807749"}}}}}}},"summary":"Get AI agent details","tags":["Protocol"]},"put":{"description":"Update the AI agent's metadata. Requires a Nevermined API key.","operationId":"ProtocolController_updateAgent","parameters":[{"name":"agentId","required":true,"in":"path","description":"the unique identifier of the agent","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentDto"}}}},"responses":{"201":{"description":"Result of the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/_NvmAPIResultDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"}},"security":[{"Authorization":[]}],"summary":"Update an AI agent's metadata","tags":["Protocol"]}},"/api/v1/protocol/plans/{planId}/balance/{holderAddress}":{"get":{"description":"Retrieve the credit balance for a specific user on a payment plan, including plan details, subscription status, and price per credit. Public endpoint — no authentication required.","operationId":"ProtocolController_getPlanBalance","parameters":[{"name":"planId","required":true,"in":"path","description":"Unique identifier of the payment plan (BigInt as string)","schema":{"format":"int64","example":"43298432984329","type":"integer"}},{"name":"holderAddress","required":true,"in":"path","description":"Ethereum address of the user holding the credits (checksummed, 0x-prefixed)","schema":{"example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","type":"string"}}],"responses":{"200":{"description":"Plan balance retrieved successfully","content":{"application/json":{"schema":{"example":{"planId":"43298432984329","planName":"Premium AI Access","planType":"credits","isSubscriber":true,"holderAddress":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","creditsContract":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","balance":"950","pricePerCredit":0.01}}}}},"400":{"description":"Bad Request - Invalid planId (must be a uint256) or holderAddress format","content":{"application/json":{"schema":{"example":{"code":"BCK.COMMON.0026","httpStatus":400,"message":"Invalid uint256 identifier (must be a decimal in [0, 2^256 - 1])"}}}}},"404":{"description":"Not found - Plan does not exist","content":{"application/json":{"schema":{"example":{"code":"BCK.PROTOCOL.0006","httpStatus":500,"message":"Error getting balance of plan","params":{"planId":"43298432984329","holderAddress":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"}}}}}}},"summary":"Get a user's credit balance for a plan","tags":["Protocol"]}},"/api/v1/protocol/plans":{"post":{"description":"Register a new payment plan on the blockchain and store its metadata. Requires a Nevermined API key.","operationId":"ProtocolController_registerPaymentPlan","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterPaymentPlanDto"},"examples":{"creditsPlan":{"summary":"Credits-based payment plan","description":"Example of a standard credits-based plan with fixed redemption","value":{"metadataAttributes":{"name":"Premium AI Access","description":"Pay-as-you-go AI agent access with credits","author":"Nevermined AI Inc.","tags":["AI","Premium","Credits"]},"priceConfig":{"isCrypto":true,"amounts":["1000000000000000000"],"receivers":["0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"],"tokenAddress":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","externalPriceAddress":"0x0000000000000000000000000000000000000000","templateAddress":"0x0000000000000000000000000000000000000000"},"creditsConfig":{"isRedemptionAmountFixed":true,"redemptionType":2,"onchainMirror":false,"amount":"1000","minAmount":"1","maxAmount":"1","durationSecs":"0"},"accessLimit":"credits"}}}}}},"responses":{"201":{"description":"Payment plan successfully created","content":{"application/json":{"schema":{"type":"object","properties":{"planId":{"type":"string","example":"43298432984329","description":"Unique identifier of the created payment plan (BigInt as string)"},"metadata":{"type":"object","description":"Plan metadata including name, description, and configuration"}}}}}},"400":{"description":"Bad Request - Invalid input data","content":{"application/json":{"schema":{"example":{"code":"BCK.PROTOCOL.0001","httpStatus":400,"message":"Unable to register payment plan","params":{"error":"Invalid priceConfig: amounts array cannot be empty"}}}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"example":{"code":"BCK.APIKEY.0004","httpStatus":401,"message":"Invalid Nevermined API Key"}}}}},"403":{"description":"Forbidden - API key does not have permission to register plans","content":{"application/json":{"schema":{"example":{"code":"BCK.APIKEY.0001","httpStatus":403,"message":"API Key not registered, you need to register it first"}}}}}},"security":[{"Authorization":[]}],"summary":"Register a payment plan","tags":["Protocol"]},"get":{"description":"Get paginated payment plans for the current user. Supports pagination and sorting by any indexed field. Requires a Nevermined API key or a Privy identity token.","operationId":"ProtocolController_getUserPlans","parameters":[{"name":"sortBy","required":false,"in":"query","description":"Sorting criteria by field","schema":{"example":"created","type":"string"}},{"name":"sortOrder","required":false,"in":"query","description":"Sorting order (asc or desc)","schema":{"example":"desc","type":"string"}},{"name":"orgId","required":false,"in":"query","description":"When set, returns every plan in this org (any creator). Requires active membership. When omitted, returns every plan authored by the caller across any context.","schema":{"example":"org-acme","type":"string"}},{"name":"offset","required":false,"in":"query","description":"Number of items per page (default: 10)","schema":{"example":10,"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number to retrieve (default: 1)","schema":{"example":1,"type":"number"}}],"responses":{"200":{"description":"Paginated payment plans","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedPaymentPlansDto"}}}}},"security":[{"Authorization":[]}],"summary":"List the current user's payment plans","tags":["Protocol"]}},"/api/v1/protocol/agents/plans":{"post":{"description":"Register a new AI agent and its associated payment plan in a single transaction. Requires a Nevermined API key.","operationId":"ProtocolController_registerAgentAndPlan","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterAgentAndPlanDto"},"examples":{"agentWithPlan":{"summary":"Agent with payment plan","description":"Create an AI agent and its associated payment plan in a single operation","value":{"plan":{"metadataAttributes":{"name":"Agent Access Plan","description":"Payment plan for accessing the AI agent"},"priceConfig":{"isCrypto":true,"amounts":["1000000000000000000"],"receivers":["0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"],"tokenAddress":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","externalPriceAddress":"0x0000000000000000000000000000000000000000","templateAddress":"0x0000000000000000000000000000000000000000"},"creditsConfig":{"isRedemptionAmountFixed":true,"redemptionType":2,"onchainMirror":false,"amount":"1000","minAmount":"1","maxAmount":"1","durationSecs":"0"},"accessLimit":"credits"},"agent":{"metadataAttributes":{"name":"My AI Agent","description":"AI agent for automated tasks"},"agentApiAttributes":{"endpoints":[{"POST":"https://myagent.ai/api/v1/agents/(.*)/tasks"},{"GET":"https://myagent.ai/api/v1/agents/(.*)/status"}],"openEndpoints":["https://myagent.ai/docs"],"agentDefinitionUrl":"https://myagent.ai/openapi.json","authType":"bearer","token":"my-secret-token"}}}}}}}},"responses":{"201":{"description":"Agent and plan successfully created","content":{"application/json":{"schema":{"example":{"success":true,"data":{"agentId":"112715147946069636715282379221777166315490656636137176534659157141164168807749","planId":"43298432984329"}}}}}},"400":{"description":"Bad Request - Invalid input data","content":{"application/json":{"schema":{"example":{"code":"BCK.PROTOCOL.0040","httpStatus":400,"message":"Unable to register agent and plan","params":{"error":"Invalid agent endpoint configuration"}}}}}},"401":{"description":"Unauthorized - Invalid or missing API key"},"403":{"description":"Forbidden - API key does not have permission"}},"security":[{"Authorization":[]}],"summary":"Register an AI agent with a payment plan","tags":["Protocol"]}},"/api/v1/protocol/agents":{"post":{"description":"Register a new AI agent with its API endpoints, authentication, and associated payment plans. Requires a Nevermined API key.","operationId":"ProtocolController_registerAgent","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterAgentDto"},"examples":{"basicAgent":{"summary":"AI Agent with bearer authentication","description":"Register an AI agent with API endpoints and bearer token authentication","value":{"metadataAttributes":{"name":"Data Analysis Agent","description":"AI agent specialized in data analysis and visualization","author":"Nevermined AI","tags":["AI","Data Analysis","Automation"]},"agentApiAttributes":{"endpoints":[{"POST":"https://myagent.ai/api/v1/agents/(.*)/analyze"},{"GET":"https://myagent.ai/api/v1/agents/(.*)/results"}],"openEndpoints":["https://myagent.ai/docs","https://myagent.ai/health"],"agentDefinitionUrl":"https://myagent.ai/openapi.json","authType":"bearer","token":"your-secret-bearer-token"},"plans":["43298432984329"]}}}}}},"responses":{"201":{"description":"Agent successfully created","content":{"application/json":{"schema":{"example":{"success":true,"message":"Agent created","txHash":"0xabc123...","httpStatus":201,"data":{"agentId":"112715147946069636715282379221777166315490656636137176534659157141164168807749"}}}}}},"400":{"description":"Bad Request - Invalid input data","content":{"application/json":{"schema":{"example":{"code":"BCK.PROTOCOL.0002","httpStatus":400,"message":"Unable to register agent","params":{"error":"Invalid endpoint configuration"}}}}}},"401":{"description":"Unauthorized - Invalid or missing API key"},"403":{"description":"Forbidden - API key does not have permission to register agents"}},"security":[{"Authorization":[]}],"summary":"Register an AI agent","tags":["Protocol"]},"get":{"description":"Get paginated agents for the current user. Supports pagination and sorting by any indexed field. Requires a Nevermined API key or a Privy identity token.","operationId":"ProtocolController_getUserAgents","parameters":[{"name":"sortBy","required":false,"in":"query","description":"Sorting criteria by field","schema":{"example":"created","type":"string"}},{"name":"sortOrder","required":false,"in":"query","description":"Sorting order (asc or desc)","schema":{"example":"desc","type":"string"}},{"name":"orgId","required":false,"in":"query","description":"When set, returns every agent in this org (any creator). Requires active membership. When omitted, returns every agent authored by the caller across any context.","schema":{"example":"org-acme","type":"string"}},{"name":"offset","required":false,"in":"query","description":"Number of items per page (default: 10)","schema":{"example":10,"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number to retrieve (default: 1)","schema":{"example":1,"type":"number"}}],"responses":{"200":{"description":"Paginated agents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedAgentsDto"}}}}},"security":[{"Authorization":[]}],"summary":"List the current user's AI agents","tags":["Protocol"]}},"/api/v1/protocol/plans/{planId}/order":{"post":{"description":"Settles a payment plan whose price is denominated in a stablecoin (crypto). The caller pays from the on-chain account derived from the Nevermined API Key and receives the plan credits in the same wallet.\n\n**Fiat (USD / EUR) plans are NOT orderable through this endpoint.** Fiat plans use the x402 card-delegation flow — register a card delegation (`POST /api/v1/x402/permissions` to create one, `POST /api/v1/x402/verify` to validate, `POST /api/v1/x402/settle` to settle) so the Stripe charge runs before credits are minted. Calling this endpoint for a fiat plan returns 400 `BCK.PROTOCOL.0050` pointing back to that flow.\n\nSee https://nevermined.ai/docs/specs/x402-card-delegation for the card-delegation specification.","operationId":"ProtocolController_order","parameters":[{"name":"planId","required":true,"in":"path","description":"Unique identifier of the payment plan (BigInt as string)","schema":{"format":"int64","example":"43298432984329","type":"integer"}}],"responses":{"201":{"description":"Plan ordered successfully. Returns the on-chain transaction hash and success flag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/_NvmAPIResultDto"}}}},"400":{"description":"Bad Request — common causes: `BCK.PROTOCOL.0050` (the plan is fiat and must be purchased via the x402 settle flow), invalid planId format."},"401":{"description":"Unauthorized — the Nevermined API Key is missing or invalid."},"402":{"description":"Payment Required (`BCK.PROTOCOL.0011`) — the buyer wallet has insufficient stablecoin balance to cover the plan price."},"403":{"description":"Forbidden — the API key is not authorised to order on behalf of this account."}},"security":[{"Authorization":[]}],"summary":"Order (purchase) a stablecoin-priced payment plan","tags":["Protocol"]}},"/api/v1/protocol/plans/mint":{"post":{"description":"Mint (add) credits to a payment plan for a specific user. Only the plan owner can mint credits. Requires a Nevermined API key.","operationId":"ProtocolController_mintCredits","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MintPlanDto"},"examples":{"mintCredits":{"summary":"Mint 150 credits","description":"Add 150 credits to the payment plan for the specified user address","value":{"planId":"43298432984329","creditsReceiver":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","amount":"150"}}}}}},"responses":{"201":{"description":"Credits successfully minted","content":{"application/json":{"schema":{"example":{"success":true,"message":"Credits minted successfully","txHash":"0xdef456...","httpStatus":201}}}}},"400":{"description":"Bad Request - Invalid plan ID or amount","content":{"application/json":{"schema":{"example":{"code":"BCK.PROTOCOL.0007","httpStatus":400,"message":"Error minting plan","params":{"planId":"43298432984329","amount":"150"}}}}}},"401":{"description":"Unauthorized - Invalid or missing API key"},"403":{"description":"Forbidden - Only the plan owner can mint credits","content":{"application/json":{"schema":{"example":{"code":"BCK.PROTOCOL.0017","httpStatus":401,"message":"The user doesnt own this plan"}}}}}},"security":[{"Authorization":[]}],"summary":"Mint credits to a plan holder","tags":["Protocol"]}},"/api/v1/protocol/plans/mintExpirable":{"post":{"description":"Mint time-limited (expirable) credits to a payment plan for a specific user; the credits expire after the configured duration. Only the plan owner can mint credits. Requires a Nevermined API key.","operationId":"ProtocolController_mintCreditsExpirable","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MintPlanExpirableDto"}}}},"responses":{"201":{"description":"Result of the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/_NvmAPIResultDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"Mint expirable credits to a plan holder","tags":["Protocol"]}},"/api/v1/protocol/agents/{agentId}/plan/{planId}":{"delete":{"description":"Remove a payment plan from an agent. Requires a Nevermined API key.","operationId":"ProtocolController_removePlanFromAgent","parameters":[{"name":"agentId","required":true,"in":"path","description":"the unique identifier of the agent","schema":{"type":"string"}},{"name":"planId","required":true,"in":"path","description":"the unique identifier of the payment plan","schema":{"format":"int64","type":"integer"}}],"responses":{"201":{"description":"Result of the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/_NvmAPIResultDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"}},"security":[{"Authorization":[]}],"summary":"Remove a payment plan from an agent","tags":["Protocol"]},"post":{"description":"Adds a payment plan to an agent. Requires a Nevermined API key.","operationId":"ProtocolController_addPlanToAgent","parameters":[{"name":"agentId","required":true,"in":"path","description":"the unique identifier of the agent","schema":{"type":"string"}},{"name":"planId","required":true,"in":"path","description":"the unique identifier of the payment plan","schema":{"format":"int64","type":"integer"}}],"responses":{"201":{"description":"Result of the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/_NvmAPIResultDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"}},"security":[{"Authorization":[]}],"summary":"Add a payment plan to an agent","tags":["Protocol"]}},"/api/v1/protocol/agents/{agentId}/list/{activate}":{"put":{"description":"Toggle an agent's on-chain listing status: set `activate` to true to publish (list) the agent, false to unpublish (unlist). Requires a Nevermined API key.","operationId":"ProtocolController_manageAgentActivationStatus","parameters":[{"name":"agentId","required":true,"in":"path","description":"the unique identifier of the agent","schema":{"type":"string"}},{"name":"activate","required":true,"in":"path","schema":{"type":"boolean"}}],"responses":{"201":{"description":"Result of the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/_NvmAPIResultDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"}},"security":[{"Authorization":[]}],"summary":"Publish or unpublish an AI agent","tags":["Protocol"]}},"/api/v1/protocol/plans/{planId}/list/{activate}":{"put":{"description":"Toggle a plan's on-chain listing status: set `activate` to true to publish (list) the plan, false to unpublish (unlist). Requires a Nevermined API key.","operationId":"ProtocolController_managePlanActivationStatus","parameters":[{"name":"planId","required":true,"in":"path","description":"the unique identifier of the plan","schema":{"format":"int64","type":"integer"}},{"name":"activate","required":true,"in":"path","schema":{"type":"boolean"}}],"responses":{"201":{"description":"Result of the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/_NvmAPIResultDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"}},"security":[{"Authorization":[]}],"summary":"Publish or unpublish a payment plan","tags":["Protocol"]}},"/api/v1/protocol/all-plans":{"get":{"description":"Get all paginated payment plans. Supports pagination, sorting, and filtering by plan name (prefix match). Requires a Nevermined API key or a Privy identity token.","operationId":"ProtocolController_getAllPlans","parameters":[{"name":"sortBy","required":false,"in":"query","description":"Sorting criteria by field","schema":{"example":"created","type":"string"}},{"name":"sortOrder","required":false,"in":"query","description":"Sorting order (asc or desc)","schema":{"example":"desc","type":"string"}},{"name":"name","required":false,"in":"query","description":"Filter by plan name or plan ID (substring match, case-insensitive for names)","schema":{"example":"Premium","type":"string"}},{"name":"offset","required":false,"in":"query","description":"Number of items per page (default: 10)","schema":{"example":10,"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number to retrieve (default: 1)","schema":{"example":1,"type":"number"}}],"responses":{"200":{"description":"Paginated payment plans","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedPaymentPlansDto"}}}}},"security":[{"Authorization":[]}],"summary":"List all payment plans","tags":["Protocol"]}},"/api/v1/protocol/agents/{agentId}/plans":{"get":{"description":"Get paginated payment plans associated with an agent. Public endpoint — no authentication required.","operationId":"ProtocolController_getPaymentPlansAssociatedToAgent","parameters":[{"name":"agentId","required":true,"in":"path","description":"The ID of the agent","schema":{"type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Sorting criteria by field","schema":{"example":"created","type":"string"}},{"name":"sortOrder","required":false,"in":"query","description":"Sorting order (asc or desc)","schema":{"example":"desc","type":"string"}},{"name":"offset","required":false,"in":"query","description":"Number of items per page (default: 10)","schema":{"example":10,"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number to retrieve (default: 1)","schema":{"example":1,"type":"number"}}],"responses":{"200":{"description":""}},"summary":"List payment plans for an agent","tags":["Protocol"]}},"/api/v1/protocol/plans/{planId}/agents":{"get":{"description":"Get paginated agents associated with a payment plan. Public endpoint — no authentication required.","operationId":"ProtocolController_getAgentsAssociatedToPlan","parameters":[{"name":"planId","required":true,"in":"path","description":"The ID of the plan","schema":{"format":"int64","type":"integer"}},{"name":"sortBy","required":false,"in":"query","description":"Sorting criteria by field","schema":{"example":"created","type":"string"}},{"name":"sortOrder","required":false,"in":"query","description":"Sorting order (asc or desc)","schema":{"example":"desc","type":"string"}},{"name":"offset","required":false,"in":"query","description":"Number of items per page (default: 10)","schema":{"example":10,"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number to retrieve (default: 1)","schema":{"example":1,"type":"number"}}],"responses":{"200":{"description":""}},"summary":"List agents for a payment plan","tags":["Protocol"]}},"/api/v1/protocol/agent-sub-tasks":{"post":{"description":"Track an agent sub-task. Requires a Nevermined API key.","operationId":"ProtocolController_trackAgentSubTask","parameters":[],"requestBody":{"required":true,"description":"Agent sub task data to track","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackAgentSubTaskDto"}}}},"responses":{"201":{"description":"Agent sub task tracked successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/_NvmAPIResultDto"}}}},"400":{"description":"Bad Request - Invalid input data"},"401":{"description":"Unauthorized - Invalid API key"},"403":{"description":"Forbidden - You do not have permission to track agent sub tasks for this agent task"},"404":{"description":"Not Found - Agent task not found"},"500":{"description":"Internal Server Error"}},"security":[{"Authorization":[]}],"summary":"Track an agent sub-task","tags":["Protocol"]}},"/api/v1/protocol/agents/simulate/start":{"post":{"description":"Simulate an agent request without executing it (used to validate/estimate credit usage). Requires a Nevermined API key.","operationId":"ProtocolController_simulateAgentRequest","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitializeAgentRequestDto"}}}},"responses":{"201":{"description":"Payment plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitializeAgentRequestResponseDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"Simulate the start of an agent request","tags":["Protocol"]}},"/api/v1/protocol/agents/simulate/finish":{"post":{"description":"Simulate the redemption of credits for an agent request. Requires a Nevermined API key.","operationId":"ProtocolController_simulateRedeemCredits","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedeemSimulationCreditsDto"}}}},"responses":{"201":{"description":"Result of the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/_NvmAPIResultDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"Simulate redeeming credits for an agent request","tags":["Protocol"]}},"/oauth/token":{"post":{"description":"OAuth 2.1 token endpoint. Validates the authorization code and PKCE `code_verifier`, then returns an access token (JWT) in the OAuth standard format. The single-use, time-limited code already carries the user identity, so no user authentication is required. Public endpoint — no authentication required.","operationId":"OAuthController_token","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequestDto"}}}},"responses":{"200":{"description":"Access token response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponseDto"}}}},"400":{"description":"Bad Request - Invalid code, PKCE validation failed, or other errors"}},"summary":"Exchange authorization code for access token","tags":["OAuth"]}},"/api/v1/x402/permissions":{"post":{"description":"Creates a permission and generates an x402 access token for a payment plan. Requires a Nevermined API key.","operationId":"X402Controller_createPermission","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateX402TokenDto"},"examples":{"basicPermission":{"summary":"Basic crypto permission (nvm:erc4337)","description":"Create a permission with minimal x402 PaymentPayload structure","value":{"accepted":{"scheme":"nvm:erc4337","network":"eip155:84532","planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071"}}},"permissionWithAgent":{"summary":"Crypto permission with agent and endpoint","description":"Create a permission with agentId, endpoint, and httpVerb for validation","value":{"resource":{"url":"https://myagent.ai/api/v1/tasks","description":"AI agent task execution"},"accepted":{"scheme":"nvm:erc4337","network":"eip155:84532","planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071","extra":{"agentId":"80918427023170428029540261117198154464497879145267720259488529685089104529015","httpVerb":"POST"}}}},"cryptoDelegation":{"summary":"Crypto delegation permission (nvm:erc4337)","description":"Create a delegation-based permission for crypto settlement with auto-created delegation","value":{"resource":{"url":"https://myagent.ai/api/v1/tasks"},"accepted":{"scheme":"nvm:erc4337","network":"eip155:84532","planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071","extra":{"version":"1","agentId":"80918427023170428029540261117198154464497879145267720259488529685089104529015","httpVerb":"POST"}},"delegationConfig":{"spendingLimitCents":10000,"durationSecs":3600,"currency":"usdc"}}},"cardDelegation":{"summary":"Card delegation permission (nvm:card-delegation)","description":"Create a delegation-based permission using a Stripe payment method for fiat settlement","value":{"accepted":{"scheme":"nvm:card-delegation","network":"stripe","planId":"delegation"},"delegationConfig":{"providerPaymentMethodId":"pm_1Abc2Def3Ghi4Jkl","spendingLimitCents":10000,"durationSecs":604800,"currency":"usd"}}},"cardDelegationWithMerchant":{"summary":"Card delegation with merchant routing","description":"Create a delegation-based permission with Stripe Connect merchant account routing","value":{"accepted":{"scheme":"nvm:card-delegation","network":"stripe","planId":"delegation"},"delegationConfig":{"providerPaymentMethodId":"pm_1Abc2Def3Ghi4Jkl","spendingLimitCents":50000,"durationSecs":2592000,"currency":"usd","merchantAccountId":"acct_1ReAt6BTy5gR9Yy6","maxTransactions":100}}}}}}},"responses":{"201":{"description":"Permission successfully created and X402 access token generated","schema":{"example":{"accessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwbGFuSWQiOiI0MzI5ODQzMjk4NDMyOSIsImFnZW50SWQiOiIxMjM0NTY3ODkwMTIzNDU2Nzg5MCIsInN1YnNjcmliZXJBZGRyZXNzIjoiMHhmMzlGZDZlNTFhYWQ4OEY2RjRjZTZhQjg4MjcyNzljZmZGYjkyMjY2IiwiaWF0IjoxNzM2NjAwMDAwLCJleHAiOjE3Mzc4MDk2MDB9.x402_signature_hash"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentX402AccessTokenDto"}}}},"400":{"description":"Bad Request - Invalid input data","content":{"application/json":{"schema":{"example":{"code":"BCK.X402.0001","httpStatus":400,"message":"Unable to generate X402 Access Token","params":{"error":"Invalid planId or agentId"}}}}}},"404":{"description":"Not Found - Plan or agent does not exist","content":{"application/json":{"schema":{"example":{"code":"BCK.X402.0002","httpStatus":404,"message":"Plan not found","params":{"planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071"}}}}}}},"security":[{"Authorization":[]}],"summary":"Create permission","tags":["X402"]},"get":{"description":"Returns a paginated list of permissions for the authenticated user, optionally filtered by scheme. Requires a Nevermined API key.","operationId":"X402Controller_getPermissions","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"example":1,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Number of results per page (default: 10)","schema":{"example":10,"type":"number"}},{"name":"scheme","required":false,"in":"query","description":"Filter by scheme (nvm:erc4337 or nvm:card-delegation)","schema":{"enum":["nvm:erc4337","nvm:card-delegation"],"type":"string"}}],"responses":{"200":{"description":"Paginated list of permissions retrieved successfully","schema":{"example":{"totalResults":137,"page":1,"offset":20,"permissions":[{"permissionHash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071","planName":"Premium AI Access","redemptionLimit":10,"createdAt":"2025-01-10T12:00:00Z","status":"Active"},{"permissionHash":"0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890","planId":"79102475636047497640080230236781474129970992727896593861997347135613135571085","planName":"Basic API Access","redemptionLimit":null,"createdAt":"2025-01-05T08:30:00Z","status":"Active"}]}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionListDto"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"example":{"code":"BCK.APIKEY.0004","httpStatus":401,"message":"Invalid API key"}}}}}},"security":[{"Authorization":[]}],"summary":"List permissions","tags":["X402"]}},"/api/v1/x402/verify":{"post":{"description":"Verifies delegated permissions for a plan using an existing session key. Authentication via NVM API hash key is currently optional (#1570 deprecation window) and will be required in a future release — callers should start sending the header now.","operationId":"X402Controller_verifyPermissions","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlePermissionsDto"},"examples":{"verifyBasic":{"summary":"Basic verification","description":"Verify permissions with minimal required fields. The facilitator validates that the accepted payment method in the token matches one of the accepts.","value":{"paymentRequired":{"x402Version":2,"error":"Payment required to access resource","resource":{"url":"https://myagent.ai/api/v1/tasks","description":"AI agent task execution"},"accepts":[{"scheme":"nvm:erc4337","network":"eip155:84532","planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071","extra":{"agentId":"80918427023170428029540261117198154464497879145267720259488529685089104529015"}}],"extensions":{}},"x402AccessToken":"eyJ4NDAyVmVyc2lvbiI6MiwicmVzb3VyY2UiOnsidXJsIjoiaHR0cHM6Ly9teWFnZW50LmFpL2FwaS92MS90YXNrcyJ9LCJhY2NlcHRlZCI6eyJzY2hlbWUiOiJudm06ZXJjNDMzNyIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MzIiLCJwbGFuSWQiOiI0NDc0Mjc2MzA3NjA0NzQ5NzY0MDA4MDIzMDIzNjc4MTQ3NDEyOTk3MDk5MjcyNzg5NjU5Mzg2MTk5NzM0NzEzNTYxMzEzNTU3MTA3MSIsImV4dHJhIjp7InZlcnNpb24iOiIxIiwiYWdlbnRJZCI6IjgwOTE4NDI3MDIzMTcwNDI4MDI5NTQwMjYxMTE3MTk4MTU0NDY0NDk3ODc5MTQ1MjY3NzIwMjU5NDg4NTI5Njg1MDg5MTA0NTI5MDE1IiwiaHR0cFZlcmIiOiJQT1NUIn19LCJwYXlsb2FkIjp7InNpZ25hdHVyZSI6IjB4MTIzNCIsImF1dGhvcml6YXRpb24iOnsiZnJvbSI6IjB4ZjM5RmQ2ZTUxYWFkODhGNkY0Y2U2YUI4ODI3Mjc5Y2ZmRmI5MjI2NiIsInNlc3Npb25LZXlzUHJvdmlkZXIiOiJ6ZXJvZGV2Iiwic2Vzc2lvbktleXMiOltdfX0sImV4dGVuc2lvbnMiOnt9fQ=="}},"verifyWithMaxAmount":{"summary":"Verify with max amount","description":"Verify permissions with a specific max credit amount. Use this to check if the user has sufficient credits before processing the request.","value":{"paymentRequired":{"x402Version":2,"error":"Payment required to access resource","resource":{"url":"https://myagent.ai/api/v1/tasks","description":"AI agent task execution"},"accepts":[{"scheme":"nvm:erc4337","network":"eip155:84532","planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071","extra":{"agentId":"80918427023170428029540261117198154464497879145267720259488529685089104529015"}}],"extensions":{}},"x402AccessToken":"eyJ4NDAyVmVyc2lvbiI6MiwicmVzb3VyY2UiOnsidXJsIjoiaHR0cHM6Ly9teWFnZW50LmFpL2FwaS92MS90YXNrcyJ9LCJhY2NlcHRlZCI6eyJzY2hlbWUiOiJudm06ZXJjNDMzNyIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MzIiLCJwbGFuSWQiOiI0NDc0Mjc2MzA3NjA0NzQ5NzY0MDA4MDIzMDIzNjc4MTQ3NDEyOTk3MDk5MjcyNzg5NjU5Mzg2MTk5NzM0NzEzNTYxMzEzNTU3MTA3MSIsImV4dHJhIjp7InZlcnNpb24iOiIxIiwiYWdlbnRJZCI6IjgwOTE4NDI3MDIzMTcwNDI4MDI5NTQwMjYxMTE3MTk4MTU0NDY0NDk3ODc5MTQ1MjY3NzIwMjU5NDg4NTI5Njg1MDg5MTA0NTI5MDE1IiwiaHR0cFZlcmIiOiJQT1NUIn19LCJwYXlsb2FkIjp7InNpZ25hdHVyZSI6IjB4MTIzNCIsImF1dGhvcml6YXRpb24iOnsiZnJvbSI6IjB4ZjM5RmQ2ZTUxYWFkODhGNkY0Y2U2YUI4ODI3Mjc5Y2ZmRmI5MjI2NiIsInNlc3Npb25LZXlzUHJvdmlkZXIiOiJ6ZXJvZGV2Iiwic2Vzc2lvbktleXMiOltdfX0sImV4dGVuc2lvbnMiOnt9fQ==","maxAmount":"2"}}}}}},"responses":{"201":{"description":"Permission verification successful (x402 facilitator response)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402VerifyResponseDto"}}}},"400":{"description":"Bad Request - Invalid permissions or insufficient balance","content":{"application/json":{"schema":{"example":{"isValid":false,"invalidReason":"Cannot order plan - insufficient funds","payer":"0xD4f58B60330bC59cB0A07eE6A1A66ad64244eC8c"}}}}},"401":{"description":"Unauthorized - Invalid or expired X402 token","content":{"application/json":{"schema":{"example":{"code":"BCK.X402.0003","httpStatus":401,"message":"Invalid X402 Access Token","params":{"reason":"Token signature verification failed"}}}}}}},"security":[{"Authorization":[]}],"summary":"Verify permission usage","tags":["X402"]}},"/api/v1/x402/settle":{"post":{"description":"Settles delegated permissions for a plan using an existing session key. Authentication via NVM API hash key is currently optional (#1570 deprecation window) and will be required in a future release — callers should start sending the header now. Calls without the header are recorded for SRE forensics.","operationId":"X402Controller_settlePermissions","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlePermissionsDto"},"examples":{"settleBasic":{"summary":"Basic settlement","description":"Settle permissions by redeeming a fixed credit amount. The facilitator validates that the accepted payment method matches one of the accepts.","value":{"paymentRequired":{"x402Version":2,"error":"Payment required to access resource","resource":{"url":"/api/v1/agents/tasks","description":"AI agent task execution"},"accepts":[{"scheme":"nvm:erc4337","network":"eip155:84532","planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071","extra":{"version":"1"}}],"extensions":{}},"x402AccessToken":"eyJ4NDAyVmVyc2lvbiI6MiwicmVzb3VyY2UiOnsidXJsIjoiL2FwaS92MS9hZ2VudHMvdGFza3MifSwiYWNjZXB0ZWQiOnsic2NoZW1lIjoibnZtOmVyYzQzMzciLCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMyIiwicGxhbklkIjoiNDQ3NDI3NjMwNzYwNDc0OTc2NDAwODAyMzAyMzY3ODE0NzQxMjk5NzA5OTI3Mjc4OTY1OTM4NjE5OTczNDcxMzU2MTMxMzU1NzEwNzEiLCJleHRyYSI6eyJ2ZXJzaW9uIjoiMSJ9fSwicGF5bG9hZCI6eyJzaWduYXR1cmUiOiIweDEyMzQiLCJhdXRob3JpemF0aW9uIjp7ImZyb20iOiIweGYzOUZkNmU1MWFhZDg4RjZGNGNlNmFCODgyNzI3OWNmZkZiOTIyNjYiLCJzZXNzaW9uS2V5c1Byb3ZpZGVyIjoiemVyb2RldiIsInNlc3Npb25LZXlzIjpbXX19LCJleHRlbnNpb25zIjp7fX0=","maxAmount":"2","agentRequestId":"arId-123e4567-e89b-12d3-a456-426614174000"}},"settleWithMargin":{"summary":"Settle with margin percentage","description":"Settle permissions using actual cost with a margin percentage added. Useful when the exact cost is determined after processing.","value":{"paymentRequired":{"x402Version":2,"error":"Payment required to access resource","resource":{"url":"/api/v1/agents/tasks","description":"AI agent task execution"},"accepts":[{"scheme":"nvm:erc4337","network":"eip155:84532","planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071","extra":{"version":"1"}}],"extensions":{}},"x402AccessToken":"eyJ4NDAyVmVyc2lvbiI6MiwicmVzb3VyY2UiOnsidXJsIjoiL2FwaS92MS9hZ2VudHMvdGFza3MifSwiYWNjZXB0ZWQiOnsic2NoZW1lIjoibnZtOmVyYzQzMzciLCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMyIiwicGxhbklkIjoiNDQ3NDI3NjMwNzYwNDc0OTc2NDAwODAyMzAyMzY3ODE0NzQxMjk5NzA5OTI3Mjc4OTY1OTM4NjE5OTczNDcxMzU2MTMxMzU1NzEwNzEiLCJleHRyYSI6eyJ2ZXJzaW9uIjoiMSJ9fSwicGF5bG9hZCI6eyJzaWduYXR1cmUiOiIweDEyMzQiLCJhdXRob3JpemF0aW9uIjp7ImZyb20iOiIweGYzOUZkNmU1MWFhZDg4RjZGNGNlNmFCODgyNzI3OWNmZkZiOTIyNjYiLCJzZXNzaW9uS2V5c1Byb3ZpZGVyIjoiemVyb2RldiIsInNlc3Npb25LZXlzIjpbXX19LCJleHRlbnNpb25zIjp7fX0=","agentRequestId":"arId-123e4567-e89b-12d3-a456-426614174000","marginPercent":0.2}},"settleBatch":{"summary":"Settle batch request","description":"Settle permissions for a batch of LLM calls under a single agentRequestId. Use this when aggregating multiple operations.","value":{"paymentRequired":{"x402Version":2,"error":"Payment required to access resource","resource":{"url":"/api/v1/agents/tasks","description":"AI agent task execution"},"accepts":[{"scheme":"nvm:erc4337","network":"eip155:84532","planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071","extra":{"version":"1"}}],"extensions":{}},"x402AccessToken":"eyJ4NDAyVmVyc2lvbiI6MiwicmVzb3VyY2UiOnsidXJsIjoiL2FwaS92MS9hZ2VudHMvdGFza3MifSwiYWNjZXB0ZWQiOnsic2NoZW1lIjoibnZtOmVyYzQzMzciLCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMyIiwicGxhbklkIjoiNDQ3NDI3NjMwNzYwNDc0OTc2NDAwODAyMzAyMzY3ODE0NzQxMjk5NzA5OTI3Mjc4OTY1OTM4NjE5OTczNDcxMzU2MTMxMzU1NzEwNzEiLCJleHRyYSI6eyJ2ZXJzaW9uIjoiMSJ9fSwicGF5bG9hZCI6eyJzaWduYXR1cmUiOiIweDEyMzQiLCJhdXRob3JpemF0aW9uIjp7ImZyb20iOiIweGYzOUZkNmU1MWFhZDg4RjZGNGNlNmFCODgyNzI3OWNmZkZiOTIyNjYiLCJzZXNzaW9uS2V5c1Byb3ZpZGVyIjoiemVyb2RldiIsInNlc3Npb25LZXlzIjpbXX19LCJleHRlbnNpb25zIjp7fX0=","maxAmount":"10","agentRequestId":"arId-batch-456e7890-e89b-12d3-a456-426614174000","batch":true}}}}}},"responses":{"201":{"description":"Permission settlement successful (x402 facilitator response)","schema":{"example":{"success":true,"payer":"0xD4f58B60330bC59cB0A07eE6A1A66ad64244eC8c","transaction":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","network":"eip155:84532","creditsRedeemed":"2","remainingBalance":"98"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402SettleResponseDto"}}}},"400":{"description":"Bad Request - Settlement failed","content":{"application/json":{"schema":{"example":{"success":false,"errorReason":"Credit redemption failed","payer":"0xD4f58B60330bC59cB0A07eE6A1A66ad64244eC8c","transaction":"","network":"eip155:84532"}}}}},"401":{"description":"Unauthorized - Invalid or expired X402 token","content":{"application/json":{"schema":{"example":{"code":"BCK.X402.0003","httpStatus":401,"message":"Invalid X402 Access Token","params":{"reason":"Token has expired"}}}}}}},"security":[{"Authorization":[]}],"summary":"Settle permission usage","tags":["X402"]}},"/api/v1/x402/permissions/{permissionHash}":{"get":{"description":"Returns the details of a specific permission owned by the authenticated user, including delegation budget information when the permission is delegation-linked. Requires a Nevermined API key.","operationId":"X402Controller_getPermissionDetails","parameters":[{"name":"permissionHash","required":true,"in":"path","description":"The permission hash","schema":{"example":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","type":"string"}}],"responses":{"200":{"description":"Permission details retrieved successfully","schema":{"example":{"permissionHash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071","planName":"Premium AI Access","status":"Active","createdAt":"2025-01-10T12:00:00Z","lastUsedAt":"2025-01-11T14:30:00Z","expiresAt":"2025-12-31T23:59:59Z","redemptionLimit":100}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionDetailsDto"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"example":{"code":"BCK.APIKEY.0004","httpStatus":401,"message":"Invalid API key"}}}}},"404":{"description":"Not Found - Permission does not exist","content":{"application/json":{"schema":{"example":{"code":"BCK.X402.0015","httpStatus":404,"message":"Permission not found","params":{"permissionHash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"}}}}}}},"security":[{"Authorization":[]}],"summary":"Get permission details","tags":["X402"]},"delete":{"description":"Revokes a permission, preventing further use for settlement. For delegation-linked permissions the revocation cascades to the linked delegation (and to sibling erc4337 permissions). Requires a Nevermined API key.","operationId":"X402Controller_revokePermission","parameters":[{"name":"permissionHash","required":true,"in":"path","description":"The permission hash to revoke","schema":{"example":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","type":"string"}}],"responses":{"200":{"description":"Permission successfully revoked","schema":{"example":{"success":true,"message":"Permission revoked successfully"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/_NvmAPIResultDto"}}}},"400":{"description":"Bad Request - Permission is already revoked","content":{"application/json":{"schema":{"example":{"code":"BCK.X402.0009","httpStatus":400,"message":"Permission is already revoked","params":{"permissionHash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","status":"Revoked"}}}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"example":{"code":"BCK.APIKEY.0004","httpStatus":401,"message":"Invalid API key"}}}}},"404":{"description":"Not Found - Permission does not exist","content":{"application/json":{"schema":{"example":{"code":"BCK.X402.0015","httpStatus":404,"message":"Permission not found","params":{"permissionHash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"}}}}}}},"security":[{"Authorization":[]}],"summary":"Revoke permission","tags":["X402"]}},"/.well-known/jwks.json":{"get":{"description":"Returns the JSON Web Key Set used by OAuth clients to verify the JWTs issued by this authorization server. Public endpoint — no authentication required.","operationId":"WellKnownController_getJWKS","parameters":[],"responses":{"200":{"description":"Returns the JSON Web Key Set","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object","properties":{"kty":{"type":"string"},"use":{"type":"string"},"kid":{"type":"string"},"n":{"type":"string"},"e":{"type":"string"},"alg":{"type":"string"}}}}}}}}}},"summary":"Get JSON Web Key Set (JWKS)","tags":["Well-Known"]}},"/.well-known/oauth-authorization-server":{"get":{"description":"Returns the OAuth 2.0 Authorization Server metadata document (RFC 8414), providing discovery information such as endpoints and supported grant types for OAuth clients. Public endpoint — no authentication required.","operationId":"WellKnownController_getOAuthAuthorizationServer","parameters":[],"responses":{"200":{"description":"Returns OAuth Authorization Server metadata","content":{"application/json":{"schema":{"type":"object","properties":{"issuer":{"type":"string"},"authorization_endpoint":{"type":"string"},"token_endpoint":{"type":"string"},"jwks_uri":{"type":"string"},"response_types_supported":{"type":"array","items":{"type":"string"}},"response_modes_supported":{"type":"array","items":{"type":"string"}},"grant_types_supported":{"type":"array","items":{"type":"string"}},"token_endpoint_auth_methods_supported":{"type":"array","items":{"type":"string"}},"scopes_supported":{"type":"array","items":{"type":"string"}},"code_challenge_methods_supported":{"type":"array","items":{"type":"string"}}}}}}}},"summary":"Get OAuth Authorization Server metadata","tags":["Well-Known"]}},"/api/v1/payment-methods":{"get":{"description":"Returns the saved payment methods for the authenticated user. Requires a Nevermined API key.","operationId":"PaymentMethodsController_listPaymentMethods","parameters":[{"name":"accessible","required":false,"in":"query","description":"When \"true\", return only payment methods accessible to the requesting API key (filters by allowedApiKeyIds and Active status).","schema":{"enum":["true","false"],"type":"string"}},{"name":"provider","required":false,"in":"query","description":"When set, return only payment methods backed by this provider. Omit to return methods from every provider (default).","schema":{"enum":["stripe","braintree","erc4337","visa"],"type":"string"}}],"responses":{"200":{"description":"List of saved payment methods","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethodSummaryDto"}}}}},"400":{"description":"Bad Request - Unknown provider value"},"401":{"description":"Unauthorized - Invalid or missing API key"}},"security":[{"Authorization":[]}],"summary":"List saved payment methods","tags":["Payment Methods"]}},"/api/v1/payment-methods/{paymentMethodId}":{"patch":{"description":"Updates a saved payment method, changing its friendly alias and/or the set of NVM API keys allowed to use it. Requires a Nevermined API key.","operationId":"PaymentMethodsController_updatePaymentMethod","parameters":[{"name":"paymentMethodId","required":true,"in":"path","description":"Identifier of the payment method to update","schema":{"example":"pm_1Abc2Def3Ghi4Jkl","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePaymentMethodDto"}}}},"responses":{"200":{"description":"The updated payment method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentMethodSummaryDto"}}}},"401":{"description":"Unauthorized - Invalid or missing API key"},"404":{"description":"Not Found - Payment method does not exist"}},"security":[{"Authorization":[]}],"summary":"Update a payment method","tags":["Payment Methods"]},"delete":{"description":"Revokes (detaches) a saved payment method so it can no longer be used for delegated payments. Requires a Nevermined API key.","operationId":"PaymentMethodsController_revokePaymentMethod","parameters":[{"name":"paymentMethodId","required":true,"in":"path","description":"Identifier of the payment method to revoke","schema":{"example":"pm_1Abc2Def3Ghi4Jkl","type":"string"}}],"responses":{"200":{"description":"Payment method revoked","content":{"application/json":{"schema":{"example":{"success":true}}}}},"401":{"description":"Unauthorized - Invalid or missing API key"},"404":{"description":"Not Found - Payment method does not exist"}},"security":[{"Authorization":[]}],"summary":"Revoke a payment method","tags":["Payment Methods"]}}},"info":{"title":"NVM BACKEND API","description":"","version":"0.5.21","contact":{}},"tags":[],"servers":[{"url":"https://api.live.nevermined.app"}],"components":{"securitySchemes":{"Authorization":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"AdditionalInformationDto":{"type":"object","properties":{"privyUserId":{"type":"string","example":"http://example.com/avatar.jpg","description":"Profile image url"}},"required":["privyUserId"]},"_GetUserProfileDto":{"type":"object","properties":{"userId":{"type":"string","example":"jifdwqejidqwa9okdasodkaso","description":"Unique identifier of the user"},"isListed":{"type":"boolean","example":true,"description":"Flag identifying if the user is listed in the marketplace. Possible values: true or false"},"state":{"type":"string","enum":["disabled","unconfirmed","confirmed"],"example":"confirmed","description":"State of the user in the marketplace. Possible options: disabled, unconfirmed, confirmed"},"address":{"type":"string","example":"0x37BB53e3d293494DE59fBe1FF78500423dcFd43B","description":"The address owned by the user. Address cannot be shared between different users"},"nickname":{"type":"string","example":"john.doe","description":"The nickname of the user"},"name":{"type":"string","example":"John Doe","description":"The name of the user"},"email":{"type":"string","example":"john.doe@example.com","description":"The email of the user"},"creationDate":{"type":"string","example":"2019-01-01T19:73:24Z","description":"When the user information was created"},"updateDate":{"type":"string","example":"2019-01-01T19:73:24Z","description":"When was the last time the user information was updated"},"additionalInformation":{"description":"List of additional key-value attributes with additional information","allOf":[{"$ref":"#/components/schemas/AdditionalInformationDto"}]},"live":{"type":"object","description":"Stripe information for live environment"},"sandbox":{"type":"object","description":"Stripe information for sandbox environment"},"braintreeLive":{"type":"object","description":"Braintree merchant information for live environment"},"braintreeSandbox":{"type":"object","description":"Braintree merchant information for sandbox environment"},"paymentCountry":{"type":"string","example":"US","description":"The country of the user"},"acceptedTermsAndConditions":{"type":"boolean","example":true,"description":"True if the user accepted terms and conditions."},"acceptedTermsAndConditionsDate":{"type":"string","example":"2019-01-01T19:73:24Z","description":"Date when the user accepted terms and conditions"},"paymentMethodsAccepted":{"type":"string","example":"all","description":"Payment methods accepted by the user"},"role":{"type":"string","enum":["Admin","Member"],"description":"Role of the user within an organization if the user is a member"},"profileType":{"type":"string","enum":["merchant","consumer","hybrid"],"example":"hybrid","description":"Self-declared profile type. Controls which features are visible in the webapp. \"hybrid\" shows everything. Always present on API responses (the DB column is non-null with default hybrid), but typed optional to match the other optional response fields and avoid reordering the constructor."}},"required":["userId","isListed","state","address","nickname","name","email","creationDate","updateDate","additionalInformation","paymentCountry","acceptedTermsAndConditions","acceptedTermsAndConditionsDate","paymentMethodsAccepted"]},"CreateUserProfileDto":{"type":"object","properties":{"isListed":{"type":"boolean","example":true,"description":"Flag identifying if the user is listed in the marketplace. Possible values: true or false"},"state":{"type":"string","enum":["disabled","unconfirmed","confirmed"],"example":"confirmed","description":"State of the user in the marketplace. Possible options: disabled, unconfirmed, confirmed"},"address":{"type":"string","example":"0x37BB53e3d293494DE59fBe1FF78500423dcFd43B","description":"The address owned by the user. Address cannot be shared between different users"},"nickname":{"type":"string","example":"john.doe","description":"The nickname of the user"},"name":{"type":"string","example":"John Doe","description":"The name of the user"},"email":{"type":"string","example":"john.doe@example.com","description":"The email of the user"},"paymentCountry":{"type":"string","example":"US","description":"The country of the user"},"additionalInformation":{"description":"List of additional key-value attributes with additional information","allOf":[{"$ref":"#/components/schemas/AdditionalInformationDto"}]}},"required":["isListed","state","address","nickname","paymentCountry"]},"RestrictedUserProfileDto":{"type":"object","properties":{"userId":{"type":"string","example":"jifdwqejidqwa9okdasodkaso","description":"Unique identifier of the user"},"nickname":{"type":"string","example":"john.doe","description":"The nickname of the user"},"name":{"type":"string","example":"John Doe","description":"The name of the user"},"additionalInformation":{"description":"List of additional key-value attributes with additional information","allOf":[{"$ref":"#/components/schemas/AdditionalInformationDto"}]}},"required":["userId","nickname","additionalInformation"]},"UpdateUserSelfProfileDto":{"type":"object","properties":{"nickname":{"type":"string","example":"john.doe","description":"The nickname of the user"},"name":{"type":"string","example":"John Doe","description":"The name of the user"},"email":{"type":"string","example":"john.doe@example.com","description":"The email of the user"},"paymentCountry":{"type":"string","example":"US","description":"The country of the user"},"acceptedTermsAndConditions":{"type":"boolean","example":true,"description":"True if the user accepted terms and conditions."},"additionalInformation":{"description":"List of additional key-value attributes with additional information","allOf":[{"$ref":"#/components/schemas/AdditionalInformationDto"}]},"profileType":{"type":"string","enum":["merchant","consumer","hybrid"],"example":"merchant","description":"Self-declared profile type. Controls which features are visible in the webapp. \"hybrid\" shows everything."}}},"RegisterApiKeyFromEncryptedKeyDto":{"type":"object","properties":{"nvmKey":{"type":"string","description":"The encrypted NVM API key containing the session key","example":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0.eyJpc3Mi[...omitted for brevity...]"},"clientAssertion":{"type":"string","description":"JWT client assertion for backend authentication (RFC-7523). When provided, authenticates using the Nevermined passport strategy instead of Privy identity token.","example":"eyJhbGciOiJFUzI1NksiLCJ0eXAiOiJKV1QifQ.eyJpc3Mi[...omitted for brevity...]"}},"required":["nvmKey"]},"LoginDto":{"type":"object","properties":{"hash":{"type":"string","description":"The Hash of the Nevermined API key","example":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0.eyJpc3Mi[...omitted for brevity...]"},"userId":{"type":"string","example":"u-12345","description":"The userId identifying the user"},"userWallet":{"type":"string","example":"0x1234567890abcdef1234567890abcdef12345678","description":"Address of the user"}},"required":["hash","userId","userWallet"]},"_RegisterApiKeyDto":{"type":"object","properties":{"nvmKey":{"type":"string","example":"my api key","description":"The Nevermined API Key Encrypted"},"orgId":{"type":"string","example":"org-aaa-bbb","description":"The organization id of the user creating the api key"},"name":{"type":"string","example":"my api key","description":"Name of the api key given by the user"},"isBrowser":{"type":"boolean","example":true,"default":false,"description":"Indicates if the api key is for browser usage"},"expiresAt":{"format":"date-time","type":"string","description":"Expiration date of the api key given by the user"}},"required":["nvmKey","orgId","name","isBrowser","expiresAt"]},"ApiKeyEntity":{"type":"object","properties":{}},"SearchApiKeyDto":{"type":"object","properties":{"skId":{"type":"string","example":"sk-1234567890abcdef","description":"The unique identifier of the API key"},"userId":{"type":"string","example":"us-0d725471-3d70-4982-8080-63adcd5b9765","description":"The unique identifier of the user"},"userWallet":{"type":"string","example":"0x1234567890abcdef1234567890abcdef12345678","description":"Address of the user"},"hash":{"type":"string","example":"eY......","description":"Api key hash"},"name":{"type":"string","example":"test key","description":"Name of the Api key"},"orgId":{"type":"string","example":"Acme Corp","description":"Name of the organization"},"isActive":{"type":"boolean","example":true,"default":true,"description":"Indicates if the api key is active"},"isBrowser":{"type":"boolean","example":true,"description":"Indicates if the api key is for browser usage"},"canRegister":{"type":"boolean","example":true,"description":"Indicates if the api key can register plans and agents"},"canOrder":{"type":"boolean","example":true,"description":"Indicates if the api key can order plans"},"canMint":{"type":"boolean","example":true,"description":"Indicates if the api key can mint credits of plans that belong to the user"},"canBurn":{"type":"boolean","example":true,"description":"Indicates if the api key can burn credits of plans that belong to the user"},"createdBetweenBeginning":{"format":"date-time","type":"string","description":"Filter to search between two dates, this one is the beginning"},"createdBetweenEnd":{"format":"date-time","type":"string","description":"Filter to search between two dates, this one is the end"},"page":{"type":"number","example":1,"description":"Page of the points list"},"offset":{"type":"number","example":20,"description":"Page offset of the points list"}},"required":["skId","userId","userWallet","hash","name","orgId","isActive","isBrowser","canRegister","canOrder","canMint","canBurn","createdBetweenBeginning","createdBetweenEnd","page","offset"]},"ApiKeysPageDto":{"type":"object","properties":{"totalResults":{"type":"number","example":7,"description":"Total number of keys found"},"apiKeys":{"description":"List of api keys","example":[{"skId":"sk-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d","userId":"jifdwqejidqwa9okdasodkaso","userWallet":"0x37BB53e3d293494DE59fBe1FF78500423dcFd43B","isActive":true,"isBrowser":false,"canRegister":true,"canOrder":true,"canMint":false,"canBurn":false,"name":"Production agent key","orgId":"org-9f8e7d6c","expiresAt":null,"createdAt":"2026-05-29T10:00:00.000Z","updatedAt":"2026-05-29T10:00:00.000Z"}],"type":"array","items":{"type":"string"}},"page":{"type":"number","example":1,"description":"Page of the keys list"},"offset":{"type":"number","example":20,"description":"Page offset of the keys list"}},"required":["totalResults","apiKeys","page","offset"]},"ApiKeyTxsPageDto":{"type":"object","properties":{"totalResults":{"type":"number","example":7,"description":"Total number of transactions found"},"items":{"description":"List of api key transactions","example":[{"id":"st-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d","skId":"sk-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d","userId":"jifdwqejidqwa9okdasodkaso","userWallet":"0x37BB53e3d293494DE59fBe1FF78500423dcFd43B","txType":"order","result":200,"amount":1,"createdAt":"2026-05-29T10:00:00.000Z"}],"type":"array","items":{"type":"string"}},"page":{"type":"number","example":1,"description":"Page of the transactions list"},"offset":{"type":"number","example":20,"description":"Page offset of the transactions list"}},"required":["totalResults","items","page","offset"]},"SearchApiKeyTxsDto":{"type":"object","properties":{"skId":{"type":"string","example":"sk-1234567890abcdef","description":"The unique identifier of the API key"},"userId":{"type":"string","example":"us-0d725471-3d70-4982-8080-63adcd5b9765","description":"The unique identifier of the user"},"userWallet":{"type":"string","example":"0x1234567890abcdef1234567890abcdef12345678","description":"Address of the user"},"txType":{"type":"string","enum":["NewPlan","NewAgent","EditPlan","EditAgent","Purchase","Download","AccessHit","Mint","Burn","AgentExecution","Other"],"example":"NewPlan","description":"Type of usage of the session key"},"result":{"type":"number","example":200,"description":"The result of the transaction"},"amount":{"type":"number","example":10,"description":"The amount of the transaction"},"createdBetweenBeginning":{"format":"date-time","type":"string","description":"Filter to search between two dates, this one is the beginning"},"createdAt":{"format":"date-time","type":"string","example":"2026-06-16T14:48:41.696Z","description":"The date when the transaction was created"},"createdBetweenEnd":{"format":"date-time","type":"string","description":"Filter to search between two dates, this one is the end"},"page":{"type":"number","example":1,"description":"Page of the points list"},"offset":{"type":"number","example":20,"description":"Page offset of the points list"}},"required":["skId","userId","userWallet","txType","result","amount","createdBetweenBeginning","createdAt","createdBetweenEnd","page","offset"]},"ApiKeyStatsResponseDto":{"type":"object","properties":{"period":{"type":"string","description":"The time period used for the query"},"key":{"type":"string","description":"The API key filter used (\"all\" or a specific skId)"},"volumeByKey":{"type":"array","description":"Time-bucketed request volume grouped by API key name","items":{"type":"object"}},"volumeByTxType":{"type":"array","description":"Time-bucketed request volume grouped by transaction type","items":{"type":"object"}},"volumeByStatus":{"type":"array","description":"Time-bucketed request volume grouped by HTTP status group (2xx, 4xx, 5xx)","items":{"type":"object"}}},"required":["period","key","volumeByKey","volumeByTxType","volumeByStatus"]},"UpdateApiKeyNameDto":{"type":"object","properties":{"hash":{"type":"string","description":"The hash of the API key to update"},"name":{"type":"string","example":"My API Key","description":"New name for the API key","minLength":1,"maxLength":255}},"required":["hash","name"]},"ManifestDto":{"type":"object","properties":{"documents":{"type":"object","description":"Map of slug -> document metadata","example":{"terms":{"current":"1.1.0","versions":[]}}}},"required":["documents"]},"ConsentStatusDto":{"type":"object","properties":{"terms":{"type":"string","enum":["never","outdated","current"]},"privacy":{"type":"string","enum":["never","outdated","current"]}},"required":["terms","privacy"]},"DocumentContentDto":{"type":"object","properties":{"slug":{"type":"string","example":"terms"},"version":{"type":"string","example":"1.1.0"},"effectiveAt":{"type":"string","example":"2026-04-29T00:00:00Z"},"requiresReConsent":{"type":"boolean","example":true},"contentMarkdown":{"type":"string","example":"# Nevermined Terms of Service\n\n..."}},"required":["slug","version","effectiveAt","requiresReConsent","contentMarkdown"]},"AcceptanceDto":{"type":"object","properties":{"slug":{"type":"string","enum":["terms","privacy"]},"version":{"type":"string","example":"1.1.0"}},"required":["slug","version"]},"RecordConsentsDto":{"type":"object","properties":{"acceptances":{"type":"array","items":{"$ref":"#/components/schemas/AcceptanceDto"}},"action":{"type":"string","enum":["signup","login","checkout","payment_method_enrollment"]}},"required":["acceptances","action"]},"GenerateTokenDto":{"type":"object","properties":{}},"ErrorResponseDto":{"type":"object","properties":{}},"CreateOrganizationDto":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the organization","example":"Nevermined Labs"},"description":{"type":"string","description":"Short description of the organization","example":"AI infrastructure for knowledge agents."},"url":{"type":"string","description":"Organization public URL","example":"https://nevermined.app"},"organizationWallet":{"type":"string","description":"Wallet address for the organization","example":"0x1234567890abcdef1234567890abcdef12345678"},"cryptoFees":{"type":"string","description":"Fee percentage for crypto payments (as decimal, e.g., 0.05 for 5%)","example":"0"},"fiatFees":{"type":"string","description":"Fee percentage for fiat payments (as decimal, e.g., 0.05 for 5%)","example":"0"},"isActive":{"type":"boolean","description":"Whether the organization is active","example":true,"default":true},"orgType":{"type":"string","description":"Type of organization subscription","enum":["Premium","Enterprise","Lapsed","Other"],"example":"Lapsed","default":"Lapsed"},"branding":{"type":"object","description":"Branding configuration for the organization","example":{"themeName":"default","logo":"https://example.com/logo.png"}},"live":{"type":"object","description":"Stripe configuration for live environment","example":{"accountId":"acct_1234567890","isAccountValidated":false}},"sandbox":{"type":"object","description":"Stripe configuration for sandbox environment","example":{"accountId":"acct_test_1234567890","isAccountValidated":false}}},"required":["name","organizationWallet"]},"SearchOrganizationMembersDto":{"type":"object","properties":{"role":{"type":"string","enum":["Admin","Member"],"example":"Admin","description":"Role of the organization member"},"isActive":{"type":"boolean","example":true,"description":"Active status of the organization member"},"page":{"type":"number","example":1,"description":"Page of the organization members list"},"offset":{"type":"number","example":20,"description":"Page offset of the organization members list"},"environment":{"type":"string","example":"sandbox","description":"Environment to get stripe account id from (live or sandbox)","enum":["live","sandbox"]}},"required":["role","isActive","page","offset","environment"]},"OrganizationMemberWithProfileDto":{"type":"object","properties":{"name":{"type":"object","example":"John Doe","description":"Name of the user","nullable":true},"stripeAccountId":{"type":"object","example":"acct_1234567890","description":"Stripe account ID for the current environment","nullable":true}},"required":["name","stripeAccountId"]},"OrganizationMembersPageDto":{"type":"object","properties":{"totalResults":{"type":"number","example":137,"description":"Total number of results found"},"members":{"description":"List of organization members with profile information","type":"array","items":{"$ref":"#/components/schemas/OrganizationMemberWithProfileDto"}},"page":{"type":"number","example":1,"description":"Page of the notifications list"},"offset":{"type":"number","example":20,"description":"Page offset of the notifications list"},"totalActiveAdmins":{"type":"number","example":2,"description":"Total number of ACTIVE admins in the organization (not just on this page). Used by the webapp to guard \"demote / deactivate / remove last admin\" actions when the relevant admin sits on a different page than the viewer."}},"required":["totalResults","members","page","offset","totalActiveAdmins"]},"UpdateOrganizationDto":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the organization","example":"Nevermined Labs"},"description":{"type":"string","description":"Short description that will be shown publicly","example":"AI infrastructure for knowledge agents."},"url":{"type":"string","description":"Organization public URL","example":"https://nevermined.app"},"isActive":{"type":"boolean","description":"Whether the organization is active. If set to false, all members will also be deactivated.","example":true},"cryptoFees":{"type":"string","description":"Fee percentage for crypto payments, multiplied by 10000 (e.g., 1500 = 15%)","example":"1500"},"fiatFees":{"type":"string","description":"Fee percentage for fiat payments, multiplied by 10000 (e.g., 1500 = 15%)","example":"1500"}}},"MyMembershipDto":{"type":"object","properties":{"orgId":{"type":"string","example":"org-abc123","description":"Organization ID"},"orgName":{"type":"string","example":"Acme Corp","description":"Organization display name"},"role":{"type":"string","example":"Member","description":"Role of the authenticated user in this organization","enum":["Admin","Member"]},"orgType":{"type":"string","example":"Lapsed","description":"Organization type","enum":["Premium","Enterprise","Lapsed","Other"]},"isAdmin":{"type":"boolean","example":false,"description":"Whether the user is an admin of this organization"},"hasSubscriptionHistory":{"type":"boolean","example":false,"description":"True when the org has at least one organizationSubscription row — i.e. the org has previously been associated with a paid tier (active, past_due, trialing, lapsed, or canceled). Combined with `orgType === Lapsed` it distinguishes \"subscription expired\" (block resource creation) from \"free org that never subscribed\" (allow within free caps)."}},"required":["orgId","orgName","role","orgType","isAdmin","hasSubscriptionHistory"]},"ValidateOrgResponseDto":{"type":"object","properties":{"valid":{"type":"boolean","example":true,"description":"Whether the user is allowed to use the requested org as their workspace context"},"currentOrgId":{"type":"string","example":"org-abc123","description":"The org ID that was validated, or null for personal context","nullable":true},"role":{"type":"string","example":"Member","description":"Role of the user in the organization","enum":["Admin","Member"]},"orgName":{"type":"string","example":"Acme Corp","description":"Name of the organization"},"orgType":{"type":"string","example":"Lapsed","description":"Type of the organization","enum":["Premium","Enterprise","Lapsed","Other"]}},"required":["valid","currentOrgId"]},"ChangeMemberRoleDto":{"type":"object","properties":{"role":{"type":"string","example":"Member","description":"New role for the member. Only Admin or Member are permitted.","enum":["Admin","Member"]}},"required":["role"]},"BrandingDto":{"type":"object","properties":{"themeName":{"type":"string","description":"Theme name, e.g. 'default', 'gradient', 'dark', 'ocean', 'sunset', 'custom'.","example":"default"},"logo":{"type":"string","description":"Company logo URL.","example":"https://example.com/logo.png"},"leftPanelHeadingTextColor":{"type":"string","description":"Left panel heading text color.","example":"#0F172A"},"leftPanelBodyTextColor":{"type":"string","description":"Left panel body text color.","example":"#334155"},"leftPanelBackgroundColor1":{"type":"string","description":"Left panel background color (stop 1).","example":"#FFFFFF"},"leftPanelBackgroundColor2":{"type":"string","description":"Left panel background color (stop 2).","example":"#F1F5F9"},"leftPanelBackgroundImageUrl":{"type":"string","description":"Left panel background image URL (alternative to background colors).","example":"https://example.com/bg-left.png"},"rightCardTextColor":{"type":"string","description":"Right card text color.","example":"#0F172A"},"rightCardButtonBackgroundColor":{"type":"string","description":"Right card button background color.","example":"#2563EB"},"rightCardButtonTextColor":{"type":"string","description":"Right card button text color.","example":"#FFFFFF"},"rightCardBackgroundColor1":{"type":"string","description":"Right card background color (stop 1).","example":"#FFFFFF"},"rightCardBackgroundColor2":{"type":"string","description":"Right card background color (stop 2).","example":"#E2E8F0"},"rightCardBackgroundImageUrl":{"type":"string","description":"Right card background image URL (alternative to background colors).","example":"https://example.com/bg-right.png"}}},"SaveBrandingDto":{"type":"object","properties":{"branding":{"description":"Branding configuration (theme colors, logo) to persist on the organization.","allOf":[{"$ref":"#/components/schemas/BrandingDto"}]},"name":{"type":"string","description":"Organization display name to update.","example":"Acme Corp"},"url":{"type":"string","description":"Organization public URL to update.","example":"https://acme.example.com"}}},"CreateInvitationDto":{"type":"object","properties":{"email":{"type":"string","description":"Email address of the person to invite","example":"colleague@example.com","maxLength":254},"name":{"type":"string","description":"Display name of the invitee. Used to greet them in the email.","example":"Jane Doe","maxLength":120},"role":{"type":"string","description":"Role to assign in the organization","enum":["Admin","Member"],"example":"Member"}},"required":["email","name","role"]},"InvitationResponseDto":{"type":"object","properties":{"id":{"type":"string","example":"oi-550e8400-e29b-41d4-a716-446655440000"},"email":{"type":"string","example":"colleague@example.com"},"name":{"type":"object","example":"Jane Doe"},"role":{"type":"string","enum":["Admin","Member"]},"status":{"type":"string","enum":["pending","accepted","revoked","expired"]},"expiresAt":{"format":"date-time","type":"string"},"invitedByUserId":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","email","role","status","expiresAt","invitedByUserId","createdAt"]},"OrganizationInvitationStatus":{"type":"string","enum":["pending","accepted","revoked","expired"]},"PublicInvitationInfoDto":{"type":"object","properties":{"email":{"type":"string","example":"colleague@example.com"},"name":{"type":"object","example":"Jane Doe"},"orgId":{"type":"string","description":"Organization ID"},"organizationName":{"type":"string","description":"Organization display name"},"role":{"type":"string","enum":["Admin","Member"]},"status":{"type":"string","enum":["pending","accepted","revoked","expired"]},"expiresAt":{"format":"date-time","type":"string"}},"required":["email","orgId","organizationName","role","status","expiresAt"]},"AcceptInvitationResponseDto":{"type":"object","properties":{"orgId":{"type":"string","description":"Organization ID the user was added to"},"membershipId":{"type":"string","description":"New membership row ID"},"role":{"type":"string","enum":["Admin","Member"]}},"required":["orgId","membershipId","role"]},"OrganizationActivityEventResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Activity event ID (ae-{uuid})"},"eventType":{"type":"string","enum":["member.invited","member.joined","member.role_changed","member.deactivated","member.reactivated","member.removed","invitation.revoked","invitation.expired","agent.created","plan.created","plan.updated","plan.purchased","customer.added","customer.blocked","customer.unblocked","subscription.upgraded","subscription.downgraded","subscription.canceled","subscription.lapsed","webhook.delivered","webhook.failed","apikey.created","apikey.revoked","credits.redeemed"],"description":"The type of event that occurred"},"actorUserId":{"type":"object","description":"The user ID of the actor who triggered the event, or null for system events","nullable":true},"subject":{"type":"object","description":"The resource the event is about: { kind, id, ...extra }"},"metadata":{"type":"object","description":"Optional extra payload (e.g. role change before/after)","nullable":true},"occurredAt":{"format":"date-time","type":"string","description":"When the event occurred"}},"required":["id","eventType","subject","occurredAt"]},"OrganizationActivityEventPageDto":{"type":"object","properties":{"items":{"description":"Page of activity events ordered by occurredAt DESC","type":"array","items":{"$ref":"#/components/schemas/OrganizationActivityEventResponseDto"}},"total":{"type":"number","description":"Total number of events matching the filter (across all pages)"}},"required":["items","total"]},"CustomerTimeSeriesPointDto":{"type":"object","properties":{"date":{"type":"string","description":"Bucket date in YYYY-MM-DD (UTC).","example":"2026-05-01"},"purchases":{"type":"number","description":"Number of purchases in this bucket.","example":5},"amount":{"type":"string","description":"Sum of prices for purchases in this bucket, serialised as a string (bigint).","example":"125000000"}},"required":["date","purchases","amount"]},"OrgCustomersAggregationsResponseDto":{"type":"object","properties":{"customerCount":{"type":"number","description":"Total customers ever seen for this org.","example":128},"purchaseCount":{"type":"number","description":"Count of purchase transactions in range.","example":47},"totalSpent":{"type":"string","description":"Sum of purchase prices in range, serialised as a string (bigint).","example":"125000000"},"timeSeries":{"description":"Gap-filled daily series.","type":"array","items":{"$ref":"#/components/schemas/CustomerTimeSeriesPointDto"}},"from":{"type":"string","description":"Start of the requested window (ISO-8601).","example":"2026-05-01T00:00:00.000Z"},"to":{"type":"string","description":"End of the requested window (ISO-8601).","example":"2026-05-31T23:59:59.000Z"}},"required":["customerCount","purchaseCount","totalSpent","timeSeries","from","to"]},"OrganizationCustomerStatus":{"type":"string","enum":["active","blocked"]},"CustomerResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Customer record ID.","example":"oc-7b1c3e9a"},"orgId":{"type":"string","description":"Organization the customer belongs to.","example":"org-abc123"},"userId":{"type":"string","description":"Nevermined user ID of the customer.","example":"us-2f4a6c8e"},"firstSeenAt":{"type":"string","description":"ISO-8601 timestamp the customer was first observed.","example":"2026-01-15T09:30:00.000Z"},"lastActiveAt":{"type":"string","description":"ISO-8601 timestamp of the customer’s most recent activity.","example":"2026-05-20T14:05:00.000Z"},"totalSpent":{"type":"string","description":"Total amount the customer has spent, serialised as a string (bigint).","example":"125000000"},"createdAt":{"type":"string","description":"ISO-8601 timestamp the customer record was created.","example":"2026-01-15T09:30:00.000Z"},"userName":{"type":"object","description":"Display name from the buyer’s user profile, when available.","example":"Aitor Argomaniz","nullable":true},"userEmail":{"type":"object","description":"Email from the buyer’s user profile, when available.","example":"aitor@example.com","nullable":true}},"required":["id","orgId","userId","firstSeenAt","lastActiveAt","totalSpent","createdAt"]},"CustomerAggregationsResponseDto":{"type":"object","properties":{"customer":{"description":"The customer record.","allOf":[{"$ref":"#/components/schemas/CustomerResponseDto"}]},"purchaseCount":{"type":"number","description":"Count of purchase transactions in range.","example":4},"totalSpent":{"type":"string","description":"Sum of purchase prices in range, serialised as a string (bigint).","example":"12000000"},"timeSeries":{"description":"Gap-filled daily series.","type":"array","items":{"$ref":"#/components/schemas/CustomerTimeSeriesPointDto"}},"from":{"type":"string","description":"Start of the requested window (ISO-8601).","example":"2026-03-01T00:00:00.000Z"},"to":{"type":"string","description":"End of the requested window (ISO-8601).","example":"2026-05-30T23:59:59.000Z"}},"required":["customer","purchaseCount","totalSpent","timeSeries","from","to"]},"CustomerPurchaseHistoryItemDto":{"type":"object","properties":{"txId":{"type":"string","description":"Transaction ID.","example":"tx-1a2b3c"},"planId":{"type":"string","description":"Plan ID purchased.","example":"plan-7d8e9f"},"planName":{"type":"string","description":"Plan display name.","example":"Premium API access"},"price":{"type":"string","description":"Plan price paid, serialised as a string (bigint).","example":"12500000"},"createdAt":{"type":"string","description":"ISO-8601 timestamp the purchase was recorded.","example":"2026-05-15T14:30:00.000Z"}},"required":["txId","planId","planName","price","createdAt"]},"CustomerPurchaseHistoryResponseDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CustomerPurchaseHistoryItemDto"}},"total":{"type":"number","description":"Total purchase rows across all pages.","example":47}},"required":["items","total"]},"OrganizationActivityEventType":{"type":"string","enum":["member.invited","member.joined","member.role_changed","member.deactivated","member.reactivated","member.removed","invitation.revoked","invitation.expired","agent.created","plan.created","plan.updated","plan.purchased","customer.added","customer.blocked","customer.unblocked","subscription.upgraded","subscription.downgraded","subscription.canceled","subscription.lapsed","webhook.delivered","webhook.failed","apikey.created","apikey.revoked","credits.redeemed"],"description":"Event types this subscription should receive. Omit or pass an empty array to subscribe to all event types."},"CreateWebhookSubscriptionDto":{"type":"object","properties":{"url":{"type":"string","description":"Destination URL that receives the signed webhook POST. Must be an https:// URL in production (http:// is only accepted when the server explicitly allows it for development). The host must not resolve to a private, loopback, link-local, or cloud-metadata address (SSRF guard).","example":"https://example.com/hooks/nevermined","maxLength":2048},"eventTypes":{"type":"array","description":"Event types this subscription should receive. Omit or pass an empty array to subscribe to all event types.","example":["plan.purchased","customer.blocked"],"items":{"$ref":"#/components/schemas/OrganizationActivityEventType"}},"description":{"type":"string","description":"Optional human-readable label shown in the dashboard.","example":"Billing notifications"}},"required":["url"]},"UpdateWebhookSubscriptionDto":{"type":"object","properties":{"url":{"type":"string","description":"New destination URL. Subject to the same https:// and SSRF validation as on create.","example":"https://example.com/hooks/nevermined-v2","maxLength":2048},"eventTypes":{"type":"array","description":"Replacement list of event types. An empty array subscribes to all event types.","example":["plan.purchased"],"items":{"$ref":"#/components/schemas/OrganizationActivityEventType"}},"enabled":{"type":"boolean","description":"Enable or disable delivery. When false, the dispatcher skips this subscription.","example":true},"description":{"type":"string","description":"Updated human-readable label shown in the dashboard.","example":"Billing notifications (prod)"}}},"WebhookDeliveryStatus":{"type":"string","enum":["pending","in_flight","delivered","failed","dead"]},"RevenueAgentItemDto":{"type":"object","properties":{"agentId":{"type":"string","description":"Agent ID.","example":"did:nv:agent-1a2b3c"},"agentName":{"type":"string","description":"Human-readable agent name.","example":"Translation Agent"},"totalRevenue":{"type":"string","description":"Total revenue attributed to this agent, serialised as a string (bigint).","example":"4200000000"},"transactionCount":{"type":"number","description":"Number of revenue-generating transactions.","example":318}},"required":["agentId","agentName","totalRevenue","transactionCount"]},"RevenueResponseDto":{"type":"object","properties":{"items":{"description":"Per-agent revenue rows.","type":"array","items":{"$ref":"#/components/schemas/RevenueAgentItemDto"}},"totalRevenue":{"type":"string","description":"Aggregate revenue across all agents, serialised as a string (bigint).","example":"4200000000"}},"required":["items","totalRevenue"]},"MrrResponseDto":{"type":"object","properties":{"mrr":{"type":"string","description":"Monthly recurring revenue, serialised as a string (bigint).","example":"900000000"},"activeSubscriptions":{"type":"number","description":"Number of currently active subscriptions.","example":42}},"required":["mrr","activeSubscriptions"]},"PlanConsumptionItemDto":{"type":"object","properties":{"planId":{"type":"string","description":"Plan ID.","example":"plan-5d8f2a"},"planName":{"type":"string","description":"Human-readable plan name.","example":"Pro Monthly"},"creditsBurned":{"type":"string","description":"Total credits burned against this plan, serialised as a string (bigint).","example":"15000"},"uniqueUsers":{"type":"number","description":"Number of distinct users who burned credits.","example":27}},"required":["planId","planName","creditsBurned","uniqueUsers"]},"PlanConsumptionResponseDto":{"type":"object","properties":{"items":{"description":"Per-plan consumption rows.","type":"array","items":{"$ref":"#/components/schemas/PlanConsumptionItemDto"}}},"required":["items"]},"TopCustomerItemDto":{"type":"object","properties":{"customerId":{"type":"string","description":"Customer record ID.","example":"oc-7b1c3e9a"},"userId":{"type":"string","description":"Nevermined user ID of the customer.","example":"us-2f4a6c8e"},"totalSpent":{"type":"string","description":"Total amount the customer has spent, serialised as a string (bigint).","example":"125000000"},"firstSeenAt":{"type":"string","description":"ISO-8601 timestamp the customer was first observed.","example":"2026-01-15T09:30:00.000Z"},"lastActiveAt":{"type":"string","description":"ISO-8601 timestamp of the customer’s most recent activity.","example":"2026-05-20T14:05:00.000Z"}},"required":["customerId","userId","totalSpent","firstSeenAt","lastActiveAt"]},"TopCustomersResponseDto":{"type":"object","properties":{"items":{"description":"Top customers ordered by spend DESC.","type":"array","items":{"$ref":"#/components/schemas/TopCustomerItemDto"}},"totalCustomers":{"type":"number","description":"Total number of customers in the organization.","example":1342}},"required":["items","totalCustomers"]},"ConversionFunnelResponseDto":{"type":"object","properties":{"sessions":{"type":"number","description":"Number of sessions observed in the period.","example":5000},"purchases":{"type":"number","description":"Number of purchases observed in the period.","example":250},"conversionRate":{"type":"number","nullable":true,"description":"Conversion rate (purchases / sessions). `null` when no sessions were observed in the period — clients should render an empty state (\"No data yet\") rather than 0.","example":0.05}},"required":["sessions","purchases"]},"CreditsByMemberItemDto":{"type":"object","properties":{"memberId":{"type":"string","description":"Organization member ID.","example":"om-3c9d1f7a"},"memberAddress":{"type":"string","description":"Wallet address of the member.","example":"0x1234abcd5678ef901234abcd5678ef901234abcd"},"totalCreditsBurned":{"type":"string","description":"Total credits burned by this member, serialised as a string (bigint).","example":"3200"},"burnCount":{"type":"number","description":"Number of burn operations attributed to the member.","example":88},"lastBurnAt":{"type":"string","nullable":true,"description":"ISO-8601 timestamp of the member’s most recent burn, or `null` if none in the period.","example":"2026-05-18T11:42:00.000Z"}},"required":["memberId","memberAddress","totalCreditsBurned","burnCount"]},"CreditsByMemberResponseDto":{"type":"object","properties":{"items":{"description":"Per-member credit-burn attribution rows.","type":"array","items":{"$ref":"#/components/schemas/CreditsByMemberItemDto"}}},"required":["items"]},"DowngradeOrgSubscriptionDto":{"type":"object","properties":{"tier":{"type":"string","description":"Target tier for the downgrade. Premium is the only valid downgrade target.","enum":["Premium"],"example":"Premium"}},"required":["tier"]},"UpgradeOrgSubscriptionDto":{"type":"object","properties":{"tier":{"type":"string","description":"Target tier for the upgrade. Enterprise is the only valid in-place upgrade target.","enum":["Enterprise"],"example":"Enterprise"}},"required":["tier"]},"CreateOrgCheckoutDto":{"type":"object","properties":{"tier":{"type":"string","description":"Target tier to subscribe the organization to.","enum":["Premium","Enterprise"],"example":"Premium"},"currency":{"type":"string","description":"Currency for the purchase. Accepted for backward compatibility but currently ignored — checkout always resolves to USD.","enum":["USD","EUR","USDC","EURC"],"example":"USD"},"interval":{"type":"string","description":"Billing interval. Accepted for backward compatibility but currently ignored — checkout always resolves to a monthly interval.","enum":["month","year","one_shot"],"example":"month"}},"required":["tier"]},"ConfirmCryptoDto":{"type":"object","properties":{"txHash":{"type":"string","description":"Transaction hash of the on-chain ERC-20 transfer to verify (0x-prefixed, 32 bytes).","example":"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"catalogId":{"type":"string","description":"Catalog row id echoed back from the checkout paymentInstructions payload.","example":"catalog-premium-usdc-oneshot"}},"required":["txHash","catalogId"]},"TierCatalogRowDto":{"type":"object","properties":{"tier":{"type":"string","enum":["Premium","Enterprise","Lapsed","Other"],"example":"Premium"},"currency":{"type":"string","enum":["USD","EUR","USDC","EURC"],"example":"USD"},"interval":{"type":"string","enum":["month","year","one_shot"],"example":"month"},"source":{"type":"string","enum":["stripe_subscription","crypto_one_shot"],"example":"stripe_subscription"},"creditsPerCycle":{"type":"string","example":"1000000"},"durationSecs":{"type":"string","example":"2592000"},"priceMinorUnits":{"type":"number","example":25000},"stripeLookupKey":{"type":"object","example":"nvm_premium_usd_month","nullable":true},"neverminedPlanId":{"type":"string","example":"94985929696461581796777410069372531525722254393298455964755634838270184706412"}},"required":["tier","currency","interval","source","creditsPerCycle","durationSecs","priceMinorUnits","stripeLookupKey","neverminedPlanId"]},"TierCatalogResponseDto":{"type":"object","properties":{"catalog":{"type":"array","items":{"$ref":"#/components/schemas/TierCatalogRowDto"}}},"required":["catalog"]},"CreateWsSecretDto":{"type":"object","properties":{"label":{"type":"string","description":"Human-readable label for the secret, e.g. \"MacBook ops\".","maxLength":80,"example":"MacBook ops"}},"required":["label"]},"WsSecretResponseDto":{"type":"object","properties":{"id":{"type":"string","example":"rts-3f2b…"},"label":{"type":"string","example":"MacBook ops"},"secret":{"type":"string","description":"Plaintext secret — shown ONCE. Copy it now; it is never retrievable again.","example":"wss_J8x…"},"lastFour":{"type":"string","description":"Last 4 chars (the dashboard masks it as wss_…XXXX).","example":"a1B2"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","label","secret","lastFour","createdAt"]},"WsSecretSummaryDto":{"type":"object","properties":{"id":{"type":"string","example":"rts-3f2b…"},"label":{"type":"string","example":"MacBook ops"},"lastFour":{"type":"string","example":"a1B2"},"createdAt":{"format":"date-time","type":"string"},"lastUsedAt":{"format":"date-time","type":"string","nullable":true},"status":{"type":"string","enum":["active","revoked"],"example":"active"}},"required":["id","label","lastFour","createdAt","lastUsedAt","status"]},"CreateEmailChallengeDto":{"type":"object","properties":{"userId":{"type":"string","example":"us-01234","description":"The unique identifier of the user associated to the email"},"email":{"type":"string","example":"john.doe@example.com","description":"The email address of the user to validate"}},"required":["userId","email"]},"EmailChallengeEntity":{"type":"object","properties":{}},"SearchEmailChallengesDto":{"type":"object","properties":{"id":{"type":"string","example":"em-abcd","description":"The email challenge id reference"},"userId":{"type":"string","example":"us-01234","description":"The unique identifier of the user associated to the email"},"email":{"type":"string","example":"john.doe@example.com","description":"The email address of the user to validate"},"status":{"type":"string","enum":["Pending","Validated","Failed"],"example":"Validated","description":"The validation status"},"page":{"type":"number","example":1,"description":"Page of the email challenges list"},"offset":{"type":"number","example":20,"description":"Page offset of the challenges list"}},"required":["id","userId","email","status","page","offset"]},"EmailChallengesPageDto":{"type":"object","properties":{"totalResults":{"type":"number","example":137,"description":"Total number of results found"},"page":{"type":"number","example":1,"description":"Page of the email challenges list"},"offset":{"type":"number","example":20,"description":"Page offset of the email challenges list"},"challenges":{"description":"List email challenges","example":[{"id":"em-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d","userId":"jifdwqejidqwa9okdasodkaso","email":"john.doe@example.com","status":"pending","retries":0,"createdAt":"2026-05-29T10:00:00.000Z","updatedAt":"2026-05-29T10:00:00.000Z"}],"type":"array","items":{"type":"string"}}},"required":["totalResults","page","offset","challenges"]},"ValidateEmailChallengeDto":{"type":"object","properties":{"id":{"type":"string","example":"em-abcd","description":"The email challenge id reference"},"userId":{"type":"string","example":"us-01234","description":"The unique identifier of the user associated to the email"},"email":{"type":"string","example":"john.doe@example.com","description":"The email address of the user to validate"},"challenge":{"type":"string","example":"123456","description":"The email challenge sent by email"}},"required":["id","userId","email","challenge"]},"ValidationChallengeResultDto":{"type":"object","properties":{"id":{"type":"string","example":"em-abcd","description":"The email challenge id reference"},"userId":{"type":"string","example":"us-01234","description":"The unique identifier of the user associated to the email"},"email":{"type":"string","example":"john.doe@example.com","description":"The email address of the user to validate"},"status":{"type":"string","enum":["Pending","Validated","Failed"],"example":"Validated","description":"The validation status"},"message":{"type":"string","example":"The email has been validated","description":"Message describing the validation status result"}},"required":["id","userId","email","status","message"]},"NotificationEntity":{"type":"object","properties":{}},"SearchNotificationsDto":{"type":"object","properties":{"id":{"type":"string","example":"nid-99970808-0a86-45c0-ac7b-7917d45961a6","description":"Unique identifier of the notification"},"notificationType":{"type":"string","example":"purchase","description":"Type of notification"},"receiver":{"type":"string","example":"uid-99970808-0a86-45c0-ac7b-7917d45961a6","description":"Unique identifier of the user receiving the notification"},"originator":{"type":"string","example":"uid-99970808-0a86-45c0-ac7b-7917d45961a6","description":"Unique identifier of the user originating the notification"},"readStatus":{"type":"string","enum":["Pending","Read","Deleted","Other"],"example":"Pending","description":"Read status of the notification"},"deliveryStatus":{"type":"string","enum":["Pending","Sent","Failed","NotRequired","Skipped","Other"],"example":"Pending","description":"Delivery status of the notification"},"title":{"type":"string","example":"Your subscription has been purchased","description":"Title of the notification"},"did":{"type":"string","example":"112715147946069636715282379221777166315490656636137176534659157141164168807749","description":"Identifier of the asset related to the notification"},"messageTemplate":{"type":"string","example":"abcd1234","description":"Identifier of the template used to build the message of the notification"},"deliveryRetries":{"type":"number","example":"2","description":"Number of times the notification has been retried to be delivered"},"page":{"type":"number","example":1,"description":"Page of the notifications list"},"offset":{"type":"number","example":20,"description":"Page offset of the notifications list"}},"required":["id","notificationType","receiver","originator","readStatus","deliveryStatus","title","did","messageTemplate","deliveryRetries","page","offset"]},"NotificationsPageDto":{"type":"object","properties":{"totalResults":{"type":"number","example":137,"description":"Total number of results found"},"page":{"type":"number","example":1,"description":"Page of the notifications list"},"totalPages":{"type":"number","example":20,"description":"Total number of pages"},"results":{"description":"List notifications","example":[{"id":"nid-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d","notificationType":"other","receiver":"0x37BB53e3d293494DE59fBe1FF78500423dcFd43B","originator":"nevermined","readStatus":"pending","deliveryStatus":"sent","title":"Your plan was purchased","body":"A consumer just purchased credits on your plan.","did":"did:nv:1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d","link":"https://nevermined.app/notifications/nid-1a2b3c4d","messageTemplate":"plan-purchased","deliveryRetries":0,"deliveryMessage":"","createdAt":"2026-05-29T10:00:00.000Z","updatedAt":"2026-05-29T10:00:00.000Z"}],"type":"array","items":{"type":"string"}}},"required":["totalResults","page","totalPages","results"]},"NotificationReadStatus":{"type":"string","enum":["Pending","Read","Deleted","Other"]},"_NvmAPIResultDto":{"type":"object","properties":{"success":{"type":"boolean","example":true,"description":"Indicates whether the API call was successful"},"message":{"type":"string","example":"Successfully minted","description":"Message describing the result of the API call"},"txHash":{"type":"string","example":"0x923812b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef12345678","description":"Blockchain transaction hash associated with the API call"},"httpStatus":{"type":"number","example":200,"description":"HTTP status code of the API response"},"data":{"type":"object","description":"Additional parameters related to the API call","additionalProperties":true},"when":{"format":"date-time","type":"string","description":"Timestamp when the API call was made"}},"required":["success","message","txHash","httpStatus","data","when"]},"CreatePaypalCheckoutDto":{"type":"object","properties":{"nonce":{"type":"string","example":"fake-valid-nonce","description":"Braintree payment method nonce for PayPal"},"planId":{"format":"int64","type":"integer","example":"43298432984329","description":"Unique identifier of the payment plan being purchased"},"returnUrlQueryParams":{"type":"object","description":"Return URL query parameters"},"nvmExport":{"type":"string","example":"true","description":"Export NVM API key","default":false}},"required":["nonce","planId","returnUrlQueryParams","nvmExport"]},"CreateStripeAccountDto":{"type":"object","properties":{"stripeAccountId":{"type":"string","example":"acct_1O4KfNBYvSRKcV42","description":"Unique identifier of stripe account"},"userEmail":{"type":"string","example":"john.doe@example.com","description":"User email. If given it wont be asked by Stripe account creation"},"userCountryCode":{"type":"string","example":"GB","description":"User country code (ISO 3166-1 alpha-2). It will be used by Stripe for account creation"},"returnUrl":{"type":"string","example":"https://example.com","description":"Return URL"}},"required":["stripeAccountId","userEmail","userCountryCode","returnUrl"]},"StripeAccountBalanceDto":{"type":"object","properties":{"balance":{"type":"object","description":"Account balance by currency. Each currency (USD, EUR, GBP, etc.) maps to the available balance in cents/pence","example":{"usd":15000,"eur":12500,"gbp":10000}}},"required":["balance"]},"CreateStripePaymentIntentDto":{"type":"object","properties":{"planId":{"format":"int64","type":"integer","example":"43298432984329","description":"Unique identifier of the payment plan being purchased"},"language":{"type":"string","example":"en","description":"Language of the app","default":"en"},"sessionId":{"type":"string","example":"39293121O4KfNBYvSRKcV42","description":"Unique identifier of the checkout session"},"nvmExport":{"type":"string","example":"true","description":"Export NVM API key","default":false},"returnUrlQueryParams":{"type":"object","description":"Return URL query parameters passed back after payment completion","example":{"source":"webapp","feature":"premium-plan"}},"email":{"type":"string","example":"john.doe@example.com","description":"Customer email address for Stripe payment intent"},"name":{"type":"string","example":"John Doe","description":"Customer name for Stripe payment intent"}},"required":["planId","language","sessionId","nvmExport"]},"CreateStripeSubscriptionDto":{"type":"object","properties":{"planId":{"format":"int64","type":"integer","example":"43298432984329","description":"Unique identifier of the payment plan being purchased"},"priceId":{"type":"string","example":"price_1O4KfNBYvSRKcV42ABC123","description":"Stripe price ID for the subscription plan"},"paymentMethodId":{"type":"string","example":"pm_1O4KfNBYvSRKcV42XYZ789","description":"Stripe payment method ID to use for the subscription"},"email":{"type":"string","example":"john.doe@example.com","description":"Customer email address"},"name":{"type":"string","example":"John Doe","description":"Customer name"},"sessionId":{"type":"string","example":"39293121O4KfNBYvSRKcV42","description":"Unique identifier of the checkout session"},"returnUrl":{"type":"string","example":"https://example.com/payment-success","description":"URL to redirect after subscription creation"},"language":{"type":"string","example":"en","description":"Language preference for the subscription flow","default":"en"},"returnUrlQueryParams":{"type":"object","description":"Return URL query parameters passed back after subscription creation","example":{"source":"webapp","tier":"premium"}},"nvmExport":{"type":"string","example":"true","description":"Export NVM API key","default":false},"orgId":{"type":"string","example":"org-e1b97e59-56e3-4514-8af1-3745b8fe5b57","description":"Target org for an organization tier upgrade. When set, the subscription is stamped with `metadata.orgId` + `metadata.orgTierSubscription=true` so the Phase 3 webhook handler upgrades the exact org the user is viewing instead of falling back to their first/oldest org."},"intent":{"type":"string","example":"create","enum":["create","upgrade"],"description":"Org-tier checkout intent. `create` provisions a NEW org on successful payment (used by the \"Create new organization\" dialog so multi-org users actually get a second org). `upgrade` (or omitted) preserves the legacy upgrade-existing-org behaviour. Only honored on org-tier plans; ignored for agent-plan checkouts."},"newOrgName":{"type":"string","example":"Acme Labs","description":"Display name for the org provisioned by an `intent=create` checkout. Ignored on upgrades. Trimmed server-side; when blank the org is created with the caller profile default name."}},"required":["planId"]},"PaymentIntentMetadataDto":{"type":"object","properties":{"metadata":{"type":"object","description":"PaymentIntent metadata","example":{"planId":"123456789","userId":"user_123","sessionId":"session_456","returnUrl":"https://example.com/return"}},"paymentIntentId":{"type":"string","description":"PaymentIntent ID","example":"pi_1234567890abcdef"},"status":{"type":"string","description":"PaymentIntent status","example":"succeeded","enum":["requires_payment_method","requires_confirmation","requires_action","processing","requires_capture","canceled","succeeded"]}},"required":["metadata","paymentIntentId","status"]},"EnrollCardDto":{"type":"object","properties":{"vgsCardNumber":{"type":"string","description":"VGS alias for the card number (tokenized by VGS Collect)","example":"tok_sandbox_abc123"},"vgsExpDate":{"type":"string","description":"VGS alias for the card expiration date (tokenized by VGS Collect)","example":"tok_sandbox_exp456"},"vgsCvc":{"type":"string","description":"VGS alias for the card CVC (tokenized by VGS Collect)","example":"tok_sandbox_cvc789"},"alias":{"type":"string","description":"Optional friendly name for the card","example":"My Card"},"allowedApiKeyIds":{"description":"Array of NVM API Key skId values allowed to use this card. Null or empty = any key can use it.","example":["sk-abc123","sk-def456"],"nullable":true,"type":"array","items":{"type":"string"}}},"required":["vgsCardNumber","vgsExpDate","vgsCvc"]},"FinalizeEnrollmentDto":{"type":"object","properties":{"setupIntentId":{"type":"string","description":"Stripe SetupIntent ID from the confirmed card setup","example":"seti_1abc123"},"alias":{"type":"string","description":"Optional friendly name for the card","example":"My Card"},"allowedApiKeyIds":{"description":"Array of NVM API Key skId values allowed to use this card. Null or empty = any key can use it.","example":["sk-abc123","sk-def456"],"nullable":true,"type":"array","items":{"type":"string"}}},"required":["setupIntentId"]},"EnrollBraintreeDto":{"type":"object","properties":{"nonce":{"type":"string","description":"Payment method nonce from Braintree Drop-in UI","example":"tokencc_bf_abc123_xyz"},"alias":{"type":"string","description":"Optional friendly name for the payment method","example":"My Visa Card"},"allowedApiKeyIds":{"description":"Array of NVM API Key skId values allowed to use this payment method. Null or empty = any key can use it.","example":["sk-abc123","sk-def456"],"nullable":true,"type":"array","items":{"type":"string"}}},"required":["nonce"]},"EnrollVisaDto":{"type":"object","properties":{"cardId":{"type":"string","description":"CMP card identifier (`CRD…`) returned by VGS Collect `form.createCard()`. The browser performs the card creation directly against CMP via VGS-internal routing; we only receive the resulting card ID.","example":"CRDrX94aaaJz7oTFy2i13964k"},"alias":{"type":"string","description":"Optional friendly name for the payment method","example":"My Visa Card"},"allowedApiKeyIds":{"description":"Array of NVM API Key skId values allowed to use this payment method. Null or empty = any key can use it.","example":["sk-abc123","sk-def456"],"nullable":true,"type":"array","items":{"type":"string"}},"last4":{"type":"string","description":"Last 4 digits of the card from VGS Collect createCard response","example":"1387"},"brand":{"type":"string","description":"Card brand from VGS Collect createCard response (e.g. \"visa\", \"mastercard\")","example":"visa"},"expMonth":{"type":"number","description":"Card expiry month (1-12)","example":12},"expYear":{"type":"number","description":"Card expiry year (4-digit, 2000-2099)","example":2027}},"required":["cardId"]},"CreateDelegationDto":{"type":"object","properties":{"provider":{"type":"string","description":"Payment provider type","example":"stripe","default":"stripe","enum":["stripe","erc4337","braintree","visa"]},"providerPaymentMethodId":{"type":"string","description":"Payment-method identifier from the provider. For stripe / braintree this is the saved card; for visa this is the VGS agentic-token id returned by enrollment. Required for these providers; ignored for erc4337.","example":"pm_1Abc2Def3Ghi4Jkl"},"consumerPrompt":{"type":"string","description":"Visa-only: human-readable approval prompt shown to the user during VGS Agentic Auth device binding. Required when provider=visa.","example":"Allow up to USD 50.00 over 5 transactions"},"assuranceData":{"type":"object","description":"Visa-only: opaque assurance payload from the VGS Agentic Auth browser SDK after FIDO/OTP device binding. Required when provider=visa."},"spendingLimitCents":{"type":"number","description":"Maximum spending limit in cents (smallest currency unit)","example":10000},"durationSecs":{"type":"number","description":"Duration of the delegation in seconds","example":604800},"currency":{"type":"string","description":"Currency code (lowercase)","example":"usd","default":"usd","enum":["usd","eur","usdc","eurc"]},"planId":{"type":"string","description":"Optional plan ID to restrict this delegation to","example":"123456789"},"merchantAccountId":{"type":"string","description":"Optional merchant Stripe account ID to restrict payments to","example":"acct_1Abc2Def3Ghi"},"maxTransactions":{"type":"number","description":"Maximum number of transactions allowed (null = unlimited)","example":50},"apiKeyId":{"type":"string","description":"Optional API Key ID (skId) to restrict this delegation to","example":"sk-abc123"}},"required":["spendingLimitCents","durationSecs"]},"CreateDelegationResponseDto":{"type":"object","properties":{"delegationId":{"type":"string","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"delegationToken":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR...","nullable":true,"description":"Signed JWT for fiat-backed delegations (stripe/braintree). Omitted for crypto (erc4337) flows where the signed delegation is held client-side."}},"required":["delegationId"]},"DelegationSummaryDto":{"type":"object","properties":{"delegationId":{"type":"string","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"provider":{"type":"string","example":"stripe"},"providerPaymentMethodId":{"type":"string","example":"pm_1Abc2Def3Ghi4Jkl"},"status":{"type":"string","example":"Active","enum":["Active","Revoked","Expired","Exhausted"]},"spendingLimitCents":{"type":"string","example":"10000"},"amountSpentCents":{"type":"string","example":"2500"},"remainingBudgetCents":{"type":"string","example":"7500"},"currency":{"type":"string","example":"usd"},"transactionCount":{"type":"number","example":12},"expiresAt":{"format":"date-time","type":"string","example":"2026-02-20T00:00:00Z"},"createdAt":{"format":"date-time","type":"string","example":"2026-02-13T10:30:00Z"},"apiKeyId":{"type":"object","example":"sk-abc123","nullable":true,"description":"NVM API Key ID restricted to this delegation. Null = any key can use it."}},"required":["delegationId","provider","providerPaymentMethodId","status","spendingLimitCents","amountSpentCents","remainingBudgetCents","currency","transactionCount","expiresAt","createdAt"]},"DelegationListDto":{"type":"object","properties":{"totalResults":{"type":"number"},"page":{"type":"number"},"offset":{"type":"number"},"delegations":{"type":"array","items":{"$ref":"#/components/schemas/DelegationSummaryDto"}}},"required":["totalResults","page","offset","delegations"]},"DelegationDetailsDto":{"type":"object","properties":{"delegationId":{"type":"string","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"provider":{"type":"string","example":"stripe"},"providerPaymentMethodId":{"type":"string","example":"pm_1Abc2Def3Ghi4Jkl"},"status":{"type":"string","example":"Active","enum":["Active","Revoked","Expired","Exhausted"]},"spendingLimitCents":{"type":"string","example":"10000"},"amountSpentCents":{"type":"string","example":"2500"},"remainingBudgetCents":{"type":"string","example":"7500"},"currency":{"type":"string","example":"usd"},"transactionCount":{"type":"number","example":12},"expiresAt":{"format":"date-time","type":"string","example":"2026-02-20T00:00:00Z"},"createdAt":{"format":"date-time","type":"string","example":"2026-02-13T10:30:00Z"},"apiKeyId":{"type":"object","example":"sk-abc123","nullable":true,"description":"NVM API Key ID restricted to this delegation. Null = any key can use it."},"planId":{"type":"object","example":"123456789","nullable":true},"merchantAccountId":{"type":"object","example":"acct_1Abc2Def3Ghi","nullable":true},"maxTransactions":{"type":"object","example":50,"nullable":true},"lastUsedAt":{"type":"object","example":"2026-02-13T14:00:00Z","nullable":true}},"required":["delegationId","provider","providerPaymentMethodId","status","spendingLimitCents","amountSpentCents","remainingBudgetCents","currency","transactionCount","expiresAt","createdAt","planId","merchantAccountId","maxTransactions","lastUsedAt"]},"DelegationTransactionDto":{"type":"object","properties":{"id":{"type":"string","example":"tx-uuid"},"delegationId":{"type":"string","example":"delegation-uuid"},"providerTransactionId":{"type":"string","example":"pi_1Abc2Def3Ghi4Jkl"},"amountCents":{"type":"string","example":"1000"},"currency":{"type":"string","example":"usd"},"status":{"type":"string","example":"succeeded"},"failureReason":{"type":"object","example":null,"nullable":true},"createdAt":{"format":"date-time","type":"string","example":"2026-02-13T14:00:00Z"}},"required":["id","delegationId","providerTransactionId","amountCents","currency","status","failureReason","createdAt"]},"DelegationTransactionListDto":{"type":"object","properties":{"totalResults":{"type":"number"},"page":{"type":"number"},"offset":{"type":"number"},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/DelegationTransactionDto"}}},"required":["totalResults","page","offset","transactions"]},"DeploymentInfoDto":{"type":"object","properties":{"version":{"type":"string","example":"1.3.2","description":"Contract deployment version"},"contracts":{"type":"object","example":{"PayAsYouGoTemplate":"0x5e852077b30099106Aa65B4d329FFF9b5C9a8e7C","FixedPaymentTemplate":"0x32037D176558Eb02f6980eFA14bde14B0C61d059"},"description":"Contract addresses"}},"required":["contracts"]},"GetInfoDto":{"type":"object","properties":{"APIversion":{"type":"string","example":"1.0.4","description":"Marketplace API Version"},"docs":{"type":"string","example":"http://localhost:3100/api/v1/docs","description":"API docs url"},"provider-address":{"type":"string","example":"0x068Ed00cF0441e4829D9784fCBe7b9e26D4BD8d0","description":"Provider address"},"ecdsa-public-key":{"type":"string","example":"http://localhost:3100/api/v1/docs","description":"ecdsa public key"},"environment":{"type":"string","example":"local","description":"Environment"},"networkId":{"type":"number","example":"8453","description":"Network ID"},"networkName":{"type":"string","example":"base","description":"Network Name"},"organizationUpgradePlan":{"type":"string","example":"12345678901234567890","description":"Plan ID for upgrading to organization"},"deployment":{"description":"Contract deployment information","allOf":[{"$ref":"#/components/schemas/DeploymentInfoDto"}]}},"required":["APIversion","docs","provider-address","ecdsa-public-key","environment","networkId","networkName","deployment"]},"MetadataMainAttributesPlanDto":{"type":"object","properties":{"name":{"type":"string","example":"Premium AI Agent Access","description":"Name of the agent or payment plan (required)"},"author":{"type":"string","example":"Nevermined AI Inc.","description":"Author or creator of the agent or plan (optional)"},"license":{"type":"string","example":"MIT","description":"License type (e.g., MIT, Apache-2.0, Proprietary) (optional)"},"tags":{"example":["AI","Assistant","Personal","GPT"],"description":"Tags associated with the agent or plan for categorization and search","type":"array","items":{"type":"string"}},"dateCreated":{"type":"string","example":"2025-01-15T10:00:00Z","description":"Date of creation of the agent or plan (ISO 8601 format)"},"description":{"type":"string","example":"This plan provides access to the agent services.","description":"Description of the plan"}},"required":["name","author","license","tags"]},"PricingConfigDto":{"type":"object","properties":{"isCrypto":{"type":"boolean","example":true,"description":"Indicates whether the price is in cryptocurrency or fiat","default":true},"amounts":{"example":["1000000000000000000","200000000000000000"],"description":"The distributions of amounts to be paid for the plan. Amounts are provided as strings representing wei values and converted to BigInt internally.","type":"array","items":{"type":"string"}},"receivers":{"example":["0x731E7a35DDBB7d2b168D16824B371034f0DD0024","0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"],"description":"The distributions of receivers of the payments of the plan. Array of Ethereum addresses that will receive the payment amounts.","type":"array","items":{"type":"string"}},"tokenAddress":{"type":"string","example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","description":"if the price type is fixed price, the address of the token to be used"},"externalPriceAddress":{"type":"string","example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","description":"If the price type is smart contract price, the address of the smart contract that calculates the price"},"feeController":{"type":"string","example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","description":"The address of the fee controller contract, if any"},"templateAddress":{"type":"string","example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","description":"If is not the zero address, the Nevermined template contract address associated with the plan"}},"required":["isCrypto","amounts","receivers","tokenAddress","externalPriceAddress","feeController","templateAddress"]},"CreditsConfigDto":{"type":"object","properties":{"isRedemptionAmountFixed":{"type":"boolean","example":true,"description":"Indicates if the redemption amount is fixed (true) or dynamic (false)","default":true},"redemptionType":{"type":"number","enum":[0,1,2,3,4],"example":1,"description":"How the credits can be redeemed","default":1},"onchainMirror":{"type":"boolean","example":false,"description":"Whether credits mint/burn should be mirrored on-chain in addition to the off-chain ledger. Defaults to `false` (off-chain only — the cheap path; see nvm-monorepo#1274).","default":false},"amount":{"format":"int64","type":"integer","example":"1000","description":"The amount of credits that are granted when purchasing the plan. If the plan is EXPIRABLE, the amount should be 1"},"minAmount":{"format":"int64","type":"integer","example":"1","description":"The minimum number of credits redeemed when using the plan","default":"1"},"maxAmount":{"format":"int64","type":"integer","example":"1","description":"The maximum number of credits redeemed when using the plan. If the plan is fixed, it should be the same amount than minAmount. If the plan is DYNAMIC, it refers to the max number of credits that can be burned per request"},"durationSecs":{"format":"int64","type":"integer","example":"86400","description":"If credits are EXPIRABLE, the duration of the credits in seconds","default":"0"},"nftAddress":{"type":"string","example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","description":"The address of the contract that will be used to store the credits"}},"required":["isRedemptionAmountFixed","redemptionType","amount","minAmount","maxAmount","durationSecs","nftAddress"]},"RegisterPaymentPlanDto":{"type":"object","properties":{"metadataAttributes":{"description":"Metadata attributes for the payment plan (name, description, author, etc.)","allOf":[{"$ref":"#/components/schemas/MetadataMainAttributesPlanDto"}]},"priceConfig":{"description":"Definition of the price configuration for a plan","allOf":[{"$ref":"#/components/schemas/PricingConfigDto"}]},"creditsConfig":{"description":"Definition of the credits configuration for a plan","allOf":[{"$ref":"#/components/schemas/CreditsConfigDto"}]},"nonce":{"format":"int64","type":"integer","example":"3494494882712371273123737237","description":"nonce used to register the payment plan"},"isTrialPlan":{"type":"boolean","example":false,"description":"Indicates if the plan is a trial plan and only can be purchased once","default":false},"recurringSubscription":{"type":"boolean","example":false,"description":"Indicates if the plan is a recurring subscription","default":false},"accessLimit":{"type":"string","example":"credits","description":"Type of access limit for the plan","enum":["credits","time"]},"fiatPaymentProvider":{"type":"string","example":"stripe","description":"Payment provider for the plan","enum":["stripe","braintree"]},"currency":{"type":"string","example":"USD","description":"Currency for the plan (USD, EUR, USDC, EURC)","enum":["USD","EUR","USDC","EURC"]},"appId":{"type":"string","example":"1","description":"The app id"},"orgId":{"type":"object","example":"org-0af722ec-7905-4d14-bca0-1b9d5c95dc96","description":"Workspace org to tag the plan with. Real ids are prefixed `org-`. When set, the user must be an active member of that org or 403 is returned. Overrides any value resolved from the X-Current-Org-Id header."}},"required":["metadataAttributes","priceConfig","creditsConfig","nonce","isTrialPlan","recurringSubscription","accessLimit","appId"]},"MetadataMainAttributesAgentDto":{"type":"object","properties":{"name":{"type":"string","example":"Premium AI Agent Access","description":"Name of the agent or payment plan (required)"},"author":{"type":"string","example":"Nevermined AI Inc.","description":"Author or creator of the agent or plan (optional)"},"license":{"type":"string","example":"MIT","description":"License type (e.g., MIT, Apache-2.0, Proprietary) (optional)"},"tags":{"example":["AI","Assistant","Personal","GPT"],"description":"Tags associated with the agent or plan for categorization and search","type":"array","items":{"type":"string"}},"dateCreated":{"type":"string","example":"2025-01-15T10:00:00Z","description":"Date of creation of the agent or plan (ISO 8601 format)"},"description":{"type":"string","example":"This agent is a personal assistant that helps you with your daily tasks.","description":"Description of the agent"}},"required":["name","author","license","tags","description"]},"AgentAPIAttributesDto":{"type":"object","properties":{"endpoints":{"type":"array","example":[{"POST":"https://myagent.ai/api/v1/agents/(.*)/tasks"},{"GET":"https://myagent.ai/api/v1/agents/(.*)/status"}],"description":"Optional allowlist of protected endpoints exposed by the agent API. When provided, x402 verify enforces this list as defense-in-depth (Additional Security). When omitted, requests are not gated by an allowlist — the Payments library handles per-route gating."},"openEndpoints":{"example":["https://myagent.ai/docs","https://myagent.ai/api-docs","https://myagent.ai/health"],"description":"List of endpoints that are open (they do not require a plan to access). Typically used for API documentation, health checks, etc.","type":"array","items":{"type":"string"}},"agentDefinitionUrl":{"type":"string","example":"https://myagent.ai/openapi.json","description":"Optional URL to a discoverable agent definition (OpenAPI spec, MCP Manifest, or A2A agent card). Used for documentation/discovery only — not consumed at runtime by the Nevermined platform."},"authType":{"type":"string","enum":["none","basic","bearer","oauth"],"example":"bearer","description":"API authentication type"},"username":{"type":"string","example":"admin","description":"If the authentication type is basic, the username to be used"},"password":{"type":"string","example":"password","description":"If the authentication type is basic, the password to be used"},"token":{"type":"string","example":"kdjaskjdaskjdksajdkas","description":"The bearer token to be used if the authentication type is bearer"}},"required":["openEndpoints","authType","username","password","token"]},"RegisterAgentDto":{"type":"object","properties":{"metadataAttributes":{"description":"Metadata attributes for the agent (name, description, author, tags, etc.)","allOf":[{"$ref":"#/components/schemas/MetadataMainAttributesAgentDto"}]},"agentApiAttributes":{"description":"Definition of the Agent API","allOf":[{"$ref":"#/components/schemas/AgentAPIAttributesDto"}]},"plans":{"example":["43298432984329","12345678901234"],"description":"Array of payment plan IDs to associate with the agent (optional). Plan IDs are BigInt values provided as strings.","type":"array","items":{"type":"string"}},"orgId":{"type":"object","example":"org-0af722ec-7905-4d14-bca0-1b9d5c95dc96","description":"Workspace org to tag the agent with. Real ids are prefixed `org-`. When set, the user must be an active member of that org or 403 is returned. Overrides any value resolved from the X-Current-Org-Id header."}},"required":["metadataAttributes","agentApiAttributes","plans"]},"RegisterAgentAndPlanDto":{"type":"object","properties":{"plan":{"description":"Definition of the payment plan","allOf":[{"$ref":"#/components/schemas/RegisterPaymentPlanDto"}]},"agent":{"description":"Definition of the agent","allOf":[{"$ref":"#/components/schemas/RegisterAgentDto"}]}},"required":["plan","agent"]},"MintPlanDto":{"type":"object","properties":{"planId":{"format":"int64","type":"integer","example":"43298432984329","description":"Unique identifier of the payment plan. Provided as a string and converted to BigInt internally."},"creditsReceiver":{"type":"string","example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","description":"The Ethereum address of the account that will receive the minted credits (checksummed, 0x-prefixed)"},"amount":{"format":"int64","type":"integer","example":"150","description":"The number of credits to be minted. Provided as a string and converted to BigInt internally."}},"required":["planId","creditsReceiver","amount"]},"MintPlanExpirableDto":{"type":"object","properties":{"planId":{"format":"int64","type":"integer","example":"43298432984329","description":"Unique identifier of the payment plan. Provided as a string and converted to BigInt internally."},"creditsReceiver":{"type":"string","example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","description":"The Ethereum address of the account that will receive the minted credits (checksummed, 0x-prefixed)"},"amount":{"format":"int64","type":"integer","example":"150","description":"The number of credits to be minted. Provided as a string and converted to BigInt internally."},"duration":{"format":"int64","type":"integer","example":86400,"description":"The duration of the expirable credits in seconds (e.g., 86400 for 24 hours). Provided as a number or string and converted to BigInt internally.","default":0}},"required":["planId","creditsReceiver","amount","duration"]},"UpdateAgentDto":{"type":"object","properties":{"metadataAttributes":{"description":"Updated metadata attributes for the agent (name, description, author, tags, etc.)","allOf":[{"$ref":"#/components/schemas/MetadataMainAttributesAgentDto"}]},"agentApiAttributes":{"description":"Updated API configuration for the agent (endpoints, authentication, OpenAPI definition URL)","allOf":[{"$ref":"#/components/schemas/AgentAPIAttributesDto"}]}},"required":["metadataAttributes","agentApiAttributes"]},"PaymentPlanDto":{"type":"object","properties":{"planId":{"format":"int64","type":"integer","example":"43298432984329","description":"Unique identifier of the payment plan"},"owner":{"type":"string","example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","description":"The owner of the payment plan"},"priceConfig":{"description":"Definition of the price configuration for a plan","allOf":[{"$ref":"#/components/schemas/PricingConfigDto"}]},"creditsConfig":{"description":"Definition of the credits configuration for a plan","allOf":[{"$ref":"#/components/schemas/CreditsConfigDto"}]},"creditsNftAddress":{"type":"string","example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","description":"The address of the contract that will be used to store the credits"},"lastUpdated":{"format":"date-time","type":"string","example":"2025-01-15T14:30:00Z","description":"When was the last time the plan was updated (ISO 8601 format)"}},"required":["planId","owner","priceConfig","creditsConfig","creditsNftAddress","lastUpdated"]},"PaginatedPaymentPlansDto":{"type":"object","properties":{"total":{"type":"number","description":"Total number of payment plans matching the query","example":42},"page":{"type":"number","description":"Current page number (0-indexed)","example":0},"offset":{"type":"number","description":"Number of items skipped","example":0},"plans":{"description":"Array of payment plan objects for the current page","type":"array","items":{"$ref":"#/components/schemas/PaymentPlanDto"}}},"required":["total","page","offset","plans"]},"AgentDto":{"type":"object","properties":{"did":{"type":"string","example":"112715147946069636715282379221777166315490656636137176534659157141164168807749","description":"Unique identifier of the agent"},"metadataUrl":{"type":"string","example":"https://example.com/metadata","description":"URL of the metadata associated with the agent"},"plans":{"example":["43298432984329","12345678901234"],"description":"Array of payment plan IDs associated with the agent. Plan IDs are BigInt values represented as strings.","type":"array","items":{"type":"string"}},"lastUpdated":{"format":"date-time","type":"string","example":"2025-01-15T14:30:00Z","description":"When was the last time the agent was updated (ISO 8601 format)"}},"required":["did","metadataUrl","plans","lastUpdated"]},"PaginatedAgentsDto":{"type":"object","properties":{"total":{"type":"number","description":"Total number of agents matching the query","example":25},"page":{"type":"number","description":"Current page number (0-indexed)","example":0},"offset":{"type":"number","description":"Number of items skipped","example":0},"agents":{"description":"Array of agent objects for the current page","type":"array","items":{"$ref":"#/components/schemas/AgentDto"}}},"required":["total","page","offset","agents"]},"TrackAgentSubTaskDto":{"type":"object","properties":{"agentRequestId":{"type":"string","description":"The unique identifier of the access transaction. This id is returned by the initializeAgentRequest method.","example":"atx-12345"},"creditsToRedeem":{"type":"number","description":"The number of credits burned in this agent sub task.","example":5,"default":0},"tag":{"type":"string","description":"A tag to categorize this agent sub task.","example":"high-priority"},"description":{"type":"string","description":"A description of this agent sub task.","example":"Processing high-priority data request"},"status":{"type":"string","enum":["Success","Failure","Pending","In_Progress"],"description":"The status of the agent sub task.","example":"Success"}},"required":["agentRequestId"]},"InitializeAgentRequestDto":{"type":"object","properties":{"accessToken":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","description":"Access token (JWT) that grants permission to query the agent. Obtained from the Protocol API."},"endpoint":{"type":"string","example":"https://myagent.ai/api/v1/agents/abc123/tasks","description":"The full URL of the agent endpoint being requested by the subscriber"},"httpVerb":{"type":"string","example":"POST","description":"The HTTP method used to call the endpoint","enum":["GET","POST","PUT","DELETE","PATCH"]},"batch":{"type":"boolean","example":false,"description":"Whether the request is a batch request (optional, defaults to false)","default":false}},"required":["accessToken","endpoint","httpVerb"]},"PaymentPlanBalanceDto":{"type":"object","properties":{"planId":{"format":"int64","type":"integer","example":"43298432984329","description":"Unique identifier of the payment plan"},"planName":{"type":"string","example":"Plan Name","description":"Name of the payment plan"},"planType":{"type":"string","enum":["expirable","credits"],"example":"expirable","description":"Indicates if the plan is a time or credits plan"},"isSubscriber":{"type":"boolean","example":true,"description":"Indicates if the address is an active subscriber of the plan"},"holderAddress":{"type":"object","example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","description":"The address of the account that holds the credits"},"creditsContract":{"type":"object","example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","description":"The address of the Smart Contract accounting for the credits"},"balance":{"format":"int64","type":"integer","example":"150","description":"Balance of credits for the plan"},"pricePerCredit":{"type":"number","example":"0.01","description":"Price per credit in USD"}},"required":["planId","planName","planType","isSubscriber","holderAddress","creditsContract","balance","pricePerCredit"]},"InitializeAgentRequestResponseDto":{"type":"object","properties":{"agentRequestId":{"type":"string","example":"req_123abc456def","description":"Unique identifier for this agent request. Use this ID when calling redeemCredits to complete the transaction."},"agentName":{"type":"string","example":"Premium AI Assistant","description":"Name of the agent being accessed"},"agentId":{"type":"string","example":"112715147946069636715282379221777166315490656636137176534659157141164168807749","description":"Unique identifier (DID) of the agent"},"balance":{"description":"Current balance and plan information for the subscriber","allOf":[{"$ref":"#/components/schemas/PaymentPlanBalanceDto"}]},"urlMatching":{"type":"string","example":"https://myagent.ai/api/v1/agents/(.*)/tasks","description":"The URL pattern matching the requested endpoint"},"verbMatching":{"type":"string","example":"POST","description":"The HTTP method matching the request","enum":["GET","POST","PUT","DELETE","PATCH"]},"batch":{"type":"boolean","example":false,"description":"Whether the request is a batch request","default":false}},"required":["agentRequestId","agentName","agentId","balance","urlMatching","verbMatching","batch"]},"RedeemSimulationCreditsDto":{"type":"object","properties":{"agentRequestId":{"type":"string","example":"arId-123","description":"The ID of the agent request. This id is returned by the simulateAgentRequest method."},"marginPercent":{"type":"number","example":0.2,"description":"The margin percentage to apply. This percentage will be applied to the actual cost of the request."},"batch":{"type":"boolean","example":true,"description":"Whether the request is a batch request"}},"required":["agentRequestId"]},"TimeFilter":{"type":"string","enum":["4h","8h","24h","week","all"]},"RequestProperties":{"type":"object","properties":{"model":{"type":"string","example":"gpt-3.5-turbo-0125","description":"Request model name"},"provider":{"type":"string","example":"OPENAI","description":"AI provider name"},"promptTokens":{"type":"string","example":"34","description":"Prompt tokens used"},"completionTokens":{"type":"string","example":"16","description":"Completion tokens used"},"totalTokens":{"type":"string","example":"50","description":"Total tokens used"},"inputCost":{"type":"number","example":0.000041,"description":"Cost of the request"},"outputCost":{"type":"number","example":0.000041,"description":"Cost of the request"},"latency":{"type":"number","example":1065,"description":"Request delay in milliseconds"},"isMarginBased":{"type":"boolean","example":true,"description":"Whether request is margin based"},"marginPercent":{"type":"number","example":0.02,"description":"The percentage of the request that is margin"}},"required":["model","provider","promptTokens","completionTokens","totalTokens","inputCost","outputCost","latency","isMarginBased","marginPercent"]},"_RequestDto":{"type":"object","properties":{"createdAt":{"type":"string","example":"2021-02-01T10:55:11Z","description":"Date when the request was made"},"requestId":{"type":"string","example":"arId-f7a775d9-42ef-43c4-87b7-6051497f667b","description":"Agent request ID"},"customerName":{"type":"string","example":"0xb3381Dd920a4D1FEDD067E05b15Bf52d328AF912","description":"Customer name. For now it is the customer address"},"agentName":{"type":"string","example":"Financial Advisor","description":"The name of the agent"},"planName":{"type":"string","example":"Basic Plan","description":"The name of the plan"},"totalCost":{"type":"number","example":100,"description":"The total cost of the request"},"creditAmount":{"type":"number","example":100,"description":"The amount of credits used"},"requestPrice":{"type":"number","example":100,"description":"The price of the request"},"batch":{"type":"boolean","example":true,"description":"Whether the request is a batch request"},"pnl":{"type":"number","example":1.23,"description":"The PNL of the request"},"completedAt":{"type":"string","example":"2021-02-01T10:55:11Z","description":"Date when the request was completed"},"customerId":{"type":"string","example":"0xb3381Dd920a4D1FEDD067E05b15Bf52d328AF912","description":"Customer ID. For now it is the customer address"},"agentId":{"type":"string","example":"112715147946069636715282379221777166315490656636137176534659157141164168807749","description":"The ID of the agent"},"planId":{"type":"string","example":"6072893147918618836991510631432710862057010729602249220531461142018256888522","description":"The ID of the plan"},"planType":{"type":"string","example":"credits","description":"The type of the plan"},"status":{"type":"string","example":"Success","description":"Request status - Success or Failed","enum":["Success","Failed"]},"signedBodyUrl":{"type":"string","example":"https://minio.helicone.nevermined.dev/helm-request-response-storage/organizations/4fe3c803-a27d-455d-b6f6-bd8627f033e9/requests/e3b6308c-a1e5-4e64-b48a-abf12e9c1951/request_response_body?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=minioadmin%2F20250922%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20250922T121419Z&X-Amz-Expires=86400&X-Amz-Signature=e45f44556f459ea90d962a0c3d6e6500b01a28acce889b8cc9160d51a4139ea28d&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject","description":"The signed body URL"},"properties":{"description":"Request properties including model, provider, tokens, and costs","allOf":[{"$ref":"#/components/schemas/RequestProperties"}]}},"required":["createdAt","requestId","customerName","agentName","planName","totalCost","creditAmount","requestPrice","batch","pnl","completedAt","customerId","agentId","planId","planType","status","signedBodyUrl","properties"]},"PaginatedRequestsDto":{"type":"object","properties":{"total":{"type":"number","example":156,"description":"Total number of requests across all pages"},"page":{"type":"number","example":1,"description":"Current page number"},"offset":{"type":"number","example":10,"description":"Number of items per page"},"requests":{"description":"Array of request objects","type":"array","items":{"$ref":"#/components/schemas/_RequestDto"}},"filters":{"type":"object","description":"Available filter options","example":{"planNames":["Financial Agent Plan","Premium Plan"],"agentNames":["Financial Agent","Customer Support Agent"],"customerNames":["0xb3381Dd920a4D1FEDD067E05b15Bf52d328AF912"]}}},"required":["total","page","offset","requests","filters"]},"AnalyticsDimension":{"type":"string","enum":["agent","model","provider"]},"AnalyticsCurrency":{"type":"string","enum":["USD","Credits","PnL"]},"PlanTransactionsPageDto":{"type":"object","properties":{"totalResults":{"type":"number","example":137,"description":"Total number of results found"},"page":{"type":"number","example":1,"description":"Page of the plan transaction list"},"offset":{"type":"number","example":20,"description":"Page offset of the transaction list"},"planTransactions":{"description":"List of transactions","example":[{"txId":"tid-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d","planId":"93821938219382198329183921312","planOwner":"0xaaaa1111bbbb2222cccc3333dddd4444eeee5555","planConsumer":"0x37BB53e3d293494DE59fBe1FF78500423dcFd43B","txType":"mint","price":"1000000","ownerMargin":"900000","nvmMargin":"50000","orgMargin":"20000","stripeFee":"30000","numCredits":"100","currency":"USD","paymentType":"fiat","txHash":"0x9f8e7d6c5b4a39281706f5e4d3c2b1a0998877665544332211000ffeeddccbb","reconciliationStatus":"notApplicable","settledAt":null,"planName":"Premium AI Plan","createdAt":"2026-05-29T10:00:00.000Z","updatedAt":"2026-05-29T10:00:00.000Z"}],"type":"array","items":{"type":"string"}},"filters":{"type":"object","example":{"planNames":[{"id":"93821938219382198329183921312","name":"Premium AI Plan"},{"id":"93821938219382198329183921313","name":"Basic Plan"},{"id":"93821938219382198329183921314","name":"Enterprise Plan"}],"customerNames":["0x1234...","0x5678...","0x9abc..."],"builderNames":["0xaaaa...","0xbbbb..."]},"description":"Available filters for the frontend"}},"required":["totalResults","page","offset","planTransactions","filters"]},"SearchPlanTransactionsDto":{"type":"object","properties":{"txId":{"type":"string","example":"tid-8fd70808-0a86-45c0-ac7b-7917d45961a6","description":"Identifier of the transaction in the database"},"planId":{"type":"string","example":"93821938219382198329183921312","description":"PlanId the transaction is about"},"planOwner":{"type":"string","example":"0xb6c82652E91B8bd90E68b9F8F4E33Bac1716AEC7","description":"Address of the owner of the plan"},"planOwners":{"example":["0xb6c82652E91B8bd90E68b9F8F4E33Bac1716AEC7","0x73C5D5cF8482ae5631ac18E6C67B690f1f1E6167"],"description":"List of addresses of plan owners to filter by","type":"array","items":{"type":"string"}},"planConsumer":{"type":"string","example":"0x73C5D5cF8482ae5631ac18E6C67B690f1f1E6167","description":"Address of the consumer of the plan"},"txType":{"type":"string","enum":["Purchase","Mint","Burn","Transfer","Error","Other","CreditMint","CreditBurn","CreditExpired","CreditBackfill","CreditRefund"],"example":"Mint","description":"Type of plan transaction"},"minPrice":{"format":"int64","type":"integer","example":"3.50","description":"Min price of the plan"},"maxPrice":{"format":"int64","type":"integer","example":"150.99","description":"Max price of the plan"},"currency":{"type":"string","example":"USD","description":"Currency"},"paymentType":{"type":"string","enum":["Crypto","Fiat"],"example":"Crypto","description":"Payment type"},"txHash":{"type":"string","example":"0x0e826d720490480fdd4ecc6890a01bee0593a8808153c51f3a6d4c352496901f","description":"Blockchain transaction hash"},"page":{"type":"number","example":1,"description":"Page of the plan transaction list"},"offset":{"type":"number","example":20,"description":"Page offset of the plan transaction list"},"order":{"type":"object","example":"DESC","description":"Order by. DESC to have more recent first or ASC to older first. Default is DESC"},"time":{"type":"string","example":"24h","description":"Time filter for transactions"}},"required":["txId","planId","planOwner","planConsumer","txType","minPrice","maxPrice","currency","paymentType","txHash","page","offset","order","time"]},"PlanCreditsInfo":{"type":"object","properties":{"isRedemptionAmountFixed":{"type":"boolean","description":"Indicates if the redemption amount is fixed (true) or dynamic (false)","example":true},"consumptionInfo":{"type":"number","description":"For EXPIRABLE plans: percentage consumed (0-100). For FIXED/DYNAMIC: remaining credits","example":25.5},"isExpired":{"type":"boolean","description":"For EXPIRABLE plans: true if expired, false otherwise. For FIXED/DYNAMIC: true if no credits left","example":false},"currentBalance":{"type":"string","description":"Current credits balance","example":"75"},"totalCredits":{"type":"string","description":"Total credits originally granted","example":"100"},"purchaseDate":{"type":"string","description":"Purchase date for expirable plans","example":"2024-01-15T10:30:00Z"},"durationSecs":{"type":"number","description":"Duration in seconds for expirable plans","example":2592000}},"required":["isRedemptionAmountFixed","consumptionInfo","isExpired","currentBalance","totalCredits","purchaseDate","durationSecs"]},"PlanTransactionEntity2":{"type":"object","properties":{}},"PlanPurchasedDetailedItem":{"type":"object","properties":{"plan":{"type":"object","description":"Plan detailed information"},"agents":{"description":"Agents associated to this plan","type":"array","items":{"type":"string"}},"creditsInfo":{"description":"Credits consumption information","allOf":[{"$ref":"#/components/schemas/PlanCreditsInfo"}]},"transactions":{"description":"List of transactions for this plan","type":"array","items":{"$ref":"#/components/schemas/PlanTransactionEntity2"}}},"required":["plan","agents","creditsInfo","transactions"]},"PlanPurchasedDetailedDto":{"type":"object","properties":{"page":{"type":"number","example":1,"description":"Page of the plan transaction list"},"totalPages":{"type":"number","example":1,"description":"Total number of pages"},"totalResults":{"type":"number","example":137,"description":"Total number of results found"},"results":{"description":"List of transactions with detailed plan and agent information","type":"array","items":{"$ref":"#/components/schemas/PlanPurchasedDetailedItem"}}},"required":["page","totalPages","totalResults","results"]},"NvmConfigVersionsDto2":{"type":"object","properties":{"id":{"type":"number","example":"1","description":"The id of the revision"},"updated":{"type":"string","example":"2020-01-01T19:13:24Z","description":"The date of the revision"},"checksum":{"type":"string","example":"89328493849328493284932","description":"The checksum of the revision"}},"required":["id","updated","checksum"]},"NvmConfigDto2":{"type":"object","properties":{"userId":{"type":"string","example":"u-12345","description":"The userId who created the asset"},"appId":{"type":"string","example":"12345","description":"The application id that created the asset"},"versions":{"example":"12345","description":"The application id that created the asset","type":"array","items":{"$ref":"#/components/schemas/NvmConfigVersionsDto2"}}}},"MetadataDto2":{"type":"object","properties":{}},"_GetPlanDto":{"type":"object","properties":{"@context":{"type":"string","example":"https://w3id.org/did/v1","description":"Context of the asset"},"_nvm":{"description":"Nevermined config section","allOf":[{"$ref":"#/components/schemas/NvmConfigDto2"}]},"created":{"type":"string","example":"2021-02-01T10:55:11Z","description":"Date when the asset is created"},"updated":{"type":"string","example":"2021-02-01T10:55:11Z","description":"Date when the asset is created"},"id":{"type":"string","example":"112715147946069636715282379221777166315490656636137176534659157141164168807749","description":"ID of the asset"},"metadata":{"description":"Metadata that contains the asset","allOf":[{"$ref":"#/components/schemas/MetadataDto2"}]},"registry":{"type":"object","description":"The object representing the on-chain registry of the asset"},"orgId":{"type":"object","description":"Workspace organization that owns this plan. `null` for Personal plans.","nullable":true,"example":"org-acme"},"organizationName":{"type":"object","description":"Human-readable name of the owning org, resolved server-side. `null` for Personal plans or when the org has been soft-deleted. Webapp badges should prefer this over showing the raw `orgId`.","nullable":true,"example":"Acme Corp"}},"required":["@context","_nvm","created","updated","id","metadata"]},"_GetRankingDto":{"type":"object","properties":{"mostPopularPlan":{"description":"Get the most claimed plan","allOf":[{"$ref":"#/components/schemas/_GetPlanDto"}]},"lastPlanCreated":{"description":"Get the last asset created","allOf":[{"$ref":"#/components/schemas/_GetPlanDto"}]},"lastTransaction":{"type":"object","description":"Get the last transaction"}},"required":["mostPopularPlan","lastPlanCreated","lastTransaction"]},"DashboardMetricsResponseDto":{"type":"object","properties":{"activeUsers":{"type":"number","description":"Number of unique active users","example":1213},"activeUsersVariation":{"type":"string","description":"Percentage variation of active users compared to previous period","example":"15.25"},"totalApiCalls":{"type":"number","description":"Total number of API calls","example":5847},"totalApiCallsVariation":{"type":"string","description":"Percentage variation of API calls compared to previous period","example":"-8.50"},"usdRevenue":{"type":"number","description":"Total revenue in USD/USDC currencies","example":1250.5},"otherCurrencies":{"type":"object","description":"Revenue grouped by other currencies","example":{"ETH":2.5,"BTC":0.1}},"revenueVariation":{"type":"string","description":"Percentage variation of USD/USDC revenue compared to previous period","example":"22.75"}},"required":["activeUsers","activeUsersVariation","totalApiCalls","totalApiCallsVariation","usdRevenue","otherCurrencies","revenueVariation"]},"UploadFileBodyDto":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The file to upload. Sent as the `file` part of the multipart request."},"title":{"type":"string","example":"My avatar","description":"File title."},"description":{"type":"string","example":"The avatar of my profile","description":"Description of the file."},"author":{"type":"string","example":"Heroquest","description":"File owner."},"category":{"type":"string","example":"sales","description":"Category of the file."}},"required":["file","title","description","author","category"]},"_CreateFileUrlDto":{"type":"object","properties":{"url":{"type":"string","example":"http://localhost:3000/cover/2493939919391293567/2493939919391293567.jpg","description":"url generated where the file will host"},"ugcId":{"type":"string","example":"2493939919391293567","description":"ugc id of the files"}},"required":["url","ugcId"]},"_CreatePrivateFileUrlDto":{"type":"object","properties":{"url":{"type":"string","example":"s3://nvm-one-restricted/2493939919391293567/2493939919391293567.jpg","description":"url generated where the file will host"},"ugcId":{"type":"string","example":"2493939919391293567","description":"ugc id of the files"}},"required":["url","ugcId"]},"AuthorizeRequestDto":{"type":"object","properties":{"client_id":{"type":"string","example":"agent-123","description":"Client ID (contains agent_id value - MCP Server identifier)"},"resource":{"type":"string","example":"https://mcp-server.example.com","description":"MCP Server URI (resource identifier)"},"redirect_uri":{"type":"string","example":"cursor://oauth/callback","description":"Redirect URI where the authorization code will be sent"},"code_challenge":{"type":"string","example":"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM","description":"PKCE code challenge (base64url encoded SHA256 hash)"},"code_challenge_method":{"type":"string","example":"S256","description":"PKCE code challenge method","enum":["S256"],"default":"S256"},"state":{"type":"string","example":"xyz","description":"State parameter for CSRF protection"},"plan_id":{"type":"string","example":"plan-456","description":"Payment plan ID to use (optional, will use first available if not provided)"}},"required":["client_id","redirect_uri","code_challenge","code_challenge_method"]},"AuthorizeResponseDto":{"type":"object","properties":{"code":{"type":"string","example":"abc123...","description":"Authorization code to be exchanged for access token"}},"required":["code"]},"TokenRequestDto":{"type":"object","properties":{"grant_type":{"type":"string","example":"authorization_code","description":"Grant type","enum":["authorization_code"]},"code":{"type":"string","example":"abc123...","description":"Authorization code received from /oauth/authorize"},"redirect_uri":{"type":"string","example":"cursor://oauth/callback","description":"Redirect URI (must match the one used in authorization request)"},"client_id":{"type":"string","example":"agent-123","description":"Client ID (MCP Server identifier - same value used in authorization request)"},"code_verifier":{"type":"string","example":"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk","description":"PKCE code verifier (original random string)"},"resource":{"type":"string","example":"https://mcp-server.example.com","description":"MCP Server URI (resource identifier)"}},"required":["grant_type","code","redirect_uri","client_id","code_verifier"]},"TokenResponseDto":{"type":"object","properties":{"access_token":{"type":"string","example":"eyJhbGciOiJFUzI1NksifQ...","description":"Access token (JWT)"},"token_type":{"type":"string","example":"Bearer","description":"Token type","enum":["Bearer"],"default":"Bearer"},"expires_in":{"type":"number","example":3600,"description":"Token expiration time in seconds"},"scope":{"type":"string","example":"calendar contacts","description":"Scope of the access token"}},"required":["access_token","token_type","expires_in"]},"X402ResourceDto":{"type":"object","properties":{"url":{"type":"string","description":"URL of the protected resource/endpoint","example":"/api/v1/agents/80918427023170428029540261117198154464497879145267720259488529685089104529015/tasks"},"description":{"type":"string","description":"Description of the resource","example":"AI agent task execution"},"mimeType":{"type":"string","description":"Expected response MIME type","example":"application/json"}},"required":["url"]},"X402SchemeExtraDto":{"type":"object","properties":{"version":{"type":"string","description":"Scheme version","example":"1"},"agentId":{"type":"string","description":"Agent ID for endpoint validation","example":"80918427023170428029540261117198154464497879145267720259488529685089104529015"},"httpVerb":{"type":"string","description":"HTTP verb for endpoint validation","example":"POST"}}},"X402SchemeDto":{"type":"object","properties":{"scheme":{"type":"string","description":"Payment scheme identifier","example":"nvm:erc4337","enum":["nvm:erc4337","nvm:card-delegation"]},"network":{"type":"string","description":"Settlement network: `eip155:<chainId>` for on-chain ERC-4337, or one of `stripe`/`braintree`/`visa` for off-chain card-delegation.","example":"eip155:84532"},"planId":{"type":"string","description":"Plan ID (256-bit identifier, required for nvm:erc4337, optional for nvm:card-delegation)","example":"44742763076047497640080230236781474129970992727896593861997347135613135571071"},"extra":{"description":"Extra scheme-specific fields","allOf":[{"$ref":"#/components/schemas/X402SchemeExtraDto"}]}},"required":["scheme","network"]},"DelegationConfigDto":{"type":"object","properties":{"providerPaymentMethodId":{"type":"string","description":"Stripe payment method ID (from SetupIntent confirmation). Required when creating a new delegation.","example":"pm_1Abc2Def3Ghi4Jkl"},"spendingLimitCents":{"type":"number","description":"Maximum spending limit in cents (smallest currency unit). Required when creating a new delegation.","example":10000},"durationSecs":{"type":"number","description":"Duration of the delegation in seconds. Required when creating a new delegation.","example":604800},"currency":{"type":"string","description":"Currency code (ISO 4217 lowercase)","example":"usd","enum":["usd","eur","usdc","eurc"],"default":"usd"},"merchantAccountId":{"type":"string","description":"Optional merchant Stripe account ID for Connect routing","example":"acct_1Abc2Def3Ghi"},"maxTransactions":{"type":"number","description":"Maximum number of transactions allowed (null = unlimited)","example":50},"apiKeyId":{"type":"string","description":"NVM API Key ID (skId) to restrict this delegation to. Null = any key can use it.","example":"sk-abc123"},"cardId":{"type":"string","description":"Payment method entity UUID to use for this delegation (alternative to providerPaymentMethodId)","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"delegationId":{"type":"string","description":"Existing delegation UUID to reuse instead of creating a new one","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}},"GenerateX402TokenDto":{"type":"object","properties":{"resource":{"description":"The protected resource information","allOf":[{"$ref":"#/components/schemas/X402ResourceDto"}]},"accepted":{"description":"The accepted payment scheme (nvm:erc4337 or nvm:card-delegation)","allOf":[{"$ref":"#/components/schemas/X402SchemeDto"}]},"delegationConfig":{"description":"Delegation configuration (both nvm:erc4337 and nvm:card-delegation schemes)","allOf":[{"$ref":"#/components/schemas/DelegationConfigDto"}]}},"required":["accepted"]},"AgentX402AccessTokenDto":{"type":"object","properties":{"accessToken":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwbGFuSWQiOiI0MzI5ODQzMjk4NDMyOSIsImFnZW50SWQiOiIxMjM0NTY3ODkwMTIzNDU2Nzg5MCIsInN1YnNjcmliZXJBZGRyZXNzIjoiMHhmMzlGZDZlNTFhYWQ4OEY2RjRjZTZhQjg4MjcyNzljZmZGYjkyMjY2IiwiaWF0IjoxNzM2NjAwMDAwLCJleHAiOjE3Mzc4MDk2MDB9.x402_signature_hash","description":"X402 access token (JWT) for permission-based access. This token is used by the subscriber to access agent endpoints without exposing their private keys. The token contains embedded permission details (plan ID, agent ID, subscriber address, expiration, limits)."}},"required":["accessToken"]},"X402PaymentRequiredDto":{"type":"object","properties":{"x402Version":{"type":"number","description":"x402 protocol version","example":2},"error":{"type":"string","description":"Human-readable error message","example":"Payment required to access resource"},"resource":{"description":"Protected resource information","allOf":[{"$ref":"#/components/schemas/X402ResourceDto"}]},"accepts":{"description":"Array of accepted payment schemes","type":"array","items":{"$ref":"#/components/schemas/X402SchemeDto"}},"extensions":{"type":"object","description":"Extensions object (empty for nvm:erc4337)","example":{}}},"required":["x402Version","resource","accepts","extensions"]},"SettlePermissionsDto":{"type":"object","properties":{"paymentRequired":{"description":"The server's 402 PaymentRequired response. The facilitator validates that the accepted payment method in the token matches one of the accepts in this object.","allOf":[{"$ref":"#/components/schemas/X402PaymentRequiredDto"}]},"x402AccessToken":{"type":"string","description":"The x402 payment payload (base64-encoded). Contains all required fields: planId, subscriberAddress, agentId, endpoint, httpVerb. Alias: paymentPayload","example":"eyJ4NDAyVmVyc2lvbiI6MiwicmVzb3VyY2UiOnsidXJsIjoiaHR0cHM6Ly9teWFnZW50LmFpL2FwaS92MS90YXNrcyJ9LCJhY2NlcHRlZCI6eyJzY2hlbWUiOiJudm06ZXJjNDMzNyIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MzIiLCJwbGFuSWQiOiI0NDc0Mjc2MzA3NjA0NzQ5NzY0MDA4MDIzMDIzNjc4MTQ3NDEyOTk3MDk5MjcyNzg5NjU5Mzg2MTk5NzM0NzEzNTYxMzEzNTU3MTA3MSIsImV4dHJhIjp7InZlcnNpb24iOiIxIiwiYWdlbnRJZCI6IjgwOTE4NDI3MDIzMTcwNDI4MDI5NTQwMjYxMTE3MTk4MTU0NDY0NDk3ODc5MTQ1MjY3NzIwMjU5NDg4NTI5Njg1MDg5MTA0NTI5MDE1IiwiaHR0cFZlcmIiOiJQT1NUIn19LCJwYXlsb2FkIjp7InNpZ25hdHVyZSI6IjB4MTIzNCIsImF1dGhvcml6YXRpb24iOnsiZnJvbSI6IjB4ZjM5RmQ2ZTUxYWFkODhGNkY0Y2U2YUI4ODI3Mjc5Y2ZmRmI5MjI2NiIsInNlc3Npb25LZXlzUHJvdmlkZXIiOiJ6ZXJvZGV2Iiwic2Vzc2lvbktleXMiOltdfX0sImV4dGVuc2lvbnMiOnt9fQ=="},"maxAmount":{"format":"int64","type":"integer","description":"Maximum amount of credits needed to redeem during settlement","example":"2"},"agentRequestId":{"type":"string","example":"arId-123e4567-e89b-12d3-a456-426614174000","description":"Agent request ID for observability tracking. Returned by verify endpoint. Must match `[a-zA-Z0-9\\-_]{1,128}` — the value is interpolated into the Helicone `properties.contains` filter and persisted to `agent_tasks.agent_request_id`, so the surface is bounded to a URL-safe ASCII subset."},"batch":{"type":"boolean","example":true,"description":"Whether this is a batch request (multiple LLM calls under one agentRequestId)"},"marginPercent":{"type":"number","example":0.2,"description":"Margin percentage (0-10) for credit calculation. Mutually exclusive with maxAmount when agentRequestId provided."}},"required":["paymentRequired","x402AccessToken"]},"X402VerifyResponseDto":{"type":"object","properties":{"isValid":{"type":"boolean","description":"Whether the payment authorization is valid","example":true},"invalidReason":{"type":"string","description":"Reason for invalidity (only present if isValid is false)","example":"Insufficient balance"},"payer":{"type":"string","description":"Address of the payer's wallet","example":"0xD4f58B60330bC59cB0A07eE6A1A66ad64244eC8c"},"network":{"type":"string","description":"Network identifier (e.g. CAIP-2 chain ID or payment provider)","example":"eip155:84532"},"agentRequestId":{"type":"string","description":"Agent request ID for observability tracking (Nevermined extension)","example":"arId-123e4567-e89b-12d3-a456-426614174000"},"urlMatching":{"type":"string","description":"URL pattern that matched the endpoint (only present when endpoint validation is performed)","example":"/api/v1/agents/:agentId/tasks"},"agentRequest":{"type":"object","description":"Agent request context for observability (Nevermined extension)","example":{"agentRequestId":"arId-123e4567-e89b-12d3-a456-426614174000","agentName":"AI Assistant Agent","agentId":"80918427023170428029540261117198154464497879145267720259488529685089104529015","balance":{"planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071","planName":"Premium AI Access","planType":"credits","holderAddress":"0xD4f58B60330bC59cB0A07eE6A1A66ad64244eC8c","balance":"98","creditsContract":"0x1234567890abcdef1234567890abcdef12345678","isSubscriber":true,"pricePerCredit":0.001},"urlMatching":"/api/v1/agents/:agentId/tasks","verbMatching":"POST","batch":false}}},"required":["isValid"]},"X402SettleResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether settlement was successful","example":true},"errorReason":{"type":"string","description":"Reason for settlement failure (only present if success is false)","example":"UserOperation reverted"},"payer":{"type":"string","description":"Address of the payer's wallet","example":"0xD4f58B60330bC59cB0A07eE6A1A66ad64244eC8c"},"transaction":{"type":"string","description":"Blockchain transaction hash (not present if settlement failed before a transaction)","example":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"},"network":{"type":"string","description":"Blockchain network identifier in CAIP-2 format","example":"eip155:84532"},"creditsRedeemed":{"type":"string","description":"Number of credits redeemed (Nevermined extension)","example":"2"},"remainingBalance":{"type":"string","description":"Subscriber's remaining balance (Nevermined extension)","example":"98"},"orderTx":{"type":"string","description":"Reference for the auto top-up order, if one occurred (Nevermined extension). For fiat card-delegation this is the **Stripe PaymentIntent id** (`pi_…`); the on-chain order hash is backfilled into `providerMetadata.onchainTxHash` on the corresponding `Purchase` row once the async on-chain mirror lands. For crypto plans this is the on-chain transaction hash (`0x…`). Treat as an opaque string and disambiguate by prefix when needed.","example":"pi_3TUrvfBYvSRKcV420xCBjHb1"}},"required":["success","network"]},"PermissionSummaryDto":{"type":"object","properties":{"permissionHash":{"type":"string","description":"Unique identifier of the permission (hash)","example":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"},"scheme":{"type":"string","description":"Payment scheme identifier","example":"nvm:erc4337","enum":["nvm:erc4337","nvm:card-delegation"]},"planId":{"type":"string","description":"Unique identifier of the payment plan","example":"12345"},"planName":{"type":"string","description":"Name of the payment plan","example":"Premium Credits"},"redemptionLimit":{"type":"object","description":"Maximum number of redemptions allowed (null = unlimited)","example":10,"nullable":true},"orderLimit":{"type":"object","deprecated":true,"nullable":true,"description":"Deprecated since v0.4.0 — always null. Retained as a v0.3.x backward-compat slot; will be removed in v0.6.x."},"createdAt":{"format":"date-time","type":"string","description":"Date when the permission was created","example":"2025-05-09T12:00:00Z"},"status":{"type":"string","description":"Current status of the permission","enum":["Active","Revoked","Expired","Exhausted"],"example":"Active"},"delegationId":{"type":"object","description":"Linked delegation ID (for delegation-based permissions)","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","nullable":true}},"required":["permissionHash","scheme","planId","planName","redemptionLimit","createdAt","status"]},"PermissionListDto":{"type":"object","properties":{"totalResults":{"type":"number","example":137,"description":"Total number of permissions found"},"page":{"type":"number","example":1,"description":"Current page number"},"offset":{"type":"number","example":20,"description":"Number of results per page"},"permissions":{"description":"List of permissions associated with the subscriber","example":[{"permissionHash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","planId":"43298432984329","planName":"Premium AI Access","redemptionLimit":10,"createdAt":"2025-01-10T12:00:00Z","status":"Active"},{"permissionHash":"0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890","planId":"98765432109876","planName":"Basic API Access","redemptionLimit":null,"createdAt":"2025-01-05T08:30:00Z","status":"Active"}],"type":"array","items":{"$ref":"#/components/schemas/PermissionSummaryDto"}}},"required":["totalResults","page","offset","permissions"]},"PermissionDetailsDto":{"type":"object","properties":{"permissionHash":{"type":"string","description":"Unique identifier of the permission (hash)","example":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"},"scheme":{"type":"string","description":"Payment scheme identifier","example":"nvm:erc4337","enum":["nvm:erc4337","nvm:card-delegation"]},"planId":{"type":"string","description":"Unique identifier of the payment plan","example":"12345"},"planName":{"type":"string","description":"Name of the payment plan","example":"Premium Credits"},"status":{"type":"string","description":"Current status of the permission","enum":["Active","Revoked","Expired","Exhausted"],"example":"Active"},"createdAt":{"format":"date-time","type":"string","description":"Date when the permission was created","example":"2025-05-09T12:00:00Z"},"lastUsedAt":{"type":"object","description":"Date when the permission was last used","example":"2025-05-09T14:00:00Z","nullable":true},"expiresAt":{"type":"object","description":"Date when the permission expires","example":"2025-12-20T00:00:00Z","nullable":true},"redemptionLimit":{"type":"object","description":"Maximum number of redemptions allowed (null = unlimited)","example":10,"nullable":true},"orderLimit":{"type":"object","deprecated":true,"nullable":true,"description":"Deprecated since v0.4.0 — always null. Retained as a v0.3.x backward-compat slot."},"planCost":{"type":"object","deprecated":true,"nullable":true,"description":"Deprecated since v0.4.0 — always null. Retained as a v0.3.x backward-compat slot."},"creditsPerOrder":{"type":"object","deprecated":true,"nullable":true,"description":"Deprecated since v0.4.0 — always null. Retained as a v0.3.x backward-compat slot."},"delegationId":{"type":"object","description":"Linked delegation ID — nvm:card-delegation only","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","nullable":true},"spendingLimitCents":{"type":"object","description":"Spending limit in cents — nvm:card-delegation only","example":"10000","nullable":true},"currency":{"type":"object","description":"Currency code — nvm:card-delegation only","example":"usd","nullable":true},"remainingBudgetCents":{"type":"object","description":"Remaining budget in cents — nvm:card-delegation only","example":"9000","nullable":true}},"required":["permissionHash","scheme","planId","planName","status","createdAt","lastUsedAt","expiresAt","redemptionLimit"]},"PaymentMethodSummaryDto":{"type":"object","properties":{"id":{"type":"string","example":"pm_1Abc2Def3Ghi4Jkl"},"type":{"type":"string","example":"card"},"last4":{"type":"string","example":"4242"},"brand":{"type":"string","example":"visa"},"expMonth":{"type":"object","example":12,"nullable":true},"expYear":{"type":"object","example":2027,"nullable":true},"alias":{"type":"object","example":"My Card","nullable":true},"provider":{"type":"string","example":"stripe","enum":["stripe","braintree","erc4337","visa"]},"status":{"type":"string","example":"Active","enum":["Active","Revoked"]},"allowedApiKeyIds":{"type":"object","example":["sk-abc123","sk-def456"],"nullable":true,"description":"NVM API Key IDs allowed to use this card. Null = any key can use it."}},"required":["id","type","last4","brand","expMonth","expYear","alias","provider","status"]},"UpdatePaymentMethodDto":{"type":"object","properties":{"alias":{"type":"string","description":"Optional friendly name for the card","example":"My Production Card"},"allowedApiKeyIds":{"description":"Array of NVM API Key skId values allowed to use this card. Null or empty = any key can use it.","example":["sk-abc123","sk-def456"],"nullable":true,"type":"array","items":{"type":"string"}}}},"CreateWidgetKeyDto":{"type":"object","properties":{"name":{"type":"string","description":"Display name for the widget key","example":"Production widget key"},"allowedOrigins":{"description":"Allowed parent origins for postMessage targets","example":["https://app.example.com"],"type":"array","items":{"type":"string"}}},"required":["name","allowedOrigins"]},"CreateWidgetKeyResponseDto":{"type":"object","properties":{"keyId":{"type":"string","example":"a1b2c3d4-..."},"name":{"type":"string","example":"Production widget key"},"isActive":{"type":"boolean","example":true},"createdAt":{"format":"date-time","type":"string","example":"2026-04-16T10:00:00Z"},"revokedAt":{"type":"object","example":null,"nullable":true},"allowedOrigins":{"example":["https://app.example.com"],"description":"Allowed parent origins for postMessage targets","type":"array","items":{"type":"string"}},"rawSecret":{"type":"string","description":"Raw secret — shown only once at creation time","example":"wk_a1b2c3d4e5f6..."}},"required":["keyId","name","isActive","createdAt","revokedAt","allowedOrigins","rawSecret"]},"WidgetKeyDto":{"type":"object","properties":{"keyId":{"type":"string","example":"a1b2c3d4-..."},"name":{"type":"string","example":"Production widget key"},"isActive":{"type":"boolean","example":true},"createdAt":{"format":"date-time","type":"string","example":"2026-04-16T10:00:00Z"},"revokedAt":{"type":"object","example":null,"nullable":true},"allowedOrigins":{"example":["https://app.example.com"],"description":"Allowed parent origins for postMessage targets","type":"array","items":{"type":"string"}}},"required":["keyId","name","isActive","createdAt","revokedAt","allowedOrigins"]},"UpdateWidgetKeyDto":{"type":"object","properties":{"allowedOrigins":{"description":"Allowed parent origins for postMessage targets","example":["https://app.example.com","https://staging.example.com"],"type":"array","items":{"type":"string"}}},"required":["allowedOrigins"]},"CreateWidgetSessionDto":{"type":"object","properties":{"orgId":{"type":"string","description":"Organization id the widget session belongs to. Matches the `orgId` passed to `createWidgetSession` in the server SDK."},"email":{"type":"string","description":"End-user's email — canonical Nevermined identity for the widget. The same email that ever logs in directly to nevermined.dev resolves to the same Privy user, wallet and profile."},"rawSecret":{"type":"string","description":"Raw widget key secret (`wk_...`) issued in the org admin UI. Sent server-to-server from the integrator backend. F-055: the API stores only a SHA-256 hash of this value; never expose it to the browser.","example":"wk_a1b2c3d4e5f6..."},"returnUrl":{"type":"string","description":"Optional returnUrl the iframe-less / top-level-tab caller intends to redirect to on success. When supplied the server pre-validates it against the widget key’s `allowedOrigins` (plus the always-allow for localhost / 127.0.0.1 / [::1]) and returns `isReturnUrlAllowed` in the response — letting CLI integrations fail fast before opening the browser. Omit when minting a session for the classic iframe flow.","example":"http://localhost:54321/callback"}},"required":["orgId","email","rawSecret"]},"WidgetSessionResponseDto":{"type":"object","properties":{"sessionToken":{"type":"string","description":"Short-lived JWT session token for widget requests"},"userId":{"type":"string","description":"Nevermined user ID"},"userWallet":{"type":"string","description":"User smart wallet address"},"apiKeyHash":{"type":"string","description":"Bearer credential (signed JWT) for the widget-session user. Despite the legacy `apiKeyHash` name, this is NOT a SHA-256 hash — it is a live API-key credential. H4 (security audit 2026-05-27): the widget-key path (POST /widgets/session) now mints this credential with the same 2h TTL as the session JWT itself, down from the previous 1-year default, so an XSS-stolen value can no longer be replayed long after the session ends. The self-mint path (POST /widgets/session/self) still returns the caller-supplied API key (the caller already authenticated with it). Treat it as sensitive (XSS-readable on the host page) and prefer iframe-scoped flows when possible. See #1734 for the planned rename."},"expiresAt":{"type":"string","description":"Session expiration timestamp (ISO 8601)"},"isReturnUrlAllowed":{"type":"boolean","description":"Set when the caller supplied a `returnUrl` in the request: `true` when the URL is acceptable for this session, `false` when it is not. `null` (or omitted) when no `returnUrl` was supplied. CLI integrations use this to fail fast before opening the browser; the same check runs again at page-load via `/widgets/session/validate` as defense in depth.","nullable":true}},"required":["sessionToken","userId","userWallet","apiKeyHash","expiresAt"]},"CreateSelfWidgetSessionDto":{"type":"object","properties":{"orgId":{"type":"string","description":"Organization id the session should be scoped to. The authenticated user must be an active member of this organization, otherwise the request is rejected with BCK.WIDGET_SESSION.0019."},"returnUrl":{"type":"string","description":"Optional returnUrl the top-level-tab caller intends to redirect to on success. Self-mint sessions accept only localhost / 127.0.0.1 / [::1] hosts. The response carries `isReturnUrlAllowed` so the CLI can fail fast before opening the browser.","example":"http://localhost:54321/callback"}},"required":["orgId"]},"WidgetSessionValidateResponseDto":{"type":"object","properties":{"valid":{"type":"boolean","description":"Always `true` when the session is valid (a 401 is returned otherwise)"},"userId":{"type":"string","description":"Nevermined user ID extracted from the session JWT"},"userWallet":{"type":"string","description":"User smart wallet address extracted from the session JWT"},"apiKeyHash":{"type":"string","description":"Hash of the NVM API key bound to this widget session — embedded consumers use this as a Bearer token against existing user-scoped endpoints. See class JSDoc for the security model."},"allowedOrigins":{"description":"Origins authorized by the widget key. The embedded webapp uses this list to gate postMessage targets.","example":["https://app.example.com"],"type":"array","items":{"type":"string"}},"isReturnUrlAllowed":{"type":"boolean","description":"Set when the caller forwarded the `X-Nvm-Widget-Return-Url` header (redirect-mode embed callers). `true` when the URL passes the same allow-list the create-session endpoint applies; `false` when it does not; `null` when no return URL was supplied. Lets the embed page refuse to redirect to a URL the server has not blessed.","nullable":true}},"required":["valid","userId","userWallet","apiKeyHash","allowedOrigins"]},"CreateEmbedSessionDto":{"type":"object","properties":{"returnUrl":{"type":"string","description":"Optional returnUrl the caller intends to redirect to on success. Embedded sessions accept only localhost / 127.0.0.1 / [::1] hosts. The response carries `isReturnUrlAllowed` so the caller can fail fast before opening the browser.","example":"http://127.0.0.1:54321/callback"}}},"ErrorResponseDto2":{"type":"object","properties":{"code":{"type":"string","description":"Error code identifier (e.g., BCK.PROTOCOL.0001, BCK.X402.0005)","example":"BCK.COMMON.0001"},"httpStatus":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Human-readable error message describing what went wrong","example":"Unable to initialize Nevermined instance"},"details":{"type":"string","description":"Throw-site detail string supplementing the canonical message. Only set when the call site supplied an opts.message; absent otherwise.","example":"Hash JWT is not signed by the node account"},"hint":{"type":"string","description":"Actionable remediation hint, sourced from the catalogue or supplied at the throw site. Tells the caller what to fix or where to look.","example":"Verify the wallet has sufficient balance and that the plan is active."},"docsUrl":{"type":"string","description":"Permalink to the docs page describing this error code.","example":"https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008"},"category":{"type":"string","description":"Coarse classification of the failure, useful for client-side branching without parsing the message.","enum":["validation","auth","business","integration","internal"],"example":"integration"},"retryable":{"type":"boolean","description":"Whether the failure is transient and the same call can be retried with identical inputs. Absent when the catalogue does not assert either way.","example":true},"correlationId":{"type":"string","description":"Request-scoped correlation id stamped by the global filter. Echoed in the x-correlation-id response header. Quote this when reporting issues.","example":"a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9"},"uuid":{"type":"string","description":"Per-error UUID generated at construction. Useful for log correlation.","example":"e-550e8400-e29b-41d4-a716-446655440000"},"date":{"type":"string","description":"ISO timestamp at which the error was constructed.","example":"2026-05-09T12:34:56.789Z","format":"date-time"},"params":{"type":"string","description":"JSON-stringified contextual parameters supplied at the throw site (e.g. IDs, state). Always a string in the wire format — parse with JSON.parse if needed.","example":"{\"planId\":\"43298432984329\",\"reason\":\"Invalid configuration\"}"}},"required":["code","httpStatus","message"]},"ProtocolErrorResponseDto":{"type":"object","properties":{"code":{"type":"string","description":"Protocol-specific error code (BCK.PROTOCOL.0001 - BCK.PROTOCOL.0044)","example":"BCK.PROTOCOL.0001"},"httpStatus":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message for protocol operations","example":"Unable to register payment plan","examples":["Unable to register payment plan","Unable to register agent","Unable to get payment plan by planId","Error ordering plan","Invalid credits type","Insufficient balance"]},"details":{"type":"string","description":"Throw-site detail string supplementing the canonical message. Only set when the call site supplied an opts.message; absent otherwise.","example":"Hash JWT is not signed by the node account"},"hint":{"type":"string","description":"Actionable remediation hint, sourced from the catalogue or supplied at the throw site. Tells the caller what to fix or where to look.","example":"Verify the wallet has sufficient balance and that the plan is active."},"docsUrl":{"type":"string","description":"Permalink to the docs page describing this error code.","example":"https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008"},"category":{"type":"string","description":"Coarse classification of the failure, useful for client-side branching without parsing the message.","enum":["validation","auth","business","integration","internal"],"example":"integration"},"retryable":{"type":"boolean","description":"Whether the failure is transient and the same call can be retried with identical inputs. Absent when the catalogue does not assert either way.","example":true},"correlationId":{"type":"string","description":"Request-scoped correlation id stamped by the global filter. Echoed in the x-correlation-id response header. Quote this when reporting issues.","example":"a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9"},"uuid":{"type":"string","description":"Per-error UUID generated at construction. Useful for log correlation.","example":"e-550e8400-e29b-41d4-a716-446655440000"},"date":{"type":"string","description":"ISO timestamp at which the error was constructed.","example":"2026-05-09T12:34:56.789Z","format":"date-time"},"params":{"type":"string","description":"Protocol-specific error parameters (JSON-stringified)","example":"{\"planId\":\"43298432984329\",\"agentId\":\"12345\",\"error\":\"Invalid priceConfig\"}"}},"required":["code","httpStatus","message"]},"X402ErrorResponseDto":{"type":"object","properties":{"code":{"type":"string","description":"X402-specific error code (BCK.X402.0001 - BCK.X402.0011)","example":"BCK.X402.0004"},"httpStatus":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message for X402 operations","example":"Error generating X402 access token","examples":["Agent not found","Plan not found","The plan is not associated to the agent","Error generating X402 access token","Invalid access token","Error verifying permissions"]},"details":{"type":"string","description":"Throw-site detail string supplementing the canonical message. Only set when the call site supplied an opts.message; absent otherwise.","example":"Hash JWT is not signed by the node account"},"hint":{"type":"string","description":"Actionable remediation hint, sourced from the catalogue or supplied at the throw site. Tells the caller what to fix or where to look.","example":"Verify the wallet has sufficient balance and that the plan is active."},"docsUrl":{"type":"string","description":"Permalink to the docs page describing this error code.","example":"https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008"},"category":{"type":"string","description":"Coarse classification of the failure, useful for client-side branching without parsing the message.","enum":["validation","auth","business","integration","internal"],"example":"integration"},"retryable":{"type":"boolean","description":"Whether the failure is transient and the same call can be retried with identical inputs. Absent when the catalogue does not assert either way.","example":true},"correlationId":{"type":"string","description":"Request-scoped correlation id stamped by the global filter. Echoed in the x-correlation-id response header. Quote this when reporting issues.","example":"a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9"},"uuid":{"type":"string","description":"Per-error UUID generated at construction. Useful for log correlation.","example":"e-550e8400-e29b-41d4-a716-446655440000"},"date":{"type":"string","description":"ISO timestamp at which the error was constructed.","example":"2026-05-09T12:34:56.789Z","format":"date-time"},"params":{"type":"string","description":"X402-specific error parameters (JSON-stringified)","example":"{\"planId\":\"43298432984329\",\"agentId\":\"12345\",\"permissionHash\":\"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef\"}"}},"required":["code","httpStatus","message"]},"FiatErrorResponseDto":{"type":"object","properties":{"code":{"type":"string","description":"Fiat payment error code (BCK.STRIPE.0001 - BCK.STRIPE.0017)","example":"BCK.STRIPE.0003"},"httpStatus":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message for Stripe/PayPal operations","example":"Error creating Stripe payment intent","examples":["Error creating Stripe account","Error creating Stripe payment intent","Error creating Stripe checkout session","The plan is not a Fiat plan","Payment intent not succeeded","Subscription not found"]},"details":{"type":"string","description":"Throw-site detail string supplementing the canonical message. Only set when the call site supplied an opts.message; absent otherwise.","example":"Hash JWT is not signed by the node account"},"hint":{"type":"string","description":"Actionable remediation hint, sourced from the catalogue or supplied at the throw site. Tells the caller what to fix or where to look.","example":"Verify the wallet has sufficient balance and that the plan is active."},"docsUrl":{"type":"string","description":"Permalink to the docs page describing this error code.","example":"https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008"},"category":{"type":"string","description":"Coarse classification of the failure, useful for client-side branching without parsing the message.","enum":["validation","auth","business","integration","internal"],"example":"integration"},"retryable":{"type":"boolean","description":"Whether the failure is transient and the same call can be retried with identical inputs. Absent when the catalogue does not assert either way.","example":true},"correlationId":{"type":"string","description":"Request-scoped correlation id stamped by the global filter. Echoed in the x-correlation-id response header. Quote this when reporting issues.","example":"a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9"},"uuid":{"type":"string","description":"Per-error UUID generated at construction. Useful for log correlation.","example":"e-550e8400-e29b-41d4-a716-446655440000"},"date":{"type":"string","description":"ISO timestamp at which the error was constructed.","example":"2026-05-09T12:34:56.789Z","format":"date-time"},"params":{"type":"string","description":"Stripe/PayPal error parameters (JSON-stringified)","example":"{\"planId\":\"43298432984329\",\"paymentIntentId\":\"pi_1234567890\",\"customerId\":\"cus_1234567890\"}"}},"required":["code","httpStatus","message"]},"OrganizationsErrorResponseDto":{"type":"object","properties":{"code":{"type":"string","description":"Organizations error code (BCK.ORGANIZATIONS.0001 - BCK.ORGANIZATIONS.0002)","example":"BCK.ORGANIZATIONS.0001"},"httpStatus":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message for organization operations","example":"Error creating organization member","examples":["Error creating organization member","Error getting organization members"]},"details":{"type":"string","description":"Throw-site detail string supplementing the canonical message. Only set when the call site supplied an opts.message; absent otherwise.","example":"Hash JWT is not signed by the node account"},"hint":{"type":"string","description":"Actionable remediation hint, sourced from the catalogue or supplied at the throw site. Tells the caller what to fix or where to look.","example":"Verify the wallet has sufficient balance and that the plan is active."},"docsUrl":{"type":"string","description":"Permalink to the docs page describing this error code.","example":"https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008"},"category":{"type":"string","description":"Coarse classification of the failure, useful for client-side branching without parsing the message.","enum":["validation","auth","business","integration","internal"],"example":"integration"},"retryable":{"type":"boolean","description":"Whether the failure is transient and the same call can be retried with identical inputs. Absent when the catalogue does not assert either way.","example":true},"correlationId":{"type":"string","description":"Request-scoped correlation id stamped by the global filter. Echoed in the x-correlation-id response header. Quote this when reporting issues.","example":"a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9"},"uuid":{"type":"string","description":"Per-error UUID generated at construction. Useful for log correlation.","example":"e-550e8400-e29b-41d4-a716-446655440000"},"date":{"type":"string","description":"ISO timestamp at which the error was constructed.","example":"2026-05-09T12:34:56.789Z","format":"date-time"},"params":{"type":"string","description":"Organization-specific error parameters (JSON-stringified)","example":"{\"orgId\":\"org-123\",\"userId\":\"uid-456\",\"role\":\"admin\"}"}},"required":["code","httpStatus","message"]},"ApiKeyErrorResponseDto":{"type":"object","properties":{"code":{"type":"string","description":"API Key error code (BCK.APIKEY.0001 - BCK.APIKEY.0012)","example":"BCK.APIKEY.0004"},"httpStatus":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message for API key operations","example":"Invalid Nevermined API Key","examples":["API Key not registered, you need to register it first","Invalid Nevermined API Key","API Key with given hash not found","API Key issuer does not match user address","Expiration date must be in the future"]},"details":{"type":"string","description":"Throw-site detail string supplementing the canonical message. Only set when the call site supplied an opts.message; absent otherwise.","example":"Hash JWT is not signed by the node account"},"hint":{"type":"string","description":"Actionable remediation hint, sourced from the catalogue or supplied at the throw site. Tells the caller what to fix or where to look.","example":"Verify the wallet has sufficient balance and that the plan is active."},"docsUrl":{"type":"string","description":"Permalink to the docs page describing this error code.","example":"https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008"},"category":{"type":"string","description":"Coarse classification of the failure, useful for client-side branching without parsing the message.","enum":["validation","auth","business","integration","internal"],"example":"integration"},"retryable":{"type":"boolean","description":"Whether the failure is transient and the same call can be retried with identical inputs. Absent when the catalogue does not assert either way.","example":true},"correlationId":{"type":"string","description":"Request-scoped correlation id stamped by the global filter. Echoed in the x-correlation-id response header. Quote this when reporting issues.","example":"a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9"},"uuid":{"type":"string","description":"Per-error UUID generated at construction. Useful for log correlation.","example":"e-550e8400-e29b-41d4-a716-446655440000"},"date":{"type":"string","description":"ISO timestamp at which the error was constructed.","example":"2026-05-09T12:34:56.789Z","format":"date-time"},"params":{"type":"string","description":"API Key error parameters (JSON-stringified)","example":"{\"hash\":\"nvm-api-key-abc123\",\"userId\":\"uid-456\"}"}},"required":["code","httpStatus","message"]},"CommonErrorResponseDto":{"type":"object","properties":{"code":{"type":"string","description":"Common error code (BCK.COMMON.0001 - BCK.COMMON.0024)","example":"BCK.COMMON.0013"},"httpStatus":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message for common operations","example":"Unable to resolve DDO from DID","examples":["Unable to resolve DDO from DID","Plan not found","Unable to get the Plan balance","Method not supported"]},"details":{"type":"string","description":"Throw-site detail string supplementing the canonical message. Only set when the call site supplied an opts.message; absent otherwise.","example":"Hash JWT is not signed by the node account"},"hint":{"type":"string","description":"Actionable remediation hint, sourced from the catalogue or supplied at the throw site. Tells the caller what to fix or where to look.","example":"Verify the wallet has sufficient balance and that the plan is active."},"docsUrl":{"type":"string","description":"Permalink to the docs page describing this error code.","example":"https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008"},"category":{"type":"string","description":"Coarse classification of the failure, useful for client-side branching without parsing the message.","enum":["validation","auth","business","integration","internal"],"example":"integration"},"retryable":{"type":"boolean","description":"Whether the failure is transient and the same call can be retried with identical inputs. Absent when the catalogue does not assert either way.","example":true},"correlationId":{"type":"string","description":"Request-scoped correlation id stamped by the global filter. Echoed in the x-correlation-id response header. Quote this when reporting issues.","example":"a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9"},"uuid":{"type":"string","description":"Per-error UUID generated at construction. Useful for log correlation.","example":"e-550e8400-e29b-41d4-a716-446655440000"},"date":{"type":"string","description":"ISO timestamp at which the error was constructed.","example":"2026-05-09T12:34:56.789Z","format":"date-time"},"params":{"type":"string","description":"JSON-stringified contextual parameters supplied at the throw site (e.g. IDs, state). Always a string in the wire format — parse with JSON.parse if needed.","example":"{\"planId\":\"43298432984329\",\"reason\":\"Invalid configuration\"}"}},"required":["code","httpStatus","message"]}}}}