{"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/organizations/{orgId}/ai-catalog.json":{"get":{"description":"Returns the organization's Agentic Resource Discovery (ARD) catalog: one entry per listed agent, each carrying its x402 payment terms (plan, price, settlement network) in `metadata`. Crawlable by ARD registries. Only active Premium/Enterprise organizations are served; any other org (Lapsed or non-existent) returns 404. Public endpoint — no authentication required.","operationId":"OrganizationsIntegrationController_aiCatalog","parameters":[{"name":"orgId","required":true,"in":"path","description":"Organization identifier","schema":{"example":"org-abc123","type":"string"}}],"responses":{"200":{"description":"ARD ai-catalog.json document","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Organization not found or not on a paid tier"}},"summary":"Public ARD ai-catalog.json 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, plus the chain IDs this pod is actively serving (#1929). A network dropped at boot (its RPC was unreachable) is absent from `networks` until the pod restarts, so ops can detect and cycle a degraded pod. 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"},"networks":{"type":"array","items":{"type":"number"},"example":[8453,4217]}}}}}}},"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":"Credits-based 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","billingModel":"credits"}}}}},"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":403,"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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthGrantErrorDto"}}}}},"summary":"Exchange authorization code for access token","tags":["OAuth"]}},"/oauth/device_authorization":{"post":{"description":"Starts the device ceremony for a browserless agent: returns a device_code (poll /oauth/token with it), a human-typeable user_code, and a verification_uri where a human approves. Public endpoint — no authentication required.","operationId":"OAuthController_deviceAuthorization","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceAuthorizationRequestDto"}}}},"responses":{"200":{"description":"Device authorization response (RFC 8628 §3.2)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceAuthorizationResponseDto"}}}},"400":{"description":"Bad Request - unknown client or missing agent_id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthGrantErrorDto"}}}},"404":{"description":"Not Found - Agent not found"}},"summary":"RFC 8628 device authorization request","tags":["OAuth"]}},"/oauth/revoke":{"post":{"description":"Revokes the AgentBinding behind the supplied credential (NVM API key or x402 access token), invalidating every credential minted from it. Idempotent — always returns 200, including for an unknown or already-revoked token. Public endpoint.","operationId":"OAuthController_revoke","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeRequestDto"}}}},"responses":{"200":{"description":"Token revoked (or already revoked / unknown)."}},"summary":"Revoke a credential (RFC 7009)","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"}}},"cardDelegationCapped":{"summary":"Card delegation with a transaction cap (nvm:card-delegation)","description":"Same as above with a longer window and a maxTransactions ceiling. Note there is no settlement-account field: the seller Stripe Connect account is resolved server-side from the plan (#3136) and is never supplied by the caller","value":{"accepted":{"scheme":"nvm:card-delegation","network":"stripe","planId":"delegation"},"delegationConfig":{"providerPaymentMethodId":"pm_1Abc2Def3Ghi4Jkl","spendingLimitCents":50000,"durationSecs":2592000,"currency":"usd","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. An NVM API key is required unless the token is a well-formed `nvm:erc4337` payload, the rail on which x402 defines a permissionless facilitator. On `nvm:card-delegation` the key is mandatory and must belong to a party to the transaction — the plan owner, a member of the organization that published it, or the buyer the token was issued to.","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. An NVM API key is required unless the token is a well-formed `nvm:erc4337` payload, the rail on which x402 defines a permissionless facilitator. On `nvm:card-delegation` the key is mandatory and must belong to a party to the transaction — the plan owner, a member of the organization that published it, or the buyer the token was issued to. That rail charges real cards, so it is not open to anonymous callers.","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). `billingModel` discriminates the two shapes: `credits` settles redeem from the plan balance (example below); `pay-as-you-go` settles charge per request and return `creditsRedeemed`/`remainingBalance` of `\"0\"` with the charge in `orderTx`.","schema":{"example":{"success":true,"payer":"0xD4f58B60330bC59cB0A07eE6A1A66ad64244eC8c","transaction":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","network":"eip155:84532","billingModel":"credits","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/ai-catalog.json":{"get":{"description":"On the API host, returns the Nevermined platform Agentic Resource Discovery (ARD) root catalog (one nested entry per organization with published agents/plans). On a per-org branded subdomain (`<slug>.api.<tier>.nevermined.app`), returns that organization's own catalog. Public endpoint — no authentication required.","operationId":"WellKnownController_aiCatalog","parameters":[],"responses":{"200":{"description":"ARD ai-catalog.json document (root or per-org)","content":{"application/json":{"schema":{"type":"object"}}}}},"summary":"ARD catalog (platform root, or per-org on a branded subdomain)","tags":["Well-Known"]}},"/.well-known/agent-services-catalog.json":{"get":{"description":"Google Agentic Resource Discovery (ARD) document listing the Nevermined-curated external agent services (x402 / MPP / REST / A2A). Public endpoint — no authentication required.","operationId":"WellKnownController_agentServicesCatalog","parameters":[],"responses":{"200":{"description":"ARD ai-catalog.json document for the curated services","content":{"application/json":{"schema":{"type":"object"}}}}},"summary":"ARD catalog for the curated Agent Services Catalog","tags":["Well-Known"]}},"/.well-known/ard.json":{"get":{"description":"The Nevermined-curated Agent Services Catalog served at the Agentic Resource Discovery spec’s normative /.well-known/ard.json path. Identical document to agent-services-catalog.json. Public endpoint — no authentication required.","operationId":"WellKnownController_ardJson","parameters":[],"responses":{"200":{"description":"ARD document for the curated Agent Services Catalog","content":{"application/json":{"schema":{"type":"object"}}}}},"summary":"ARD catalog at the normative /.well-known/ard.json path","tags":["Well-Known"]}},"/.well-known/llms.txt":{"get":{"description":"Served on a per-org branded subdomain (`<slug>.api.<tier>.nevermined.app`); resolves to that organization's llms.txt. Returns 404 on the bare API host. Public endpoint.","operationId":"WellKnownController_llmsTxt","parameters":[],"responses":{"200":{"description":"llms.txt content (plain text)"},"404":{"description":"Not a per-org subdomain, or org not found / not paid"}},"summary":"Per-org llms.txt (on a branded subdomain)","tags":["Well-Known"]}},"/.well-known/agentic-instructions.md":{"get":{"description":"Served on a per-org branded subdomain; resolves to that organization's agentic-instructions.md. Returns 404 on the bare API host. Public endpoint.","operationId":"WellKnownController_agenticInstructionsMd","parameters":[],"responses":{"200":{"description":"agentic-instructions.md content (markdown)"},"404":{"description":"Not a per-org subdomain, or org not found / not paid"}},"summary":"Per-org agentic-instructions.md (on a branded subdomain)","tags":["Well-Known"]}},"/.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"}},"code_challenge_methods_supported":{"type":"array","items":{"type":"string"}},"revocation_endpoint":{"type":"string"},"device_authorization_endpoint":{"type":"string"}}}}}}},"summary":"Get OAuth Authorization Server metadata","tags":["Well-Known"]}},"/.well-known/oauth-protected-resource":{"get":{"description":"Returns the OAuth 2.0 Protected Resource Metadata document (RFC 9728) for this API as a resource server: its resource identifier, the authorization server(s) that mint credentials it accepts, and the supported bearer method. Public endpoint — no authentication required.","operationId":"WellKnownController_getOAuthProtectedResource","parameters":[],"responses":{"200":{"description":"Returns OAuth Protected Resource metadata","content":{"application/json":{"schema":{"type":"object","properties":{"resource":{"type":"string"},"authorization_servers":{"type":"array","items":{"type":"string"}},"bearer_methods_supported":{"type":"array","items":{"type":"string"}},"resource_documentation":{"type":"string"}}}}}}},"summary":"Get OAuth Protected Resource metadata","tags":["Well-Known"]}},"/api/v1/catalog/services":{"get":{"description":"Public, paginated list of curated external agent services. Free-text search over title and description; filter by category, protocol, and tag.","operationId":"CatalogController_listServices","parameters":[{"name":"page","required":false,"in":"query","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Items per page (default 20, capped at 100)","schema":{"minimum":1,"example":20,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Free-text over title and description.","schema":{"example":"weather","type":"string"}},{"name":"category","required":false,"in":"query","schema":{"example":"Search & Research","type":"string","enum":["Data & Enrichment","Sales & Business Intelligence","Web Scraping & Automation","Search & Research","Crypto & Blockchain","Finance & Markets","AI & Media","Communication & Voice","Social & Creator","Identity & Compliance","Infrastructure & Compute","Weather","Travel"]}},{"name":"subCategory","required":false,"in":"query","description":"Granular sub-category under a top category (see /catalog/categories).","schema":{"example":"Browser automation","type":"string"}},{"name":"protocol","required":false,"in":"query","schema":{"example":"x402","type":"string","enum":["x402","mpp","rest","a2a","other"]}},{"name":"tag","required":false,"in":"query","schema":{"example":"scraping","type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by liveness status from the catalog-monitor agent. `unverified` = cannot be probed (no signal, NOT down). A service that was never observed (status null) matches no filter. Red = badge only: an unavailable service STAYS listed — the caller filters.","schema":{"example":"operational","type":"string","enum":["operational","degraded","unavailable","unverified"]}},{"name":"sortBy","required":false,"in":"query","description":"Explicit sort column. Omit for the default curated view (tier ascending, then a time-seeded shuffle within each tier). An unknown value is rejected with 400.","schema":{"example":"tier","type":"string","enum":["tier","sortWeight","createdAt","title","healthStatus","uptime7d","uptime30d","latencyP50Ms","latencyP95Ms","lastCheckedAt"]}},{"name":"sortOrder","required":false,"in":"query","schema":{"example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCatalogServicesDto"}}}},"400":{"description":"Invalid query parameter"}},"summary":"List curated agent services","tags":["Agent Services Catalog"]}},"/api/v1/catalog/categories":{"get":{"description":"Curated top-level categories over listed services, each with its count and its granular sub-categories, for the filter dropdown and drill-down.","operationId":"CatalogController_listCategories","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CatalogCategoryDto"}}}}}},"summary":"List catalog categories with counts","tags":["Agent Services Catalog"]}},"/api/v1/catalog/services/{slug}":{"get":{"operationId":"CatalogController_getService","parameters":[{"name":"slug","required":true,"in":"path","schema":{"example":"webscrape-pro","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogServiceDto"}}}},"404":{"description":"No listed service matches the slug (BCK.CATALOG.0001)"}},"summary":"Get a curated agent service by slug","tags":["Agent Services Catalog"]}},"/api/v1/catalog/listings":{"post":{"description":"Creates an owned catalog listing from one of your organization's agents. The listing starts unlisted (pending); the catalog monitor validates it before it goes live.","operationId":"CatalogListingsController_publish","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishCatalogListingDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnerCatalogListingDto"}}}},"404":{"description":"Agent not found / not owned (BCK.CATALOG.0004)"},"409":{"description":"Agent already listed (BCK.CATALOG.0006)"}},"security":[{"Authorization":[]}],"summary":"Publish an owned agent into the catalog","tags":["Agent Services Catalog"]}},"/api/v1/catalog/mine":{"get":{"description":"Every listing owned by your organization, in any lifecycle state (newest first).","operationId":"CatalogListingsController_mine","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OwnerCatalogListingDto"}}}}}},"security":[{"Authorization":[]}],"summary":"List my organization's catalog listings","tags":["Agent Services Catalog"]}},"/api/v1/catalog/listings/{id}":{"patch":{"description":"Update the presentation of one of your listings. Changing the endpoint returns the listing to validation (pending).","operationId":"CatalogListingsController_edit","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditCatalogListingDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnerCatalogListingDto"}}}},"403":{"description":"Endpoint change refused — the listing is under a moderation hold (BCK.CATALOG.0010)"},"404":{"description":"Listing not found / not owned (BCK.CATALOG.0007)"}},"security":[{"Authorization":[]}],"summary":"Edit an owned catalog listing","tags":["Agent Services Catalog"]},"delete":{"description":"Delists the listing (soft remove). The agent itself stays active.","operationId":"CatalogListingsController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnerCatalogListingDto"}}}},"404":{"description":"Listing not found / not owned (BCK.CATALOG.0007)"}},"security":[{"Authorization":[]}],"summary":"Remove an owned listing from the catalog","tags":["Agent Services Catalog"]}},"/api/v1/catalog/listings/{id}/logo":{"post":{"description":"Uploads a raster logo image (png/jpeg/webp/gif/ico, ≤ 2 MB) for one of your listings. The image is hosted by Nevermined and the listing's logoUrl is set to it — use this when your logo would otherwise disclose the service's upstream host (and so is hidden on the public catalog). Presentation-only: it does not change the listing's validation state.","operationId":"CatalogListingsController_setLogo","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UploadLogoBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnerCatalogListingDto"}}}},"400":{"description":"Missing file, or not a supported image (BCK.CATALOG.0012)"},"404":{"description":"Listing not found / not owned (BCK.CATALOG.0007)"},"413":{"description":"Logo image larger than 2 MB"}},"security":[{"Authorization":[]}],"summary":"Upload a self-hosted logo for an owned listing","tags":["Agent Services Catalog"]}},"/api/v1/catalog/listings/{id}/resubmit":{"post":{"description":"Returns a failed/removed listing to validation (pending). The next monitor probe promotes it to live on the first healthy result. A still-listed listing (live or degraded) or an already-pending one cannot be re-submitted.","operationId":"CatalogListingsController_resubmit","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnerCatalogListingDto"}}}},"404":{"description":"Listing not found / not owned (BCK.CATALOG.0007)"},"409":{"description":"Not in a re-submittable state — still listed (live/degraded) or already pending (BCK.CATALOG.0009)"}},"security":[{"Authorization":[]}],"summary":"Re-submit a listing for validation","tags":["Agent Services Catalog"]}},"/api/v1/router/payments":{"post":{"description":"Pay any x402-compatible agent WITHOUT that agent integrating Nevermined. Returns a signed\ncredential you attach to your own request to the agent.\n\nPrerequisite: a spending **Delegation**. Create one once via `POST /api/v1/delegation/create`\nwith `provider: 'erc4337'`, a `spendingLimitCents`, and a `durationSecs`; pass its `id` as\n`delegationId` here. The Router signs with your custodial wallet and enforces the cap.\n\nSteps:\n1. Call the agent once WITHOUT payment → it replies HTTP 402 with requirements. x402 v1 puts\n   them in the JSON body `{ x402Version: 1, accepts: [...] }`; x402 v2 puts them in a base64\n   `PAYMENT-REQUIRED` response header (decode to an object). Pass what you got as `target`.\n2. POST here. The Router selects a fundable option, signs an x402 `exact` (EIP-3009) payment,\n   reserves the amount against your Delegation, and returns `credential` + `settlement`.\n3. Re-send your original request to the agent with the HTTP header named `credential.name`\n   (`PAYMENT-SIGNATURE` for v2, `X-PAYMENT` for v1) set to `credential.value`. The agent\n   verifies, settles on-chain, and returns the resource.\n\nOptionally call `POST /api/v1/router/payments/{paymentId}/settled` with the on-chain tx to\ncomplete the audit record.\n\n**Pass a stable `requestId`, and reuse it across every retry of the same purchase.** At most one\ncredential is minted per id: a retry returns `409 BCK.ROUTER.0002` with the original `paymentId`\ninstead of minting again. Without one — or with a fresh id per HTTP attempt — a retry is a new\npurchase, so it mints a second credential AND is charged the routing fee a second time. Derive\nthe id from the work you are doing, not from a UUID generated per attempt.\nPrefer `POST /api/v1/router/route` to have the Router call the agent and pay in one step (mode B).\n\nMPP: set `protocol: \"mpp\"` and pass the raw `WWW-Authenticate: Payment …` header value as\n`target.challenge` to pay a Merchant-Payment-Protocol (tempo `charge`) merchant. The Router\nreturns an `Authorization: Payment <…>` credential (attach it under header `credential.name`).","operationId":"mintX402PaymentCredential","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentDto"},"examples":{"x402-v1":{"summary":"Pay a v1 (x402-express) agent","value":{"delegationId":"5e7481c3-e972-45bd-bdc5-a0b99c4de4a1","protocol":"x402","resourceUrl":"https://agent.example/paid","requestId":"order-1234","target":{"x402Version":1,"accepts":[{"scheme":"exact","network":"base-sepolia","maxAmountRequired":"1000","asset":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","payTo":"0x209693Bc6afc0C5328bA36FaF03C514EF312287C","maxTimeoutSeconds":60,"extra":{"name":"USDC","version":"2"}}]}}},"mpp-tempo":{"summary":"Pay an MPP (tempo charge) merchant","value":{"delegationId":"5e7481c3-e972-45bd-bdc5-a0b99c4de4a1","protocol":"mpp","resourceUrl":"https://merchant.example/paid","requestId":"order-5678","target":{"challenge":"Payment id=\"ch_abc\", realm=\"merchant.example\", method=\"tempo\", intent=\"charge\", request=\"<base64url>\""}}}}}}},"responses":{"201":{"description":"A signed credential + settlement descriptor + record id. Attach `credential.value` under header `credential.name` to your request to the agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MintPaymentResponseDto"}}}},"400":{"description":"Invalid request, no fundable option in `target`, or a malformed 402 (BCK.ROUTER.0001); or every option advertised an EIP-712 domain its own settlement token does not sign under (BCK.ROUTER.0012). A request-body validation failure arrives as BCK.HTTP.400 instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"401":{"description":"Missing/invalid Nevermined API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"402":{"description":"The spend could not be authorized or funded — no money moved. Three distinct causes: BCK.ROUTER.0003, the delegation cap is exceeded or the delegation is expired / exhausted / revoked; BCK.ROUTER.0009, the buyer wallet does not hold enough of the settlement asset on the target network (crypto rails) or the issuer declined the card (MPP-stripe); BCK.ROUTER.0011, the card needs 3-D Secure cardholder authentication, which an agent with no human at a browser cannot complete. None is safely auto-retryable — branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"403":{"description":"Credential barred from the Router spend rails. Two codes, in the order they are checked: BCK.OAUTH.0030 first — an OAuth-minted key (device/auth-code ceremony) may not spend here; thrown by a guard, so it precedes any handler logic. Then BCK.ROUTER.0008 — a legacy v1 API key cannot sign EIP-3009 from the unified funded wallet; thrown by the handler, and the 403 a Router caller is most likely to hit. Use a plain account key for the first, mint a fresh API key (issued as v2) for the second. Both are permanent — do not retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"404":{"description":"Something the payment needs does not exist. BCK.DELEGATION.0002 — no delegation with that `delegationId` belongs to this caller: unknown, revoked, or owned by someone else. A MALFORMED id is a 400 instead (the field is validated as a uuid), so this is the 404 a well-formed but wrong id produces, and the likeliest error when wiring up. BCK.X402.0011 — the account has no Privy wallet, i.e. signup never completed. BCK.X402.0053 — the account’s embedded wallet has been deleted, so its smart account can no longer be reconstructed; Privy documents this as unrecoverable, so provision a new account. All three are permanent — retrying creates nothing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"409":{"description":"The `requestId` was already used — idempotency conflict (BCK.ROUTER.0002); or the target is a cataloged Nevermined service that must be invoked through the broker by its slug, not by raw URL (BCK.ROUTER.0014).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"422":{"description":"Organization-wallet spend refused by the group budget: the group has exhausted its budget for this period (BCK.BUDGETS.0003), or it has no budget in the settlement currency (BCK.BUDGETS.0006). Only reachable when the delegation is funded by an organization wallet — a personal delegation never returns 422.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"429":{"description":"Rate limit exceeded (BCK.HTTP.429). Two buckets can produce this. The per-API-key ceiling is genuinely yours and answers with `Retry-After` (seconds) — honour it. The global bucket is NOT: these routes authenticate after it runs, so it falls back to keying on the client IP, which is currently SHARED by all external callers — you can be limited by traffic that is not yours. That one answers with `Retry-After-short` / `Retry-After-long`. Retryable after a backoff either way.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"500":{"description":"BCK.ROUTER.0010 — the payment handler reported a settlement amount the routing-fee arithmetic cannot use. For THAT code specifically: a credential may already have been minted while no payment record was written, so your `requestId` will NOT suppress a retry — do not blind-retry, report it. BCK.ROUTER.0013 — Nevermined holds no EIP-712 signing domain for the selected settlement token; nothing was signed, charged or reserved, and a retry fails identically until our token table is fixed, so report it rather than looping. Any other 500 is an unexpected server error, may carry no `code` at all, and the guidance above does not apply to it — treat it as unknown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"503":{"description":"BCK.X402.0052 — the account’s EIP-7702 delegation designator could not be installed on the settlement network, and the Router refuses to pay from a wallet whose funds have not been swept to the signer. Reachable only where EIP-7702 is enabled. This is a transient infrastructure fault and the ONE failure on these routes an autonomous caller SHOULD retry — back off first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}}},"security":[{"Authorization":[]}],"summary":"Mint an x402 payment credential for an upstream agent (mode A)","tags":["Router"]},"get":{"description":"Returns your Router payments (newest first, capped at 1000) across every agent and delegation —\nthe unified audit trail. Filter by `delegationId` and by `from`/`to` (ISO-8601, inclusive on\n`createdAt`). `format=csv` returns a CSV file download instead of the JSON array.","operationId":"listRouterPayments","parameters":[{"name":"delegationId","required":false,"in":"query","description":"Only payments spent against this delegation id.","schema":{"type":"string"}},{"name":"from","required":false,"in":"query","description":"ISO-8601 lower bound on createdAt (inclusive).","schema":{"example":"2026-07-01T00:00:00Z","type":"string"}},{"name":"to","required":false,"in":"query","description":"ISO-8601 upper bound on createdAt (inclusive).","schema":{"example":"2026-07-31T23:59:59Z","type":"string"}},{"name":"format","required":false,"in":"query","description":"Response format. Defaults to JSON; `csv` returns a downloadable file.","schema":{"enum":["json","csv"],"type":"string"}}],"responses":{"200":{"description":"The payment record — a JSON array (or a CSV file when `format=csv`).","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RouterPaymentRecordDto"}}}}},"400":{"description":"`from`/`to` are not valid ISO-8601 timestamps (BCK.ROUTER.0001).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"401":{"description":"Missing/invalid Nevermined API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}}},"security":[{"Authorization":[]}],"summary":"List / export the buyer’s unified payment record across all agents","tags":["Router"]}},"/api/v1/router/route":{"post":{"description":"Hand the Router the request you want made to an upstream x402 agent; it probes, pays any 402\nwith your Delegation (same engine as `POST /payments`), and relays the agent’s response in ONE\ncall — you never see the 402 or handle the credential yourself.\n\nPrerequisite: a Delegation `id` (`POST /api/v1/delegation/create`, provider `erc4337`).\n\nProvide the target `url` OR a catalog `slug` (+ optional `method`, `headers`, `body`). A free\n(non-402) upstream on a raw `url` is relayed unchanged with `paid=false` and no `payment`. For a\ncataloged `slug` the merchant host is protected, so `body` is null on a free/error probe\n(`paid=false`) and on a non-2xx paid response such as a 402 re-challenge (`paid=true, body=null`).\nThe one exception, OFF BY DEFAULT and enabled per-deployment by the operator, is a free\nfollow-up to a resource you have ALREADY paid for (an async result/status poll): when enabled,\nit is relayed (`paid=false`) if a settled payment for the same `slug` exists within a short\nwindow, so you can collect an async result — the host-bearing response headers are still\nstripped. Treat `body=null` on a free cataloged call as the default. `requestId` is REQUIRED (the Router pays automatically, so a retry must be idempotency-keyed); a duplicate returns 409 with the original paymentId.\n\nFor LARGE or STREAMED responses, a transparent streaming variant exists at `ALL /api/v1/router/proxy`:\npoint your HTTP client at it with headers `X-Router-Target-Url` and `X-Router-Delegation-Id`\n(optional `X-Router-Upstream-Authorization` for the agent’s own auth). Method, body and the\nstandard request headers pass through and the response streams back, with payment metadata in\n`X-Router-Payment-Id`, `X-Router-Payment-Status`, `X-Router-Tx-Hash`, and (on a Failed/unsettled\npayment) `X-Router-Failure-Reason` response headers.\nBecause `/proxy` replays headers off the wire it forwards an ALLOWLIST — everything our ingress\nadds (`x-forwarded-*`, `x-real-client-ip`, `traceparent`), plus `cookie`/`origin`/`referer`, is\ndropped; send anything else as `X-Router-Forward-<name>: <value>`. This JSON endpoint takes its\n`headers` from YOU, so it applies no allowlist (hop-by-hop, cloud-metadata and `X-Router-*` are\nstill stripped) — use it when you want a single structured result, or a header `/proxy` will\nnot carry.","operationId":"routeAndPayRequest","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyRequestDto"},"examples":{"get-paid-resource":{"summary":"GET a paid resource through the Router","value":{"delegationId":"5e7481c3-e972-45bd-bdc5-a0b99c4de4a1","url":"https://agent.example/paid","method":"GET","requestId":"order-1234"}}}}}},"responses":{"201":{"description":"The relayed upstream response (`status` + `body`) plus the `payment` that was made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteResultDto"}}}},"400":{"description":"Invalid request, no fundable option, or an upstream/402 error (BCK.ROUTER.0001); or every option advertised an EIP-712 domain its own settlement token does not sign under (BCK.ROUTER.0012). A request-body validation failure arrives as BCK.HTTP.400 instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"401":{"description":"Missing/invalid Nevermined API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"402":{"description":"The spend could not be authorized or funded — no money moved. Three distinct causes: BCK.ROUTER.0003, the delegation cap is exceeded or the delegation is expired / exhausted / revoked; BCK.ROUTER.0009, the buyer wallet does not hold enough of the settlement asset on the target network (crypto rails) or the issuer declined the card (MPP-stripe); BCK.ROUTER.0011, the card needs 3-D Secure cardholder authentication, which an agent with no human at a browser cannot complete. None is safely auto-retryable — branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"403":{"description":"Credential barred from the Router spend rails. Two codes, in the order they are checked: BCK.OAUTH.0030 first — an OAuth-minted key (device/auth-code ceremony) may not spend here; thrown by a guard, so it precedes any handler logic. Then BCK.ROUTER.0008 — a legacy v1 API key cannot sign EIP-3009 from the unified funded wallet; thrown by the handler, and the 403 a Router caller is most likely to hit. Use a plain account key for the first, mint a fresh API key (issued as v2) for the second. Both are permanent — do not retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"404":{"description":"Something the payment needs does not exist. BCK.DELEGATION.0002 — no delegation with that `delegationId` belongs to this caller: unknown, revoked, or owned by someone else. A MALFORMED id is a 400 instead (the field is validated as a uuid), so this is the 404 a well-formed but wrong id produces, and the likeliest error when wiring up. BCK.X402.0011 — the account has no Privy wallet, i.e. signup never completed. BCK.X402.0053 — the account’s embedded wallet has been deleted, so its smart account can no longer be reconstructed; Privy documents this as unrecoverable, so provision a new account. All three are permanent — retrying creates nothing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"409":{"description":"The `requestId` was already used — idempotency conflict (BCK.ROUTER.0002); or the target is a cataloged Nevermined service that must be invoked through the broker by its slug, not by raw URL (BCK.ROUTER.0014).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"422":{"description":"Organization-wallet spend refused by the group budget: the group has exhausted its budget for this period (BCK.BUDGETS.0003), or it has no budget in the settlement currency (BCK.BUDGETS.0006). Only reachable when the delegation is funded by an organization wallet — a personal delegation never returns 422.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"429":{"description":"BCK.ROUTER.0007 — too many mode-B relays in flight for this caller at once (each holds an upstream socket and a reserved budget). Retryable: let some relays finish, then try again. A slug-addressed call (using `slug`, not `url`) has a THIRD 429 source: a per-slug invoke rate limit (BCK.HTTP.429 with `Retry-After`). Two buckets again — the per-(key, slug) ceiling is yours, but the per-slug ceiling is SHARED by everyone invoking that slug, so heavy traffic to a popular slug can limit you even when your own rate is low. Retryable after the `Retry-After` backoff. Rate limit exceeded (BCK.HTTP.429). Two buckets can produce this. The per-API-key ceiling is genuinely yours and answers with `Retry-After` (seconds) — honour it. The global bucket is NOT: these routes authenticate after it runs, so it falls back to keying on the client IP, which is currently SHARED by all external callers — you can be limited by traffic that is not yours. That one answers with `Retry-After-short` / `Retry-After-long`. Retryable after a backoff either way.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"500":{"description":"BCK.ROUTER.0010 — the payment handler reported a settlement amount the routing-fee arithmetic cannot use. For THAT code specifically: a credential may already have been minted while no payment record was written, so your `requestId` will NOT suppress a retry — do not blind-retry, report it. BCK.ROUTER.0013 — Nevermined holds no EIP-712 signing domain for the selected settlement token; nothing was signed, charged or reserved, and a retry fails identically until our token table is fixed, so report it rather than looping. Any other 500 is an unexpected server error, may carry no `code` at all, and the guidance above does not apply to it — treat it as unknown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"503":{"description":"BCK.X402.0052 — the account’s EIP-7702 delegation designator could not be installed on the settlement network, and the Router refuses to pay from a wallet whose funds have not been swept to the signer. Reachable only where EIP-7702 is enabled. This is a transient infrastructure fault and the ONE failure on these routes an autonomous caller SHOULD retry — back off first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}}},"security":[{"Authorization":[]}],"summary":"Route a request through the Router, paying the agent’s 402 and relaying the reply (mode B)","tags":["Router"]}},"/api/v1/router/commerce/route":{"post":{"description":"The OAuth counterpart of `POST /api/v1/router/route`, for a credential minted from a\n`commerce` authorization. Identical behaviour and identical response — with one difference:\n**you do not choose the delegation.** It is derived from your grant: the capped, expiring\nmandate the user approved when they connected you. Sending a `delegationId` is refused, not\nignored.\n\nThe cap, its expiry, and the user revoking the grant are the boundary on what you can spend.\nThe routing fee is drawn from that same cap, in addition to each merchant’s price.\n\nA plain (non-OAuth) API key cannot use this route — it has no grant to derive from. Use\n`POST /api/v1/router/route` and name your own `delegationId` instead.","operationId":"routeAndPayRequestFromGrant","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommerceRouteRequestDto"}}}},"responses":{"200":{"description":"Upstream response, relayed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteResultDto"}}}},"400":{"description":"Malformed request, a `delegationId` was supplied (BCK.OAUTH.0034 — it is derived from your grant), or both `url` and `slug` were given (BCK.ROUTER.0001).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"402":{"description":"The spend could not be authorized or funded — no money moved. Three distinct causes: BCK.ROUTER.0003, the delegation cap is exceeded or the delegation is expired / exhausted / revoked; BCK.ROUTER.0009, the buyer wallet does not hold enough of the settlement asset on the target network (crypto rails) or the issuer declined the card (MPP-stripe); BCK.ROUTER.0011, the card needs 3-D Secure cardholder authentication, which an agent with no human at a browser cannot complete. None is safely auto-retryable — branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"403":{"description":"This credential is not a commerce grant (BCK.OAUTH.0033), or the EIP-7702 wallet gate refused the key (BCK.ROUTER.0008).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"404":{"description":"Something the payment needs does not exist. BCK.DELEGATION.0002 — no delegation with that `delegationId` belongs to this caller: unknown, revoked, or owned by someone else. A MALFORMED id is a 400 instead (the field is validated as a uuid), so this is the 404 a well-formed but wrong id produces, and the likeliest error when wiring up. BCK.X402.0011 — the account has no Privy wallet, i.e. signup never completed. BCK.X402.0053 — the account’s embedded wallet has been deleted, so its smart account can no longer be reconstructed; Privy documents this as unrecoverable, so provision a new account. All three are permanent — retrying creates nothing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"409":{"description":"The `requestId` was already used — idempotency conflict (BCK.ROUTER.0002) — or the raw `url` targets a cataloged service and must be invoked by `slug` (BCK.ROUTER.0014, not retryable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"422":{"description":"Organization-wallet spend refused by the group budget: the group has exhausted its budget for this period (BCK.BUDGETS.0003), or it has no budget in the settlement currency (BCK.BUDGETS.0006). Only reachable when the delegation is funded by an organization wallet — a personal delegation never returns 422.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"429":{"description":"BCK.ROUTER.0007 — too many mode-B relays in flight for this caller at once (each holds an upstream socket and a reserved budget). Retryable: let some relays finish, then try again. A slug-addressed call (using `slug`, not `url`) has a THIRD 429 source: a per-slug invoke rate limit (BCK.HTTP.429 with `Retry-After`). Two buckets again — the per-(key, slug) ceiling is yours, but the per-slug ceiling is SHARED by everyone invoking that slug, so heavy traffic to a popular slug can limit you even when your own rate is low. Retryable after the `Retry-After` backoff. Rate limit exceeded (BCK.HTTP.429). Two buckets can produce this. The per-API-key ceiling is genuinely yours and answers with `Retry-After` (seconds) — honour it. The global bucket is NOT: these routes authenticate after it runs, so it falls back to keying on the client IP, which is currently SHARED by all external callers — you can be limited by traffic that is not yours. That one answers with `Retry-After-short` / `Retry-After-long`. Retryable after a backoff either way.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"500":{"description":"BCK.ROUTER.0010 — the payment handler reported a settlement amount the routing-fee arithmetic cannot use. For THAT code specifically: a credential may already have been minted while no payment record was written, so your `requestId` will NOT suppress a retry — do not blind-retry, report it. BCK.ROUTER.0013 — Nevermined holds no EIP-712 signing domain for the selected settlement token; nothing was signed, charged or reserved, and a retry fails identically until our token table is fixed, so report it rather than looping. Any other 500 is an unexpected server error, may carry no `code` at all, and the guidance above does not apply to it — treat it as unknown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"503":{"description":"BCK.X402.0052 — the account’s EIP-7702 delegation designator could not be installed on the settlement network, and the Router refuses to pay from a wallet whose funds have not been swept to the signer. Reachable only where EIP-7702 is enabled. This is a transient infrastructure fault and the ONE failure on these routes an autonomous caller SHOULD retry — back off first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}}},"security":[{"Authorization":[]}],"summary":"Route and pay using the delegation from your commerce grant (mode B, OAuth)","tags":["Router"]}},"/api/v1/router/payments/{id}/settled":{"post":{"description":"After you attached a mode-A credential and the agent settled on-chain, report the settlement\n`txHash` (from the agent’s `PAYMENT-RESPONSE` / `X-PAYMENT-RESPONSE` header) so the payment\nrecord moves `Issued → Settled`. Idempotent: re-reporting the same txHash is a no-op; a\ndifferent txHash, or a record not in `Issued`, is rejected. NOT needed for mode B\n(`/route` and `/proxy` self-complete the record from the upstream settlement header).","operationId":"reportPaymentSettlement","parameters":[{"name":"id","required":true,"in":"path","description":"The `paymentId` returned by POST /payments.","schema":{"example":"b1f9c2e4-8a3d-4f27-9c6b-5d2e17a04f8b","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlePaymentDto"}}}},"responses":{"201":{"description":"The record is now `Settled`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettleResponseDto"}}}},"400":{"description":"`id` is not a valid uuid, or the body failed validation — both arrive as BCK.HTTP.400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"401":{"description":"Missing/invalid Nevermined API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"404":{"description":"No payment record with that id for this caller (BCK.ROUTER.0004).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"409":{"description":"Record not settleable — already settled with a different tx, or not in `Issued` (BCK.ROUTER.0005).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}}},"security":[{"Authorization":[]}],"summary":"Report the on-chain settlement tx for a minted payment (completes the record)","tags":["Router"]}},"/api/v1/router/payments/summary":{"get":{"description":"Returns the buyer’s total number of Router payment requests (uncapped — unlike the 1000-row\nlist endpoint) plus a per-bucket time-series for a dashboard chart. Filter by `from`/`to`\n(ISO-8601, inclusive on `createdAt`); choose the bucket size with `granularity` (day/week/month).","operationId":"routerPaymentsSummary","parameters":[{"name":"from","required":false,"in":"query","description":"ISO-8601 lower bound on createdAt (inclusive).","schema":{"example":"2026-07-01T00:00:00Z","type":"string"}},{"name":"to","required":false,"in":"query","description":"ISO-8601 upper bound on createdAt (inclusive).","schema":{"example":"2026-07-31T23:59:59Z","type":"string"}},{"name":"granularity","required":false,"in":"query","description":"Bucket size. Defaults to day.","schema":{"enum":["day","week","month"],"type":"string"}}],"responses":{"200":{"description":"Total + time-series.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentsSummaryDto"}}}},"400":{"description":"`from`/`to` are not valid ISO-8601 timestamps (BCK.ROUTER.0001).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"401":{"description":"Missing/invalid Nevermined API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"500":{"description":"The summary could not be built (BCK.ROUTER.0006). Transient — safe to retry; the inputs are validated before this point, so it is not a bad request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}}},"security":[{"Authorization":[]}],"summary":"Aggregate count + time-series of the buyer’s payment requests","tags":["Router"]}},"/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","vgs"],"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"]}},"/api/v1/ard/search":{"post":{"description":"Relevance-ranked search over listed catalog services. `text` is required; `filter` accepts a bounded supported term set (type, tags, capabilities, publisher, pay:*). Each result carries `identifier`, `score` (0–100) and `source`. `federation` (§5.4) controls cross-registry routing: `none` (local only), `referrals` (also list configured peer registries), or `auto` (fan out and merge, gated). Public.","operationId":"ArdRegistryController_search","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArdSearchRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArdSearchResponseDto"}}}},"400":{"description":"Missing `text`, or an unsupported filter term (INVALID_ARGUMENT)."},"429":{"description":"Rate limit exceeded."}},"summary":"ARD registry search (semantic ranking, lexical fallback, federation)","tags":["ARD Registry"]}},"/api/v1/ard/explore":{"post":{"description":"Facet aggregation over the matched set (type, publisher, pay:protocol, tags), narrowed by `text`/`filter` using lexical relevance. Returns `{ resultType: \"facets\", facets }`. Public.","operationId":"ArdRegistryController_explore","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArdExploreRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArdExploreResponseDto"}}}},"400":{"description":"Unsupported facet field or filter term (INVALID_ARGUMENT)."},"429":{"description":"Rate limit exceeded."}},"summary":"ARD registry explore (facets)","tags":["ARD Registry"]}},"/api/v1/ard/agents":{"get":{"description":"Deterministic, cacheable listing over listed catalog services with an EBNF `filter`, `orderBy`, and `pageSize`/`pageToken`. Returns `{ items, total, pageToken }`. Public.","operationId":"ArdRegistryController_agents","parameters":[{"name":"filter","required":false,"in":"query","description":"EBNF filter expression, e.g. \"type = 'application/a2a-agent-card+json' AND updatedAt > '2026-01-01'\".","schema":{"type":"string"}},{"name":"orderBy","required":false,"in":"query","description":"Sort field + optional direction. No relevance sorting (that is /search).","schema":{"example":"updatedAt DESC","type":"string"}},{"name":"pageSize","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"pageToken","required":false,"in":"query","description":"Opaque pagination token.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArdListResponseDto"}}}},"400":{"description":"Malformed filter/orderBy expression (INVALID_ARGUMENT)."},"429":{"description":"Rate limit exceeded."}},"summary":"ARD registry list (deterministic browse)","tags":["ARD Registry"]}}},"info":{"title":"NVM BACKEND API","description":"","version":"1.35.1","contact":{}},"tags":[],"servers":[{"url":"https://api.live.nevermined.app"}],"components":{"securitySchemes":{"Authorization":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"ErrorResponseDto":{"type":"object","properties":{"code":{"type":"string","description":"Error code identifier (e.g., BCK.PROTOCOL.0001, BCK.X402.0005). NOTE: any endpoint may also return a framework-level `BCK.HTTP.<status>` code (e.g. `BCK.HTTP.400` from request validation, `BCK.HTTP.429` from throttling, `BCK.HTTP.404`) — these are emitted by the global fallback filter for HTTP errors that carry no domain-specific code. Clients must tolerate them.","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"},"error":{"type":"string","description":"RFC 6749 §5.2 / RFC 8628 §3.5 top-level OAuth error string. Present only on the OAuth device-polling responses from `POST /oauth/token` (`authorization_pending`, `slow_down`, `expired_token`, `access_denied`), so a standards-compliant OAuth/device client can branch on it directly instead of on the Nevermined `code`. Absent on every other error.","example":"authorization_pending"},"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"]},"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 rail for this delegation. `stripe`, `braintree`, `visa`, and `erc4337` select that rail directly. `vgs` is a portable, plan-agnostic card delegation whose settlement processor (Stripe or Braintree) is chosen when a payment is made, based on the plan being paid — so one enrolled card can pay across processors. `vgs` requires a portable `providerPaymentMethodId` (the `CRD…` `cardId`, which must carry an active network token); for `vgs`, `planId` is optional and only restricts the delegation to a single plan.","example":"stripe","enum":["stripe","erc4337","braintree","visa","vgs"]},"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; for vgs this is the `CRD…` canonical cardId from the unified VGS-Collect enroll. 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":"Restrict this delegation to a single plan. Optional and plan-agnostic by default, including for `vgs` card delegations (whose settlement processor is resolved at payment time from the plan being paid). Required when `provider` is `visa`, because the Visa mandate is scoped to the plan owner (merchant).","example":"123456789"},"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"},"allowedRecipients":{"description":"erc4337 / Router only: restrict spend to these pay-to addresses — the Router rejects payments to any other recipient. Omit for no recipient restriction.","example":["0x209693Bc6afc0C5328bA36FaF03C514EF312287C"],"type":"array","items":{"type":"string"}},"organizationWalletId":{"type":"string","description":"erc4337 / Router only: fund this delegation from an organization wallet instead of the caller's own wallet. The caller must be an admin of the wallet's organization, and spending is always capped by the member's group budget (the wallet must be shared with that group).","example":"orw-abc123"}},"required":["provider","spendingLimitCents","durationSecs","currency"]},"CreateDelegationResponseDto":{"type":"object","properties":{"delegationId":{"type":"string","example":"a1b2c3d4-e5f6-4a90-8bcd-ef1234567890"},"delegationToken":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkZWxlZ2F0aW9uIn0.c2lnbmF0dXJl","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-4a90-8bcd-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":"string","example":"sk-abc123","nullable":true,"description":"Legacy key-id pin: the NVM API Key ID this delegation is restricted to. Null does NOT necessarily mean \"any key\" — check `bindingId`: a delegation pinned to an AgentBinding has `apiKeyId: null` but is still restricted. Null on BOTH = any of the owner's keys may use it."},"bindingId":{"type":"string","example":"ab-abc123","nullable":true,"description":"AgentBinding this delegation is pinned to — stable across credential refresh, unlike `apiKeyId`. When set, only credentials minted from this binding may use it (and `apiKeyId` is null). Null = not binding-pinned."}},"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-4a90-8bcd-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":"string","example":"sk-abc123","nullable":true,"description":"Legacy key-id pin: the NVM API Key ID this delegation is restricted to. Null does NOT necessarily mean \"any key\" — check `bindingId`: a delegation pinned to an AgentBinding has `apiKeyId: null` but is still restricted. Null on BOTH = any of the owner's keys may use it."},"bindingId":{"type":"string","example":"ab-abc123","nullable":true,"description":"AgentBinding this delegation is pinned to — stable across credential refresh, unlike `apiKeyId`. When set, only credentials minted from this binding may use it (and `apiKeyId` is null). Null = not binding-pinned."},"planId":{"type":"string","example":"123456789","nullable":true},"maxTransactions":{"type":"number","example":50,"nullable":true},"lastUsedAt":{"type":"string","example":"2026-02-13T14:00:00Z","nullable":true,"format":"date-time"}},"required":["delegationId","provider","providerPaymentMethodId","status","spendingLimitCents","amountSpentCents","remainingBudgetCents","currency","transactionCount","expiresAt","createdAt","planId","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":"string","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"},"networks":{"example":[84532,42431],"description":"Chain IDs this API instance actively serves (#1929). Primary/anchor first.","type":"array","items":{"type":"number"}},"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","networks","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"}]},"network":{"type":"number","example":84532,"description":"Settlement network (EVM chainId) to register the plan on. Sandbox: 84532 (Base Sepolia) or 42431 (Tempo Moderato). Live: 8453 (Base) or 4217 (Tempo). Optional — defaults to the caller profile's `defaultNetwork`, then the environment's primary network. Must be a network this instance supports (#1929 multi-network)."},"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."},"integrationType":{"type":"string","enum":["a2a","mcp","rest","other"],"example":"a2a","description":"Optional integration protocol the agent exposes (A2A, MCP, REST/OpenAPI, or other). Drives registration UX guidance and discovery/catalogue categorisation."},"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"}]},"network":{"type":"number","example":84532,"description":"Settlement network (EVM chainId) to register the agent on. Sandbox: 84532 (Base Sepolia) or 42431 (Tempo Moderato). Live: 8453 (Base) or 4217 (Tempo). Optional — defaults to the caller profile's `defaultNetwork`, then the environment's primary network. Must be a network this instance supports (#1929 multi-network)."},"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)"},"billingModel":{"type":"string","description":"How the buyer pays for this plan (Nevermined extension, #2755). `pay-as-you-go` plans hold no balance, so `/balance` is always `0` for them; any other plan is `credits`. Omitted only when the plan carries no price config. **In list responses this is derived from stored registration data; `GET /plans/:id` reads the on-chain registry and is authoritative** — they can differ for the rare plan whose stored template was never set. Same field and vocabulary as on `GET /plans/:id`.","enum":["credits","pay-as-you-go"],"example":"pay-as-you-go"}},"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","refresh_token","urn:ietf:params:oauth:grant-type:device_code"]},"code":{"type":"string","example":"abc123...","description":"Authorization code from /oauth/authorize. Required for grant_type=authorization_code."},"redirect_uri":{"type":"string","example":"cursor://oauth/callback","description":"Redirect URI (must match the authorize request). Required for authorization_code."},"client_id":{"type":"string","example":"fleet","description":"The registered OAuth client id (connector) — the same value sent to /oauth/authorize. #2235 G3: this is the OAuth client, NOT the agent id."},"code_verifier":{"type":"string","example":"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk","description":"PKCE code verifier. Required for grant_type=authorization_code."},"refresh_token":{"type":"string","example":"nvm_rt_Zm9vYmFy...","description":"Refresh token. Required for grant_type=refresh_token (#2396)."},"device_code":{"type":"string","example":"a1b2c3...","description":"Device code from /oauth/device_authorization. Required for grant_type=urn:ietf:params:oauth:grant-type:device_code (#2318 B)."},"resource":{"type":"string","example":"https://mcp-server.example.com","description":"MCP Server URI (resource identifier)"}},"required":["grant_type","client_id"]},"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"},"refresh_token":{"type":"string","example":"nvm_rt_Zm9vYmFyYmF6...","description":"Refresh token (#2396) — present it to POST /oauth/token with grant_type=refresh_token to re-mint the credential from the same binding without re-authorizing (RFC 6749 §6). One-time use: rotated on each refresh. Rarely absent on the authorization_code exchange if refresh-token issuance failed after the access token was already minted (the exchange still succeeds)."},"scope":{"type":"string","example":"calendar contacts","description":"Scope of the access token"}},"required":["access_token","token_type","expires_in"]},"OAuthGrantErrorDto":{"type":"object","properties":{"code":{"type":"string","description":"Nevermined error code for the grant failure. The device-polling family is BCK.OAUTH.0021 (pending) / 0022 (slow down) / 0023 (expired) / 0024 (denied); other BCK.OAUTH or BCK.HTTP codes may appear for code, PKCE, or request-validation failures.","example":"BCK.OAUTH.0021"},"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"},"error":{"type":"string","description":"RFC 6749 §5.2 / RFC 8628 §3.5 top-level OAuth error — branch on THIS, not the Nevermined `code`. The device grant emits `authorization_pending` (keep polling), `slow_down` (back off), `expired_token` / `access_denied` (stop). NOT an exhaustive set: a request-validation failure carries the framework value `Bad Request`, and a rejected / expired code omits `error` entirely. `invalid_grant` / `invalid_request` are the RFC names for a rejected or malformed grant but are reserved — not emitted today.","example":"authorization_pending"},"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"]},"DeviceAuthorizationRequestDto":{"type":"object","properties":{"client_id":{"type":"string","example":"fleet","description":"The registered OAuth client id — a connector or the first-party webapp. An unregistered client is rejected (#2235 G3)."},"agent_id":{"type":"string","example":"agent-123","description":"Target agent the ceremony binds to a human. Distinct from client_id (the OAuth client) and resource (the RFC 8707 audience). Account-level (omitted) is a follow-up (#2541)."},"resource":{"type":"string","example":"https://api.nevermined.app","description":"RFC 8707 resource (audience) the credential is scoped to. Omit for the default API key. Device ceremonies currently support only API-host resources (no x402/delegation-backed resource — that is a follow-up); a non-host resource is rejected at /oauth/token."},"scope":{"type":"string","example":"openid","description":"RFC 8628 §3.1 optional scope."}},"required":["client_id"]},"DeviceAuthorizationResponseDto":{"type":"object","properties":{"device_code":{"type":"string","description":"The machine secret the agent polls /oauth/token with (opaque)."},"user_code":{"type":"string","example":"BCDF-GHJK","description":"The short code the human types at the verification URI."},"verification_uri":{"type":"string","example":"https://nevermined.app/oauth/device","description":"Where the human goes to enter the user_code and approve."},"verification_uri_complete":{"type":"string","example":"https://nevermined.app/oauth/device?user_code=BCDF-GHJK","description":"RFC 8628 §3.3.1: verification_uri with the user_code pre-filled (for a QR/link)."},"expires_in":{"type":"number","example":600,"description":"Seconds until the device_code/user_code expire."},"interval":{"type":"number","example":5,"description":"Minimum seconds the agent must wait between token polls."}},"required":["device_code","user_code","verification_uri","verification_uri_complete","expires_in","interval"]},"RevokeRequestDto":{"type":"object","properties":{"token":{"type":"string","description":"The credential to revoke (an NVM API key or an x402 access token)."},"token_type_hint":{"type":"string","description":"RFC 7009 token_type_hint. Advisory only — resolution does not depend on it."}},"required":["token"]},"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 RAIL — not the environment (#2926). Card flows send `stripe`/`braintree`/`visa`; crypto flows send `eip155:<chainId>`. Do NOT send an environment name such as `sandbox` or `live` here.","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},"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-4a90-8bcd-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-4a90-8bcd-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"}]},"tokenVersion":{"type":"number","enum":[2,3],"description":"EIP-712 struct version to sign. Defaults to 3: the signature carries a one-time nonce, so the token is SINGLE-USE — it is consumed by its first settle and a second settle is refused with BCK.X402.0059. Mint one token per paid request. It is also bound to whichever of agentId, resource.url and httpVerb you send on this request: each is signed as the empty string when omitted, which binds the token to that value being ABSENT rather than to any value. So a mint that sends only accepted.extra.agentId gets the agent binding and no resource or verb binding — send resource and accepted.extra.httpVerb too if you want the token pinned to one seller endpoint. Version 2 is the legacy shape: reusable and unbound, so a captured token replays until the permission or delegation is revoked. Ask for it only if you cannot mint per request. The default is version-pinned: clients whose Nevermined-Version resolves below 1.34 keep receiving version 2 when this field is omitted.","example":3}},"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":"Network identifier. The discriminator is the rail, not the billing model. For crypto rails (`nvm:erc4337`) this is the CAIP-2 chain id (`eip155:84532`) for both billing models; for fiat card-delegation rails it is the settling payment provider (e.g. `stripe`, `braintree`), not a CAIP-2 value.","example":"eip155:84532"},"billingModel":{"type":"string","description":"Which billing model this settle was priced under (Nevermined extension). Present regardless of `success` — check `success` before treating it as evidence of a charge (a reverted crypto order returns `success: false` with this field set). `credits` — priced against the plan balance, redeemed on success; `pay-as-you-go` — priced per request with no balance (a card PSP for fiat, an on-chain order for crypto). For `pay-as-you-go`, `creditsRedeemed`/`remainingBalance` are always `\"0\"`; a successful charge is referenced by `orderTx` (fiat) or `transaction` (crypto).","enum":["credits","pay-as-you-go"],"example":"credits"},"creditsRedeemed":{"type":"string","description":"Number of credits redeemed (Nevermined extension). Always `\"0\"` for `billingModel: \"pay-as-you-go\"` plans, which hold no credit balance.","example":"2"},"remainingBalance":{"type":"string","description":"Subscriber's remaining credit balance (Nevermined extension). Always `\"0\"` for `billingModel: \"pay-as-you-go\"` plans — the per-request charge is in `orderTx` (fiat) or `transaction` (crypto), not here.","example":"98"},"orderTx":{"type":"string","description":"Reference for the order or per-request charge, if one occurred (Nevermined extension). For fiat `pay-as-you-go` this is the per-request charge; crypto `pay-as-you-go` reports its on-chain order in `transaction` instead. 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-4a90-8bcd-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-4a90-8bcd-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"]},"CatalogEndpointDto":{"type":"object","properties":{"path":{"type":"string","example":"/scrape"},"method":{"type":"string","example":"POST"},"description":{"type":"string","example":"Scrape a URL to structured JSON"},"priceLabel":{"type":"string","example":"$0.004"}},"required":["path"]},"CatalogFeatureDto":{"type":"object","properties":{"title":{"type":"string","example":"Structured extraction"},"description":{"type":"string","example":"Returns clean JSON from any page"}},"required":["title"]},"CatalogServiceDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","example":"webscrape-pro"},"title":{"type":"string","example":"WebScrape Pro"},"provider":{"type":"string","example":"Acme Data","nullable":true},"category":{"type":"string","enum":["Data & Enrichment","Sales & Business Intelligence","Web Scraping & Automation","Search & Research","Crypto & Blockchain","Finance & Markets","AI & Media","Communication & Voice","Social & Creator","Identity & Compliance","Infrastructure & Compute","Weather","Travel"],"example":"Web Scraping & Automation"},"subCategory":{"type":"string","nullable":true,"example":"Browser automation","description":"Granular sub-category under `category`; null for the generic top bucket."},"shortDescription":{"type":"string","example":"Structured web scraping and extraction, billed per call."},"longDescription":{"type":"string","nullable":true,"description":"Markdown overview shown on the detail page."},"protocol":{"type":"string","enum":["x402","mpp","rest","a2a","other"],"example":"x402"},"invokeUrl":{"type":"string","example":"https://api.nevermined.app/api/v1/router/svc/webscrape-pro","description":"Opaque Router invoke URL for this service. POST here with a Nevermined API key + delegation to pay-through; the Router calls the merchant and the real upstream URL is never exposed. Address the service by this alias (or its slug), never a raw upstream host."},"priceLabel":{"type":"string","example":"$0.004","nullable":true},"network":{"type":"string","example":"Base","nullable":true},"logoUrl":{"type":"string","nullable":true,"example":"https://www.google.com/s2/favicons?domain=stability.ai&sz=128","description":"Logo URL when the listing has one that names no upstream host; null otherwise (render an initials avatar)."},"endpoints":{"type":"array","items":{"$ref":"#/components/schemas/CatalogEndpointDto"}},"features":{"type":"array","items":{"$ref":"#/components/schemas/CatalogFeatureDto"}},"tags":{"example":["scraping","extraction","web"],"type":"array","items":{"type":"string"}},"isListed":{"type":"boolean","example":true,"description":"Always true on the public API (unlisted rows are hidden)."},"tier":{"type":"number","example":1,"description":"Curation tier (1 = top). The default listing orders by tier, then a time-seeded shuffle within each tier that rotates periodically."},"sortWeight":{"type":"number","example":100,"description":"Editorial weight, higher first. Only applies to `?sortBy=sortWeight`; the default view uses tier + within-tier shuffle, not this. Use `tier` to feature a service."},"partner":{"type":"boolean","example":false,"description":"Nevermined Partner trust badge (Nevermined-granted)."},"featured":{"type":"boolean","example":false,"description":"Featured badge (Nevermined-granted) — drives the Featured shelf."},"healthStatus":{"type":"string","nullable":true,"example":"operational","description":"Liveness status from the catalog-monitor agent — currently one of operational / degraded / unavailable / unverified (unverified = cannot be probed, no signal, NOT \"down\"). Treat as an OPEN string and tolerate unknown values: the set may grow. null until first observed."},"uptime7d":{"type":"number","nullable":true,"example":99.4,"description":"Uptime % over the trailing 7 days (conclusive probes); null when no coverage."},"uptime30d":{"type":"number","nullable":true,"example":98.9,"description":"Uptime % over the trailing 30 days (conclusive probes); null when no coverage."},"latencyP50Ms":{"type":"number","nullable":true,"example":340,"description":"p50 of the liveness probe round-trip (ms) — gateway/manifest response time, NOT the AI service's inference latency. null until observed."},"latencyP95Ms":{"type":"number","nullable":true,"example":960,"description":"p95 of the liveness probe round-trip (ms) — gateway response time, not inference."},"lastCheckedAt":{"type":"string","nullable":true,"format":"date-time","description":"When the monitor last probed this service."},"lastHealthyAt":{"type":"string","nullable":true,"format":"date-time","description":"When the monitor last saw this service healthy."},"lastSettledAt":{"type":"string","format":"date-time","nullable":true,"description":"When this service last had a Settled router-payment (30-day window). null = no recent settlement / never observed. Liveness only — no traction volume, no upstream identity."},"distinctPayers30d":{"type":"number","nullable":true,"example":12,"description":"Distinct payers over the trailing 30 days (traction). null when there is no recent settlement signal. SELF-REPORTED: counts distinct buyer wallets on self-attested settlements, not on-chain-verified payments — a wallet can be rotated, so treat it as an unverified traction hint, not proof. Published unfloored by design (a low count is itself informative)."},"stale":{"type":"boolean","example":false,"description":"Display-only \"no traction in ≥30 days\" flag, derived from lastSettledAt. Never auto-delists. A quiet listing surfaces as lastSettledAt=null (stale=false), NOT stale=true."},"settledPriceLabel":{"type":"string","nullable":true,"example":"$0.004","description":"Coarse USD-equivalent of the true settled price for comparison against the claimed priceLabel. Rounded (≥3 s.f.), always `$` — the exact amount, asset and network are not disclosed. null when unknown, OR withheld until the listing has more than one distinct payer (a single, possibly self-attesting, payer cannot set a public price) — the two states share this one encoding, so do not render null as a definitive \"price unknown\"."},"displayPriceLabel":{"type":"string","nullable":true,"example":"$0.004","description":"Single display price: the settled price when public-eligible, else the advertised quoted (402) price. null when neither is known. Coarse `$`, asset/network withheld. Use displayPriceSource to label it."},"displayPriceSource":{"type":"string","enum":["settled","quoted"],"nullable":true,"example":"quoted","description":"Provenance of displayPriceLabel: \"settled\" (real payments) or \"quoted\" (advertised 402 price, not yet settled — render as \"quoted, not settled\"); null when no price."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","slug","title","category","shortDescription","protocol","invokeUrl","logoUrl","endpoints","features","tags","isListed","tier","sortWeight","partner","featured","lastSettledAt","distinctPayers30d","stale","settledPriceLabel","displayPriceLabel","displayPriceSource","createdAt","updatedAt"]},"PaginatedCatalogServicesDto":{"type":"object","properties":{"total":{"type":"number","example":18},"page":{"type":"number","example":1},"offset":{"type":"number","example":10},"services":{"type":"array","items":{"$ref":"#/components/schemas/CatalogServiceDto"}}},"required":["total","page","offset","services"]},"CatalogSubCategoryDto":{"type":"object","properties":{"subCategory":{"type":"string","example":"Browser automation"},"count":{"type":"number","example":3}},"required":["subCategory","count"]},"CatalogCategoryDto":{"type":"object","properties":{"category":{"type":"string","enum":["Data & Enrichment","Sales & Business Intelligence","Web Scraping & Automation","Search & Research","Crypto & Blockchain","Finance & Markets","AI & Media","Communication & Voice","Social & Creator","Identity & Compliance","Infrastructure & Compute","Weather","Travel"],"example":"Search & Research"},"count":{"type":"number","example":3,"description":"Total listed services in this top category."},"subCategories":{"description":"Granular sub-categories within this category (services with a null sub omitted).","type":"array","items":{"$ref":"#/components/schemas/CatalogSubCategoryDto"}}},"required":["category","count","subCategories"]},"CatalogFeatureInputDto":{"type":"object","properties":{"title":{"type":"string","example":"Structured extraction"},"description":{"type":"string","example":"Returns clean JSON from any page"}},"required":["title"]},"PublishCatalogListingDto":{"type":"object","properties":{"agentDid":{"type":"string","example":"did:nv:abc123","description":"DID of an agent your organization owns."},"category":{"type":"string","enum":["Data & Enrichment","Sales & Business Intelligence","Web Scraping & Automation","Search & Research","Crypto & Blockchain","Finance & Markets","AI & Media","Communication & Voice","Social & Creator","Identity & Compliance","Infrastructure & Compute","Weather","Travel"],"example":"Web Scraping & Automation"},"targetUrl":{"type":"string","example":"https://webscrape.example/x402","description":"Callable endpoint the Router routes buyers to (resolved by the publish form)."},"title":{"type":"string","example":"WebScrape Pro","description":"Defaults to the agent name."},"shortDescription":{"type":"string","description":"One-line summary; defaults to the agent description."},"longDescription":{"type":"string","description":"Markdown overview shown on the detail page."},"subCategory":{"type":"string","example":"Browser automation"},"logoUrl":{"type":"string","description":"Logo URL. Shown publicly only when it names no host related to the service URL; otherwise the catalog renders an initials avatar."},"tags":{"example":["scraping","extraction"],"type":"array","items":{"type":"string"}},"features":{"type":"array","items":{"$ref":"#/components/schemas/CatalogFeatureInputDto"}},"homepageUrl":{"type":"string","description":"Public homepage URL."},"docsUrl":{"type":"string","description":"Public documentation URL."}},"required":["agentDid","category","targetUrl"]},"OwnerCatalogListingDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","example":"webscrape-pro"},"title":{"type":"string","example":"WebScrape Pro"},"provider":{"type":"string","example":"Acme Data","nullable":true},"category":{"type":"string","enum":["Data & Enrichment","Sales & Business Intelligence","Web Scraping & Automation","Search & Research","Crypto & Blockchain","Finance & Markets","AI & Media","Communication & Voice","Social & Creator","Identity & Compliance","Infrastructure & Compute","Weather","Travel"],"example":"Web Scraping & Automation"},"subCategory":{"type":"string","nullable":true,"example":"Browser automation","description":"Granular sub-category under `category`; null for the generic top bucket."},"shortDescription":{"type":"string","example":"Structured web scraping and extraction, billed per call."},"longDescription":{"type":"string","nullable":true,"description":"Markdown overview shown on the detail page."},"protocol":{"type":"string","enum":["x402","mpp","rest","a2a","other"],"example":"x402"},"invokeUrl":{"type":"string","example":"https://api.nevermined.app/api/v1/router/svc/webscrape-pro","description":"Opaque Router invoke URL for this service. POST here with a Nevermined API key + delegation to pay-through; the Router calls the merchant and the real upstream URL is never exposed. Address the service by this alias (or its slug), never a raw upstream host."},"priceLabel":{"type":"string","example":"$0.004","nullable":true},"network":{"type":"string","example":"Base","nullable":true},"logoUrl":{"type":"string","nullable":true,"example":"https://www.google.com/s2/favicons?domain=stability.ai&sz=128","description":"Logo URL when the listing has one that names no upstream host; null otherwise (render an initials avatar)."},"endpoints":{"type":"array","items":{"$ref":"#/components/schemas/CatalogEndpointDto"}},"features":{"type":"array","items":{"$ref":"#/components/schemas/CatalogFeatureDto"}},"tags":{"example":["scraping","extraction","web"],"type":"array","items":{"type":"string"}},"isListed":{"type":"boolean","example":false,"description":"Public gate. Unlike the public API, this can be false for an unlisted listing."},"tier":{"type":"number","example":1,"description":"Curation tier (1 = top). The default listing orders by tier, then a time-seeded shuffle within each tier that rotates periodically."},"sortWeight":{"type":"number","example":100,"description":"Editorial weight, higher first. Only applies to `?sortBy=sortWeight`; the default view uses tier + within-tier shuffle, not this. Use `tier` to feature a service."},"partner":{"type":"boolean","example":false,"description":"Nevermined Partner trust badge (Nevermined-granted)."},"featured":{"type":"boolean","example":false,"description":"Featured badge (Nevermined-granted) — drives the Featured shelf."},"healthStatus":{"type":"string","nullable":true,"example":"operational","description":"Liveness status from the catalog-monitor agent — currently one of operational / degraded / unavailable / unverified (unverified = cannot be probed, no signal, NOT \"down\"). Treat as an OPEN string and tolerate unknown values: the set may grow. null until first observed."},"uptime7d":{"type":"number","nullable":true,"example":99.4,"description":"Uptime % over the trailing 7 days (conclusive probes); null when no coverage."},"uptime30d":{"type":"number","nullable":true,"example":98.9,"description":"Uptime % over the trailing 30 days (conclusive probes); null when no coverage."},"latencyP50Ms":{"type":"number","nullable":true,"example":340,"description":"p50 of the liveness probe round-trip (ms) — gateway/manifest response time, NOT the AI service's inference latency. null until observed."},"latencyP95Ms":{"type":"number","nullable":true,"example":960,"description":"p95 of the liveness probe round-trip (ms) — gateway response time, not inference."},"lastCheckedAt":{"type":"string","nullable":true,"format":"date-time","description":"When the monitor last probed this service."},"lastHealthyAt":{"type":"string","nullable":true,"format":"date-time","description":"When the monitor last saw this service healthy."},"lastSettledAt":{"type":"string","format":"date-time","nullable":true,"description":"When this service last had a Settled router-payment (30-day window). null = no recent settlement / never observed. Liveness only — no traction volume, no upstream identity."},"distinctPayers30d":{"type":"number","nullable":true,"example":12,"description":"Distinct payers over the trailing 30 days (traction). null when there is no recent settlement signal. SELF-REPORTED: counts distinct buyer wallets on self-attested settlements, not on-chain-verified payments — a wallet can be rotated, so treat it as an unverified traction hint, not proof. Published unfloored by design (a low count is itself informative)."},"stale":{"type":"boolean","example":false,"description":"Display-only \"no traction in ≥30 days\" flag, derived from lastSettledAt. Never auto-delists. A quiet listing surfaces as lastSettledAt=null (stale=false), NOT stale=true."},"settledPriceLabel":{"type":"string","nullable":true,"example":"$0.004","description":"Coarse USD-equivalent of the true settled price. On this owner surface it is always shown (no public distinct-payer floor applies) — null means the rollup produced no price yet, not \"withheld\"."},"displayPriceLabel":{"type":"string","nullable":true,"example":"$0.004","description":"Single display price: the settled price when public-eligible, else the advertised quoted (402) price. null when neither is known. Coarse `$`, asset/network withheld. Use displayPriceSource to label it."},"displayPriceSource":{"type":"string","enum":["settled","quoted"],"nullable":true,"example":"quoted","description":"Provenance of displayPriceLabel: \"settled\" (real payments) or \"quoted\" (advertised 402 price, not yet settled — render as \"quoted, not settled\"); null when no price."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"agentDid":{"type":"string","nullable":true,"example":"did:nv:abc123"},"orgId":{"type":"string","nullable":true,"example":"org-123"},"submittedBy":{"type":"string","nullable":true,"description":"Member who published the listing."},"moderationStatus":{"type":"string","enum":["pending","live","failed","degraded","removed"],"nullable":true,"example":"pending"},"listedAt":{"type":"string","nullable":true,"format":"date-time"},"pendingSince":{"type":"string","nullable":true,"format":"date-time","description":"When the listing last entered validation — the clock the 24h sweep measures from."},"unlistedReason":{"type":"string","nullable":true,"description":"Why the listing is unlisted."},"moderatorHold":{"type":"boolean","example":false,"description":"True when Nevermined moderation (not the owner) unlisted this listing. While set, Re-submit and endpoint edits are refused (403 BCK.CATALOG.0010) — the owner cannot self-relist."},"freeFollowupPaths":{"example":["/v1/requests/"],"description":"Subpath prefixes whose free (non-402) response body the Router may relay after a paid invocation of this service — the free-follow-up gate allowlist. Server-side gate data, stripped from every public projection; visible only on this owner surface.","type":"array","items":{"type":"string"}},"paymentCount30d":{"type":"number","nullable":true,"example":24},"activeDays30d":{"type":"number","nullable":true,"example":6},"settledPriceAtomic":{"type":"string","nullable":true,"example":"4000","description":"True settled price in atomic units of settledPriceAsset (owner-only, wei-precision)."},"settledPriceAsset":{"type":"string","nullable":true,"example":"USDC"},"settledPriceNetwork":{"type":"string","nullable":true,"example":"base"},"signalsUpdatedAt":{"type":"string","nullable":true,"format":"date-time","description":"When this listing's rollup last CHANGED. An unchanged recompute is skipped, so this can be older than the last sweep — it is not an as-of/freshness timestamp."},"quotedPriceAtomic":{"type":"string","nullable":true,"example":"10000","description":"Advertised 402 price in atomic units (owner-only, wei-precision)."},"quotedPriceAsset":{"type":"string","nullable":true,"example":"USDC"},"quotedPriceNetwork":{"type":"string","nullable":true,"example":"base"},"quotedPriceUpdatedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","slug","title","category","shortDescription","protocol","invokeUrl","logoUrl","endpoints","features","tags","isListed","tier","sortWeight","partner","featured","lastSettledAt","distinctPayers30d","stale","settledPriceLabel","displayPriceLabel","displayPriceSource","createdAt","updatedAt","agentDid","orgId","submittedBy","moderationStatus","listedAt","pendingSince","unlistedReason","moderatorHold","freeFollowupPaths","paymentCount30d","activeDays30d","settledPriceAtomic","settledPriceAsset","settledPriceNetwork","signalsUpdatedAt","quotedPriceAtomic","quotedPriceAsset","quotedPriceNetwork","quotedPriceUpdatedAt"]},"EditCatalogListingDto":{"type":"object","properties":{"category":{"type":"string","enum":["Data & Enrichment","Sales & Business Intelligence","Web Scraping & Automation","Search & Research","Crypto & Blockchain","Finance & Markets","AI & Media","Communication & Voice","Social & Creator","Identity & Compliance","Infrastructure & Compute","Weather","Travel"],"example":"Web Scraping & Automation"},"targetUrl":{"type":"string","example":"https://webscrape.example/x402","description":"Callable endpoint the Router routes buyers to (resolved by the publish form)."},"title":{"type":"string","example":"WebScrape Pro","description":"Defaults to the agent name."},"shortDescription":{"type":"string","description":"One-line summary; defaults to the agent description."},"longDescription":{"type":"string","description":"Markdown overview shown on the detail page."},"subCategory":{"type":"string","example":"Browser automation"},"logoUrl":{"type":"string","description":"Logo URL. Shown publicly only when it names no host related to the service URL; otherwise the catalog renders an initials avatar."},"tags":{"example":["scraping","extraction"],"type":"array","items":{"type":"string"}},"features":{"type":"array","items":{"$ref":"#/components/schemas/CatalogFeatureInputDto"}},"homepageUrl":{"type":"string","description":"Public homepage URL."},"docsUrl":{"type":"string","description":"Public documentation URL."}}},"UploadLogoBodyDto":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The logo image to upload (png/jpeg/webp/gif/ico, ≤ 2 MB). Sent as the `file` part."}},"required":["file"]},"CreatePaymentDto":{"type":"object","properties":{"delegationId":{"type":"string","description":"Delegation id (the caller's individual spend authority) to spend against — created via POST /api/v1/delegation/create and validated as the caller’s own erc4337 delegation."},"protocol":{"type":"string","description":"Payment protocol. `x402` (EIP-3009 exact) or `mpp` (Merchant Payment Protocol, tempo `charge`). The `target` shape depends on this: x402 → `{ accepts, x402Version? }`; mpp → `{ challenge }`.","enum":["x402","mpp"],"example":"x402"},"target":{"type":"object","description":"The upstream's payment requirements, taken verbatim from its HTTP 402 response — its shape depends on `protocol`.\n\n• **x402** — pass `{ accepts: [...], x402Version? }`: `accepts` is the array of payment options the agent advertised (each with `scheme`, `network`, `asset`, `payTo`, `maxAmountRequired`/`amount`, and `extra.name`/`extra.version` for the EIP-712 domain). Get it from the 402 body (x402 v1: `{ x402Version: 1, accepts }`) or by base64-decoding the `PAYMENT-REQUIRED` response header (x402 v2). `x402Version` defaults to 2 when omitted — set it to 1 for x402-express agents. Pass `extra` through verbatim: the Router signs under the EIP-712 domain it holds for the settlement token, and checks the advertised `extra.name`/`extra.version` against it byte for byte — an agent that publishes a domain its own token does not sign under is rejected with `BCK.ROUTER.0012` (nothing is signed, charged or reserved).\n\n• **mpp** — pass `{ challenge }`, where `challenge` is the raw `WWW-Authenticate: Payment …` header value from the merchant’s 402, verbatim — e.g. `Payment id=\"…\", method=\"tempo\", intent=\"charge\", request=\"<base64url>\"`. The Router decodes it, verifies the buyer wallet can fund the tempo `charge`, signs a native Tempo transaction, and returns an `Authorization: Payment <…>` credential (the ledger scheme is `charge`). The tempo payment currency (token address) must be on the operator’s per-chain allowlist.","example":{"x402Version":1,"accepts":[{"scheme":"exact","network":"base-sepolia","maxAmountRequired":"1000","asset":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","payTo":"0x209693Bc6afc0C5328bA36FaF03C514EF312287C","maxTimeoutSeconds":60,"extra":{"name":"USDC","version":"2"}}]}},"resourceUrl":{"type":"string","description":"Upstream resource URL (absolute http(s)) — recorded with the payment."},"requestId":{"type":"string","description":"Caller correlation / idempotency id — at most one credential is minted per requestId; recorded."}},"required":["delegationId","protocol","target"]},"PaymentCredentialDto":{"type":"object","properties":{"transport":{"type":"string","description":"How the credential is delivered to the upstream. Always `header`.","enum":["header"],"example":"header"},"name":{"type":"string","description":"The exact HTTP header name to set on your request to the upstream agent. `PAYMENT-SIGNATURE` for x402 v2, `X-PAYMENT` for x402 v1, `Authorization` for mpp.","enum":["PAYMENT-SIGNATURE","X-PAYMENT","Authorization"],"example":"PAYMENT-SIGNATURE"},"value":{"type":"string","description":"The header VALUE to set. For x402 a base64-encoded signed payment payload; for mpp a `Payment <base64url>` credential. Opaque — attach it verbatim; do not modify.","example":"eyJ4NDAyVmVyc2lvbiI6MiwiYWNjZXB0ZWQiOnsuLi59LCJwYXlsb2FkIjp7Li4ufX0="}},"required":["transport","name","value"]},"SettlementDescriptorDto":{"type":"object","properties":{"recipient":{"type":"string","description":"The on-chain recipient (the agent’s `payTo` address from its 402).","example":"0x209693Bc6afc0C5328bA36FaF03C514EF312287C"},"amount":{"type":"string","description":"Amount in the asset’s smallest unit (USDC/EURC = 6 decimals).","example":"1000"},"asset":{"type":"string","description":"For x402 the asset symbol (`USDC`/`EURC`); for mpp the tempo payment token contract address (mpp carries no on-wire symbol).","example":"USDC"},"network":{"type":"string","description":"Network the payment settles on (name or CAIP-2).","example":"base-sepolia"},"approxCents":{"type":"string","description":"The MERCHANT leg in cents (rounded up) — what this credential pays the upstream agent. This is not necessarily the whole cap charge: Nevermined’s routing fee is reserved on top, so the total debited from the delegation is `approxCents + fee.cents` (also reported directly as `fee.capChargedCents`). With no fee configured the two are equal.","example":"1"},"scheme":{"type":"string","description":"Ledger settlement scheme: `exact` for x402 (EIP-3009), `charge` for MPP-tempo (a native Tempo transaction), `spt` for MPP-stripe (a Shared Payment Token). Omitted (defaults to `exact`) on the x402 path.","enum":["exact","charge","spt"],"example":"exact"}},"required":["recipient","amount","network","approxCents"]},"RouterFeeDto":{"type":"object","properties":{"bps":{"type":"number","description":"Rate applied to this payment, in basis points over a 10,000 denominator (e.g. `200` = 2%). `0` means no routing fee was charged.","example":0},"amount":{"type":"string","description":"The fee in the settlement asset’s smallest unit — the same unit as `settlement.amount`. Reported atomically rather than in cents because cents are ceiling-rounded and cannot express a sub-cent fee.","example":"0"},"cents":{"type":"string","description":"Cents this fee added to the delegation-cap reserve, i.e. `capChargedCents - settlement.approxCents`.","example":"0"},"capChargedCents":{"type":"string","description":"Total debited from the delegation cap for this payment (merchant leg + routing fee), in cents.","example":"1"}},"required":["bps","amount","cents","capChargedCents"]},"MintPaymentResponseDto":{"type":"object","properties":{"paymentId":{"type":"string","description":"Router payment record id (use it with /payments/{id}/settled).","example":"b1f9c2e4-8a3d-4f27-9c6b-5d2e17a04f8b"},"protocol":{"type":"string","description":"Payment protocol used.","enum":["x402","mpp"],"example":"x402"},"x402Version":{"type":"number","description":"Negotiated x402 version (1 or 2).","example":2},"credential":{"description":"The credential to attach to your upstream request.","allOf":[{"$ref":"#/components/schemas/PaymentCredentialDto"}]},"settlement":{"description":"What this credential pays.","allOf":[{"$ref":"#/components/schemas/SettlementDescriptorDto"}]},"fee":{"description":"Nevermined’s routing fee charged on top of the merchant leg. The credential itself pays the merchant only — the fee never rides the merchant’s authorization.","allOf":[{"$ref":"#/components/schemas/RouterFeeDto"}]},"delegationId":{"type":"string","description":"The delegation this spend was reserved against.","example":"5e7481c3-e972-45bd-bdc5-a0b99c4de4a1"},"resourceUrl":{"type":"string","description":"The upstream resource URL recorded with the payment.","example":"https://agent.example/resource","nullable":true},"requestId":{"type":"string","description":"Your idempotency id, echoed back.","example":"order-1234","nullable":true},"status":{"type":"string","description":"Record status at mint time.","enum":["Issued"],"example":"Issued"}},"required":["paymentId","protocol","credential","settlement","fee","delegationId","status"]},"RouterErrorResponseDto":{"type":"object","properties":{"code":{"type":"string","description":"Router error code. `BCK.ROUTER.0001` invalid request / no fundable option / bad 402 (400); `BCK.ROUTER.0002` requestId already used — idempotency conflict (409); `BCK.ROUTER.0003` delegation budget exceeded, expired, or inactive (402); `BCK.ROUTER.0004` payment record not found (404); `BCK.ROUTER.0005` payment not in a settleable state (409); `BCK.ROUTER.0006` failed to build the payments summary (500); `BCK.ROUTER.0007` too many concurrent mode-B relays — retryable (429); `BCK.ROUTER.0008` the Router needs an EIP-7702 (v2) API key (403); `BCK.ROUTER.0009` insufficient wallet balance, or the card was declined (402); `BCK.ROUTER.0010` the amount to charge against the cap could not be determined (500); `BCK.ROUTER.0011` the card needs 3-D Secure cardholder authentication (402); `BCK.ROUTER.0012` the seller advertised an EIP-712 domain its own settlement token does not sign under — the seller’s bug (400); `BCK.ROUTER.0013` Nevermined holds no EIP-712 domain for the selected settlement token — ours, not the seller’s, and not retryable (500); `BCK.ROUTER.0014` this target is a cataloged Nevermined service — invoke it through the broker by its catalog slug (`/router/route` with `slug`, or `/router/svc/:slug`) instead of by raw URL (409). The spend routes can also return `BCK.DELEGATION.0002` (no such delegation for this caller, 404), `BCK.OAUTH.0030` (an OAuth-minted credential may not spend here, 403), `BCK.OAUTH.0033` (this route needs a commerce grant — the OAuth-only `/router/commerce/route`, 403), `BCK.OAUTH.0034` (a `delegationId` was supplied to that route, where it is derived from the grant instead, 400), `BCK.X402.0011` (no Privy wallet for this account, 404), `BCK.X402.0053` (the account’s embedded wallet was deleted, 404) and `BCK.X402.0052` (the EIP-7702 designator could not be installed — transient, retryable, 503); and, for an organization-wallet delegation, `BCK.BUDGETS.0003` / `BCK.BUDGETS.0006` (422). Framework-level `BCK.HTTP.*` codes (e.g. `BCK.HTTP.400` request validation, `BCK.HTTP.429` throttling) may also appear — see the base `code` field.","example":"BCK.ROUTER.0003"},"httpStatus":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message for Router operations.","example":"delegation budget exceeded, expired, or inactive","examples":["delegationId is required — create one via POST /api/v1/delegation/create","no fundable option; offered: [...]","upstream pay-to address is not in this delegation's allowed recipients","delegation budget exceeded, expired, or inactive","payment already settled with a different txHash"]},"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"},"error":{"type":"string","description":"RFC 6749 §5.2 / RFC 8628 §3.5 top-level OAuth error string. Present only on the OAuth device-polling responses from `POST /oauth/token` (`authorization_pending`, `slow_down`, `expired_token`, `access_denied`), so a standards-compliant OAuth/device client can branch on it directly instead of on the Nevermined `code`. Absent on every other error.","example":"authorization_pending"},"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"]},"ProxyRequestDto":{"type":"object","properties":{"delegationId":{"type":"string","description":"The caller's erc4337 delegation to spend against (as in POST /payments)."},"url":{"type":"string","description":"Absolute upstream URL to route to (http/https only). Provide EXACTLY ONE of `url` or `slug` — both together is a 400. Use `slug` for a cataloged service (the opaque broker); `url` is for an off-catalog target you already hold the URL of.","example":"https://agent.example/api/resource"},"slug":{"type":"string","description":"Catalog slug to invoke via the opaque Router broker. The Router resolves the slug to the real upstream server-side, so the URL is never exposed. Mutually exclusive with `url`.","example":"webscrape-pro"},"path":{"type":"string","description":"Optional subpath appended to the resolved upstream when `slug` is used (e.g. `scrape` → the merchant's `/scrape`). Path segments only — it may not change the host, so `//`, `@`, `..` and an embedded absolute URL are rejected (400). Ignored when `url` is used.","example":"scrape"},"method":{"type":"string","description":"HTTP method to use for the upstream request.","enum":["GET","POST","PUT","PATCH","DELETE"],"default":"GET"},"headers":{"type":"object","description":"Headers to forward to the upstream (e.g. the agent’s own auth). Optional."},"body":{"type":"object","description":"Request body to forward (JSON). Optional."},"protocol":{"type":"string","description":"Payment protocol. On the mode-B proxy (`/route`, `/proxy`) this is ADVISORY: the Router AUTO-DETECTS the protocol from the upstream 402 — `WWW-Authenticate: Payment` → `mpp`; `accepts` / `PAYMENT-REQUIRED` → `x402` — and the DETECTED protocol is authoritative for the mint (a mismatching hint here does not change what gets paid).","enum":["x402","mpp"],"default":"x402"},"requestId":{"type":"string","description":"Idempotency key — REQUIRED for routed payments (mode B). The Router makes the upstream call and pays automatically, so a retry after a dropped connection must not double-spend. At most one payment is minted per (caller, requestId); a duplicate returns 409 (BCK.ROUTER.0002) carrying the original paymentId, rather than paying again.","example":"order-1234"}},"required":["delegationId","requestId"]},"RouteResultPaymentDto":{"type":"object","properties":{"paymentId":{"type":"string","example":"b1f9c2e4-8a3d-4f27-9c6b-5d2e17a04f8b"},"settlement":{"$ref":"#/components/schemas/SettlementDescriptorDto"},"fee":{"description":"Nevermined’s routing fee for this payment. Mode B charges it exactly as mode A does, so it is disclosed here too — `settlement.approxCents` is only the merchant leg, and `fee.capChargedCents` is what the delegation cap was actually debited.","allOf":[{"$ref":"#/components/schemas/RouterFeeDto"}]},"txHash":{"type":"string","description":"On-chain settlement tx, if the upstream reported one.","example":"0xfc8af37baae588b5ee4a5e9212532b3d46702ac009b64c17e8ff810fd90ac493","nullable":true},"status":{"type":"string","enum":["Issued","Settled","Failed"],"example":"Settled"},"failureReason":{"type":"string","description":"Why the settlement did not complete cleanly. Present when `status` is `Failed` (e.g. the merchant re-challenged 402 after receiving the credential) or when the record was left `Issued`/unsettled; absent/null on a clean `Settled`.","nullable":true,"example":"upstream rejected the payment credential (402)"},"correlationId":{"type":"string","description":"Request correlation id (also the `x-correlation-id` response header), echoed here so a failed/unsettled payment is self-contained for backend triage.","nullable":true,"example":"567bd2c1a6a56b70532995b2a8ca44f9"}},"required":["paymentId","settlement","fee","status"]},"RouteResultDto":{"type":"object","properties":{"status":{"type":"number","description":"The upstream HTTP status code that was relayed.","example":200},"body":{"type":"object","description":"The upstream response body (parsed JSON when the upstream returned JSON, else a string). For a cataloged (slug) target the body is withheld and returned as null whenever nothing was delivered — a non-402 probe (free or error), or a non-2xx paid response such as a 402 re-challenge (so `paid:true, body:null` is expected). The one exception, where the operator has enabled free follow-ups, is a free (non-402) response returned to a caller who has a recent settled payment for the same slug — an async result/status poll — which is relayed (`paid:false`). Off-catalog (raw-url) targets always relay the body verbatim.","example":{"ok":true,"data":"the paid resource"}},"paid":{"type":"boolean","description":"Whether a payment was ATTEMPTED. `false` = the upstream was free (no 402) and `payment` is absent. `true` = a 402 was encountered and a credential was minted and sent — inspect `payment.status` (`Settled`/`Issued`/`Failed`) and `payment.failureReason` for the settlement OUTCOME; `true` does NOT by itself mean the settlement succeeded.","example":true},"payment":{"description":"The payment made, when `paid` is true.","allOf":[{"$ref":"#/components/schemas/RouteResultPaymentDto"}]}},"required":["status","body","paid"]},"CommerceRouteRequestDto":{"type":"object","properties":{"url":{"type":"string","description":"Absolute upstream URL to route to (http/https only). Provide EXACTLY ONE of `url` or `slug` — both together is a 400. Use `slug` for a cataloged service (the opaque broker); `url` is for an off-catalog target you already hold the URL of.","example":"https://agent.example/api/resource"},"slug":{"type":"string","description":"Catalog slug to invoke via the opaque Router broker. The Router resolves the slug to the real upstream server-side, so the URL is never exposed. Mutually exclusive with `url`.","example":"webscrape-pro"},"path":{"type":"string","description":"Optional subpath appended to the resolved upstream when `slug` is used (e.g. `scrape` → the merchant's `/scrape`). Path segments only — it may not change the host, so `//`, `@`, `..` and an embedded absolute URL are rejected (400). Ignored when `url` is used.","example":"scrape"},"method":{"type":"string","description":"HTTP method to use for the upstream request.","enum":["GET","POST","PUT","PATCH","DELETE"],"default":"GET"},"headers":{"type":"object","description":"Headers to forward to the upstream (e.g. the agent’s own auth). Optional."},"body":{"type":"object","description":"Request body to forward (JSON). Optional."},"protocol":{"type":"string","description":"Payment protocol. On the mode-B proxy (`/route`, `/proxy`) this is ADVISORY: the Router AUTO-DETECTS the protocol from the upstream 402 — `WWW-Authenticate: Payment` → `mpp`; `accepts` / `PAYMENT-REQUIRED` → `x402` — and the DETECTED protocol is authoritative for the mint (a mismatching hint here does not change what gets paid).","enum":["x402","mpp"],"default":"x402"},"requestId":{"type":"string","description":"Idempotency key — REQUIRED for routed payments (mode B). The Router makes the upstream call and pays automatically, so a retry after a dropped connection must not double-spend. At most one payment is minted per (caller, requestId); a duplicate returns 409 (BCK.ROUTER.0002) carrying the original paymentId, rather than paying again.","example":"order-1234"},"delegationId":{"type":"string","description":"Must NOT be sent. The delegation is derived from your grant — the one the user consented to and capped. Supplying one is refused rather than ignored; use POST /api/v1/router/route with a plain API key to choose a delegation per call."}},"required":["requestId"]},"SettlePaymentDto":{"type":"object","properties":{"txHash":{"type":"string","description":"On-chain settlement tx hash (from the upstream's PAYMENT-RESPONSE header).","example":"0xfc8af37baae588b5ee4a5e9212532b3d46702ac009b64c17e8ff810fd90ac493"}},"required":["txHash"]},"SettleResponseDto":{"type":"object","properties":{"paymentId":{"type":"string","example":"b1f9c2e4-8a3d-4f27-9c6b-5d2e17a04f8b"},"status":{"type":"string","enum":["Settled"],"example":"Settled"},"txHash":{"type":"string","example":"0xfc8af37baae588b5ee4a5e9212532b3d46702ac009b64c17e8ff810fd90ac493"}},"required":["paymentId","status","txHash"]},"RouterPaymentRecordDto":{"type":"object","properties":{"id":{"type":"string","example":"b1f9c2e4-8a3d-4f27-9c6b-5d2e17a04f8b"},"createdAt":{"type":"string","example":"2026-07-01T09:00:55.605Z"},"status":{"type":"string","enum":["Issued","Settled","Failed"],"example":"Settled"},"protocol":{"type":"string","example":"x402"},"network":{"type":"string","example":"base-sepolia"},"asset":{"type":"string","description":"The settlement asset AS PERSISTED AT MINT, which differs per rail: a symbol for x402 (`USDC`/`EURC`), the ERC-20 contract ADDRESS from the challenge for MPP-tempo, and an ISO currency code for MPP-stripe. Prefer `assetSymbol`/`assetDecimals` below for display — they normalise all three. Kept as-is for consumers that already parse it.","example":"USDC","nullable":true},"assetSymbol":{"type":"string","description":"Ticker to display for `asset`, resolved for this row’s chain (e.g. `USDC.e`). `null` only when `asset` is a contract ADDRESS we do not recognise on that chain — render the (truncated) address instead, never a guess. When `asset` already is a symbol or a currency code it is echoed here, so a non-null value does NOT by itself imply the scale is known: branch on `assetDecimals` for that.","example":"USDC.e","nullable":true},"assetDecimals":{"type":"number","description":"Decimal scale of `amount` for this asset, so a client never has to assume one. `null` whenever the scale is unknown — treat `amount` as raw atomic units rather than defaulting the scale, which would render a wrong NUMBER rather than a wrong label. This, NOT `assetSymbol`, is the field to branch on: the scale can be unknown on a row that still carries a symbol.","example":6,"nullable":true},"amount":{"type":"string","description":"Amount in the asset’s smallest unit.","example":"1000"},"merchantAddress":{"type":"string","description":"The merchant's pay-to identifier: a 0x address for the crypto rails (x402 / MPP-tempo), or the seller's Stripe network business profile id (profile_…) for the MPP-stripe / SPT card rail.","example":"0x209693Bc6afc0C5328bA36FaF03C514EF312287C"},"txHash":{"type":"string","description":"On-chain settlement tx for the MERCHANT leg — the transaction that moved the money, which is NOT by itself proof the payment succeeded. It is normally reported when the payment settles. It is also filled in by on-chain reconciliation for a payment still `Issued` or `Failed` whose authorization the merchant demonstrably redeemed — whether the merchant then failed to deliver, or delivered without ever reporting a usable reference. Read `merchantSettlementObservedAt` and `status` together to tell those apart. `null` until one of those happens, and always on the MPP-stripe card rail, which does not settle on a chain.","example":"0xfc8af37baae588b5ee4a5e9212532b3d46702ac009b64c17e8ff810fd90ac493","nullable":true},"delegationId":{"type":"string","example":"5e7481c3-e972-45bd-bdc5-a0b99c4de4a1"},"requestId":{"type":"string","description":"The idempotency id supplied at mint time, if any.","example":"order-1234","nullable":true},"resourceUrl":{"type":"string","description":"The upstream resource URL recorded with the payment.","example":"https://agent.example/resource","nullable":true},"buyer":{"type":"string","description":"The buyer identity that funded the payment: the on-chain payer EOA (0x…) for the crypto rails (x402 / MPP-tempo), or the Stripe customer id (cus_…) for the MPP-stripe / SPT card rail.","example":"0x8D6A52339d5f1B0e4C7a29E8b3F6d05A1c94Be27"},"feeAtomic":{"type":"string","description":"Nevermined’s routing fee for this payment, in the settlement asset’s smallest unit. `0` when no fee applied; `null` on rows that predate the fee.","example":"0","nullable":true},"feeBps":{"type":"number","description":"Fee rate applied, in basis points over 10,000. `null` on rows that predate the fee.","example":0,"nullable":true},"feeCents":{"type":"string","description":"Cents the fee added to the delegation-cap reserve. Note `amount` on this record is the MERCHANT leg in atomic units, so the combined cap charge is not derivable from this resource alone — it is recorded as `amountCents` on GET /delegation/{id}/transactions, with this fee broken out in that row’s `providerMetadata`.","example":"0","nullable":true},"feeStatus":{"type":"string","description":"Fee lifecycle, independent of the payment `status`.","enum":["None","Accrued","Submitted","Settled","Failed","Released"],"example":"None","nullable":true},"feeTxHash":{"type":"string","description":"Settlement reference for the FEE leg — distinct from `txHash`, which is the MERCHANT leg’s. The two legs are independent movements that settle separately, so reconcile them separately. **Presence does NOT mean the fee settled — check `feeStatus` for that.** On the x402 rail it is reported verbatim by the facilitator (third-party text, not validated to a `0x` shape) and is `null` until the fee settles. On MPP-tempo it is the hash of the fee transaction Nevermined broadcasts, recorded when the transaction is SUBMITTED rather than when it is mined — so it is present while `feeStatus` is still `Submitted`, and it remains present on rows that end `Failed` or `Released` (the transaction was refused, reverted, or expired unmined). `null` when no fee applied, or before a fee leg is submitted. **On the x402 rail this is ALWAYS `null`.** Nevermined relays that leg itself as an ERC-4337 UserOp, whose artifact is a userOpHash rather than a transaction hash — a different kind of reference that resolves on no block explorer — and the reconciliation that resolves the fee reads the authorization nonce on-chain, which yields a boolean and no transaction. Do NOT poll this field to learn whether an x402 fee settled: read `feeStatus`.","example":"0x9c4d6f1eb4a7c0d38e5f2a196c7d84b0f3e6a25c19d7b8e04f1a6c3d5b920e7a8","nullable":true},"feeNonce":{"type":"string","description":"EIP-3009 nonce of the fee leg, recorded when the leg is submitted. **x402 rail only.** On that rail it is the key that ties an on-chain transfer back to this payment: `authorizationState(buyer, feeNonce)` answers definitively whether the leg was consumed, which is how a `Submitted` fee is resolved. `null` until the leg is submitted, and always `null` on MPP-tempo, whose fee leg is a native transaction with no EIP-3009 nonce — there the reconciliation key is `feeTxHash` instead. Not spendable on its own — the signed authorization is deliberately never stored.","example":"0x7b1e2c9d4f6a08b35e1c7d92a4e60f83b5271ac9de4086f1b73c25a90d8e4f16","nullable":true},"feeFailureReason":{"type":"string","description":"Why the routing fee did not collect. Its main job is `Released`: that status is ALSO the ordinary state of a fee that was legitimately never collectable, and the delegation cap reconciles either way because the reserve is handed back, so this is the only field that tells a systemic refusal from a healthy row. Set on `Failed` too — and on a `Submitted` row whose outcome could not be DETERMINED (the settlement call timed out or answered unrecoverably), where it says why the fee is still unresolved rather than that it failed; such a row is resolved by reading the chain, never by re-submitting. Common shapes, ILLUSTRATIVE rather than exhaustive: a third party’s own verdict where one was adjudicated (`amount_too_low` and the like); one of four classified prefixes where the leg could not be signed — `fee-leg insufficient-funds:` (the funding wallet cannot cover both legs), `fee-leg guard-refused:` (a misconfigured fee destination, amount or chain), `fee-leg sign-failed:` (an infrastructure fault — the RPC or signer was unavailable), `fee-leg rail-mismatch:` (a rail returned another rail’s leg; refused, not submitted); or plain prose from any other path that gives the reserve back — `upstream returned 502 — resource not delivered` for a routed hop that did not succeed (on `POST /route` this is the ordinary one), `the fee leg expired before it could be broadcast`, or a `reconciled: …` write-off from the reconciliation sweep. It ALSO answers the opposite question on a `feeStatus: None` row: `fee-not-quoted: <why>` means a fee rate is configured but none was quoted for this payment at all — no destination is set for the settlement chain, no fee submitter is usable, the rail cannot sign a fee leg, the settlement network does not map to a chain, the fee truncated below one atomic unit and could never have been transferred, or the quote was refused outright. Such a row is charged the merchant leg and nothing else, which is correct; the field is what tells a half-finished rollout collecting 0% from a deployment that never configured a fee. Diagnostic text for a human, NOT a stable contract — branch on `feeStatus`, never on this string, whose wording follows a third party on the adjudicated paths. Whitespace is collapsed and any embedded `scheme://…` URL is replaced with `[url]` before publication. `null` when no fee rate is configured, and while a quoted fee is still on its happy path. A non-null value does NOT on its own mean the fee went uncollected: a row whose outcome was once undetermined KEEPS the reason it recorded when the chain later proves the fee settled, so a `Settled` row can carry one. `feeStatus` is the field that says what happened.","example":"HTTP 400: {\"errorReason\":\"amount_too_low\",\"network\":\"eip155:84532\",\"success\":false}","nullable":true},"merchantSettlementObservedAt":{"type":"string","description":"When on-chain reconciliation OBSERVED that the merchant redeemed this payment’s authorization — i.e. the money really left your wallet. `null` on the ordinary path: a payment that settled cleanly is anchored by `txHash` and never needs this, and a rail with no EIP-3009 authorization (both MPP rails) can never record it. Read it TOGETHER with `status`, which answers a different question: `status` is what you GOT, this is what you PAID. The pair that matters is `status: Failed`/`Issued` WITH this set — the merchant took the money and delivered nothing, which is inherent to x402 (an `exact` authorization is a pull, so a merchant can always redeem and then error). Deliberately NOT folded into `status`: the three status values are unchanged, so nothing that already switches on them has to change. `txHash` is filled in alongside it whenever the settlement transaction can be identified on-chain, and is left null when it cannot — no hash is ever claimed that could not be verified. So on these rows a non-null `txHash` does NOT mean the payment succeeded: keep reading `status` for that.","nullable":true,"example":"2026-09-08T10:12:00.000Z"}},"required":["id","createdAt","status","protocol","network","amount","merchantAddress","delegationId","buyer"]},"PaymentsSummaryPointDto":{"type":"object","properties":{"date":{"type":"string","description":"Start of the time bucket (ISO-8601, UTC), truncated to the requested granularity.","example":"2026-07-01T00:00:00.000Z"},"value":{"type":"number","description":"Number of payment requests issued in the bucket.","example":12}},"required":["date","value"]},"PaymentsSummaryDto":{"type":"object","properties":{"total":{"type":"number","description":"Total payment requests in the period. Uncapped, unlike the (1000-row-capped) list endpoint.","example":137},"series":{"description":"Per-bucket counts, oldest first.","type":"array","items":{"$ref":"#/components/schemas/PaymentsSummaryPointDto"}}},"required":["total","series"]},"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","vgs"]},"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."},"orgId":{"type":"object","description":"Organization this card belongs to (null = personal).","nullable":true}},"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"}},"orgId":{"type":"object","description":"Move the card to an org (a valid orgId) or to personal (null). Omit to leave unchanged.","nullable":true}}},"ArdSearchQueryDto":{"type":"object","properties":{"text":{"type":"string","example":"find me a weather lookup tool","description":"Natural-language description of the need. Required for /search."},"filter":{"type":"object","description":"Structured constraints over the supported term set (type, tags, capabilities, publisher, pay:protocol, pay:currency, pay:network, pay:price). OR within a key, AND across keys. An unsupported key → 400 INVALID_ARGUMENT.","example":{"type":["application/a2a-agent-card+json"],"pay:protocol":["x402"]}}},"required":["text"]},"ArdSearchRequestDto":{"type":"object","properties":{"query":{"$ref":"#/components/schemas/ArdSearchQueryDto"},"federation":{"type":"string","enum":["auto","referrals","none"],"default":"auto","description":"Federation mode (ARD §5.4). `none`: this registry only. `referrals`: also return the configured peer registries in `referrals` (no outbound call). `auto`: fan out to peers and merge into one ranked list — gated by config, off by default, degrades to `none`."},"pageSize":{"type":"number","default":10,"minimum":1,"maximum":100},"pageToken":{"type":"string","description":"Opaque pagination token."}},"required":["query"]},"ArdSearchResultItemDto":{"type":"object","properties":{"identifier":{"type":"string","example":"urn:air:api.nevermined.app:service:webscrape-pro"},"score":{"type":"number","minimum":0,"maximum":100,"example":95,"description":"Relevance rating (0–100). NOT a trust/safety score."},"source":{"type":"string","format":"uri","example":"https://api.nevermined.app/api/v1/ard","description":"The registry endpoint where this entry was indexed."},"displayName":{"type":"string"},"type":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"capabilities":{"type":"array","items":{"type":"string"}},"updatedAt":{"type":"string"}},"required":["identifier","score","source"]},"ArdRegistryReferralDto":{"type":"object","properties":{"identifier":{"type":"string","example":"urn:air:nlweb.ai:registry:public"},"displayName":{"type":"string","example":"Public Agent Finder"},"type":{"type":"string","example":"application/ai-registry+json","description":"Registry media type (`application/ai-registry` or `application/ai-registry+json`)."},"url":{"type":"string","format":"uri","example":"https://finder.nlweb.ai/search"}},"required":["identifier","displayName","type","url"]},"ArdSearchResponseDto":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ArdSearchResultItemDto"}},"referrals":{"description":"Peer registries the caller may query next (ARD §5.4). Present only in `referrals` mode when at least one configured peer survives the self-origin guard; omitted otherwise.","type":"array","items":{"$ref":"#/components/schemas/ArdRegistryReferralDto"}},"pageToken":{"type":"string","description":"Token for the next page, when more results exist."}},"required":["results"]},"ArdExploreQueryDto":{"type":"object","properties":{"text":{"type":"string","example":"currency conversion"},"filter":{"type":"object","description":"Same supported term set as /search (see resolveArdFilter).","example":{"pay:protocol":["x402"]}}}},"ArdExploreFacetRequestDto":{"type":"object","properties":{"field":{"type":"string","example":"type","description":"Term path to aggregate. Phase 1 supports: type, publisher, pay:protocol, tags."},"limit":{"type":"number","default":20,"minimum":1,"description":"Max buckets returned."},"minCount":{"type":"number","default":1,"minimum":0,"description":"Suppress buckets below this count."}},"required":["field"]},"ArdExploreResultTypeDto":{"type":"object","properties":{"facets":{"type":"array","items":{"$ref":"#/components/schemas/ArdExploreFacetRequestDto"}}},"required":["facets"]},"ArdExploreRequestDto":{"type":"object","properties":{"query":{"$ref":"#/components/schemas/ArdExploreQueryDto"},"resultType":{"$ref":"#/components/schemas/ArdExploreResultTypeDto"}},"required":["resultType"]},"ArdExploreResponseDto":{"type":"object","properties":{"resultType":{"type":"string","enum":["facets"],"example":"facets"},"facets":{"type":"object","description":"Map of requested field → its facet result.","additionalProperties":{"$ref":"#/components/schemas/ArdExploreFacetResultDto"}}},"required":["resultType","facets"]},"ArdListResponseDto":{"type":"object","properties":{"items":{"description":"ARD entries; each carries at least `identifier`.","type":"array","items":{"type":"object"}},"total":{"type":"number","description":"Total matching entries in the registry."},"pageToken":{"type":"string","description":"Token for the next page, when more entries exist."}},"required":["items","total"]},"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"},"error":{"type":"string","description":"RFC 6749 §5.2 / RFC 8628 §3.5 top-level OAuth error string. Present only on the OAuth device-polling responses from `POST /oauth/token` (`authorization_pending`, `slow_down`, `expired_token`, `access_denied`), so a standards-compliant OAuth/device client can branch on it directly instead of on the Nevermined `code`. Absent on every other error.","example":"authorization_pending"},"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"},"error":{"type":"string","description":"RFC 6749 §5.2 / RFC 8628 §3.5 top-level OAuth error string. Present only on the OAuth device-polling responses from `POST /oauth/token` (`authorization_pending`, `slow_down`, `expired_token`, `access_denied`), so a standards-compliant OAuth/device client can branch on it directly instead of on the Nevermined `code`. Absent on every other error.","example":"authorization_pending"},"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"},"error":{"type":"string","description":"RFC 6749 §5.2 / RFC 8628 §3.5 top-level OAuth error string. Present only on the OAuth device-polling responses from `POST /oauth/token` (`authorization_pending`, `slow_down`, `expired_token`, `access_denied`), so a standards-compliant OAuth/device client can branch on it directly instead of on the Nevermined `code`. Absent on every other error.","example":"authorization_pending"},"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"},"error":{"type":"string","description":"RFC 6749 §5.2 / RFC 8628 §3.5 top-level OAuth error string. Present only on the OAuth device-polling responses from `POST /oauth/token` (`authorization_pending`, `slow_down`, `expired_token`, `access_denied`), so a standards-compliant OAuth/device client can branch on it directly instead of on the Nevermined `code`. Absent on every other error.","example":"authorization_pending"},"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"},"error":{"type":"string","description":"RFC 6749 §5.2 / RFC 8628 §3.5 top-level OAuth error string. Present only on the OAuth device-polling responses from `POST /oauth/token` (`authorization_pending`, `slow_down`, `expired_token`, `access_denied`), so a standards-compliant OAuth/device client can branch on it directly instead of on the Nevermined `code`. Absent on every other error.","example":"authorization_pending"},"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"},"error":{"type":"string","description":"RFC 6749 §5.2 / RFC 8628 §3.5 top-level OAuth error string. Present only on the OAuth device-polling responses from `POST /oauth/token` (`authorization_pending`, `slow_down`, `expired_token`, `access_denied`), so a standards-compliant OAuth/device client can branch on it directly instead of on the Nevermined `code`. Absent on every other error.","example":"authorization_pending"},"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"]}}}}