{"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":"1.1.1","contact":{}},"tags":[],"servers":[{"url":"https://api.live.nevermined.app"}],"components":{"securitySchemes":{"Authorization":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"_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"]},"CreateDelegationDto":{"type":"object","properties":{"provider":{"type":"string","description":"Payment provider type","example":"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","enum":["usd","eur","usdc","eurc"]},"planId":{"type":"string","description":"Plan ID to restrict this delegation to. Optional and plan-agnostic by default (#1534) — EXCEPT provider=visa, where it is REQUIRED (the VGS mandate is merchant-scoped, derived from the plan owner; see BCK.VISA.0015).","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":["provider","spendingLimitCents","durationSecs","currency"]},"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"]},"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":"DEPRECATED (#1674): inline create-on-the-fly. Stripe payment method ID (from SetupIntent confirmation). Prefer create-first via POST /delegation/create, then pass only `delegationId`.","example":"pm_1Abc2Def3Ghi4Jkl","deprecated":true},"spendingLimitCents":{"type":"number","description":"DEPRECATED (#1674): inline create-on-the-fly. Maximum spending limit in cents (smallest currency unit). Prefer create-first via POST /delegation/create, then pass only `delegationId`.","example":10000,"deprecated":true},"durationSecs":{"type":"number","description":"DEPRECATED (#1674): inline create-on-the-fly. Duration of the delegation in seconds. Prefer create-first via POST /delegation/create, then pass only `delegationId`.","example":604800,"deprecated":true},"currency":{"type":"string","description":"DEPRECATED (#1674): inline create-on-the-fly. Currency code (ISO 4217 lowercase). Required when creating inline (no default). Prefer create-first via POST /delegation/create, then pass only `delegationId`.","example":"usd","enum":["usd","eur","usdc","eurc"],"deprecated":true},"merchantAccountId":{"type":"string","description":"DEPRECATED (#1674): inline create-on-the-fly. Optional merchant Stripe account ID for Connect routing. Prefer create-first via POST /delegation/create, then pass only `delegationId`.","example":"acct_1Abc2Def3Ghi","deprecated":true},"maxTransactions":{"type":"number","description":"DEPRECATED (#1674): inline create-on-the-fly. Maximum number of transactions allowed (null = unlimited). Prefer create-first via POST /delegation/create, then pass only `delegationId`.","example":50,"deprecated":true},"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":"DEPRECATED (#1674): inline create-on-the-fly. Payment method entity UUID to use for this delegation (alternative to providerPaymentMethodId). Prefer create-first via POST /delegation/create, then pass only `delegationId`.","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","deprecated":true},"delegationId":{"type":"string","description":"Existing delegation UUID to reuse instead of creating a new one. This is the supported create-first path: create via POST /delegation/create, then pass `delegationId` here.","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},"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},"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"}}}},"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"]}}}}