{"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; missing orgs return 404 and inactive or ineligible orgs return 403. 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"}}}},"403":{"description":"Organization inactive or not entitled"},"404":{"description":"Organization not found"}},"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; missing orgs return 404 and inactive or ineligible orgs return 403. 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"}}}},"403":{"description":"Organization inactive or not entitled"},"404":{"description":"Organization not found"}},"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; missing orgs return 404 and inactive or ineligible orgs return 403. 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"}}}},"403":{"description":"Organization inactive or not entitled"},"404":{"description":"Organization not found"}},"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,"example":1}},{"name":"offset","required":false,"in":"query","description":"Number of items per page. Defaults to 10.","schema":{"type":"integer","default":10,"example":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"],"example":"true"}}],"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","example":"a1b2c3d4-e5f6-4a90-8bcd-ef1234567890"}},{"name":"withPayer","required":false,"in":"query","description":"When \"true\", also resolve `fundingWalletAddress` — the wallet the Router crypto rail spends from (EOA / 7702 kernel, or the org wallet) — and `lockedInChannels`, what that wallet has locked in MPP payment channels. Opt-in because it adds a wallet lookup and a channel read.","schema":{"type":"string","enum":["true","false"],"example":"true"}}],"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","example":"a1b2c3d4-e5f6-4a90-8bcd-ef1234567890"}}],"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","example":"a1b2c3d4-e5f6-4a90-8bcd-ef1234567890"}},{"name":"page","required":false,"in":"query","description":"Page number (1-based). Defaults to 1.","schema":{"type":"integer","default":1,"example":1}},{"name":"offset","required":false,"in":"query","description":"Number of items per page. Defaults to 10.","schema":{"type":"integer","default":10,"example":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"}}}}},"404":{"description":"Not Found - The plan is not registered on its settlement network","content":{"application/json":{"schema":{"example":{"code":"BCK.PROTOCOL.0055","httpStatus":404,"message":"Payment plan does not exist on-chain"}}}}}},"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 - 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"}}}}},"404":{"description":"Not Found - The plan is not registered on its settlement network","content":{"application/json":{"schema":{"example":{"code":"BCK.PROTOCOL.0055","httpStatus":404,"message":"Payment plan does not exist on-chain"}}}}}},"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":"Publish (list) or unpublish (unlist) an agent in Nevermined's discovery: set `activate` to true to list the agent, false to unlist it. This is a visibility flag stored by Nevermined, not an on-chain change. 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":"Publish (list) or unpublish (unlist) a plan: set `activate` to true to list the plan, false to unlist it. This is a flag stored by Nevermined, not an on-chain change. An unlisted plan is hidden from discovery and can no longer be purchased (checkout, crypto order or x402 top-up), but subscribers keep spending the credits they already hold while their balance covers a call. 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":"paymentRail","required":false,"in":"query","description":"Only listed, paid plans purchasable on this rail: `fiat` (card checkout, pay-as-you-go excluded) or `crypto`. Pagination totals count the filtered set.","schema":{"enum":["fiat","crypto"],"type":"string","example":"fiat"}},{"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. `delegationConfig.delegationId` is a PLACEHOLDER — replace it with the id returned by `POST /delegation/create`, or this returns BCK.DELEGATION.0002 (404). See `cryptoDelegation` below for the one example that runs as-is.","value":{"accepted":{"scheme":"nvm:erc4337","network":"eip155:84532","planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071"},"delegationConfig":{"delegationId":"a1b2c3d4-e5f6-4a90-8bcd-ef1234567890"}}},"permissionWithAgent":{"summary":"Crypto permission with agent and endpoint","description":"Create a permission with agentId, endpoint, and httpVerb for validation. `delegationConfig.delegationId` is a PLACEHOLDER — replace it with the id returned by `POST /delegation/create`, or this returns BCK.DELEGATION.0002 (404). See `cryptoDelegation` below for the one example that runs as-is.","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"}},"delegationConfig":{"delegationId":"a1b2c3d4-e5f6-4a90-8bcd-ef1234567890"}}},"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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentX402AccessTokenDto"},"example":{"accessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwbGFuSWQiOiI0MzI5ODQzMjk4NDMyOSIsImFnZW50SWQiOiIxMjM0NTY3ODkwMTIzNDU2Nzg5MCIsInN1YnNjcmliZXJBZGRyZXNzIjoiMHhmMzlGZDZlNTFhYWQ4OEY2RjRjZTZhQjg4MjcyNzljZmZGYjkyMjY2IiwiaWF0IjoxNzM2NjAwMDAwLCJleHAiOjE3Mzc4MDk2MDB9.x402_signature_hash"}}}},"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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionListDto"},"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"}]}}}},"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`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402SettleResponseDto"},"example":{"success":true,"payer":"0xD4f58B60330bC59cB0A07eE6A1A66ad64244eC8c","transaction":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","network":"eip155:84532","billingModel":"credits","creditsRedeemed":"2","remainingBalance":"98"}}}},"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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionDetailsDto"},"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}}}},"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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NvmAPIResultDto"},"example":{"success":true,"message":"Permission revoked successfully"}}}},"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"},"client_id_metadata_document_supported":{"type":"boolean"},"authorization_response_iss_parameter_supported":{"type":"boolean"}}}}}}},"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/instructions.md":{"get":{"description":"Raw text/markdown playbook for an autonomous agent driving the Catalog and Router — discovery, the delegation-backed pay flow, and reconciliation. Public endpoint.","operationId":"CatalogController_catalogInstructionsMd","parameters":[],"responses":{"200":{"description":"catalog-instructions.md content (markdown)"}},"summary":"Agent-facing catalog buy instructions (Markdown)","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)"},"409":{"description":"Service URL change refused because it is bound to a verified claim (BCK.CATALOG.0052)"}},"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. Like publishing, re-listing requires an active paid tier and respects the per-tier catalog listing cap.","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"}}}},"403":{"description":"Org lacks an active paid tier (BCK.ENTITLEMENTS.0004) or is already at its per-tier catalog cap (BCK.ENTITLEMENTS.0005)"},"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/catalog/listings/{id}/validate":{"post":{"description":"Runs the same centralized point-in-time eligibility check used by the catalog monitor and returns actionable feedback. Longitudinal service health remains the monitor agent’s responsibility.","operationId":"CatalogListingsController_validate","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogValidationResultDto"}}}},"400":{"description":"Listing has an invalid target/endpoint shape (BCK.CATALOG.0019)"},"404":{"description":"Listing not found / not owned (BCK.CATALOG.0007)"},"409":{"description":"Listing is not pending (BCK.CATALOG.0016), or validation is already running (BCK.CATALOG.0018)"},"500":{"description":"Validation infrastructure failed (BCK.CATALOG.0015)"}},"security":[{"Authorization":[]}],"summary":"Validate and register an owned pending listing now","tags":["Agent Services Catalog"]}},"/api/v1/catalog/listings/{id}/claim/challenge":{"get":{"operationId":"CatalogClaimController_challenge","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"domain","required":true,"in":"query","description":"The public domain you control and are proving ownership of.","schema":{"example":"api.weatherwise.ai","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimChallengeDto"}}}},"404":{"description":"Not found / not claimable / domain mismatch (BCK.CATALOG.0042)"},"409":{"description":"Already owned (BCK.CATALOG.0043)"},"422":{"description":"Not claimable by domain (BCK.CATALOG.0045)"},"429":{"description":"Too many confirmation attempts (BCK.HTTP.429)"}},"security":[{"Authorization":[]}],"summary":"Get the DNS TXT / well-known record needed to claim a listing","tags":["Agent Services Catalog"]}},"/api/v1/catalog/listings/{id}/claim/verify":{"post":{"operationId":"CatalogClaimController_verify","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyClaimDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnerCatalogListingDto"}}}},"403":{"description":"Not an active member (BCK.AUTH.0004/0005/0008/0009) or organization Catalog entitlement/cap refused (BCK.ENTITLEMENTS.0004/0005)"},"404":{"description":"Not found / not claimable / domain mismatch (BCK.CATALOG.0042)"},"409":{"description":"Claimed by another prover first (BCK.CATALOG.0043) or adoption lock busy (BCK.CATALOG.0051)"},"422":{"description":"Domain not proven (0044) / not claimable (0045) / private IP (0046)"},"429":{"description":"Too many verification attempts (BCK.HTTP.429)"},"503":{"description":"Verification could not complete; retry (BCK.CATALOG.0047)"}},"security":[{"Authorization":[]}],"summary":"Verify domain ownership and adopt the listing","tags":["Agent Services Catalog"]}},"/api/v1/catalog/claim/by-slug/{slug}":{"get":{"description":"Requires an API key. Returns only the listing id, slug, title and Official flag.","operationId":"CatalogClaimController_claimBySlug","parameters":[{"name":"slug","required":true,"in":"path","schema":{"example":"webscrape-pro","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimListingSummaryDto"}}}},"401":{"description":"Missing/invalid API key (BCK.AUTH.0002 / BCK.APIKEY.0004)"},"404":{"description":"No listed service matches the slug (BCK.CATALOG.0001)"},"500":{"description":"Catalog read failed (BCK.CATALOG.0002)"}},"security":[{"Authorization":[]}],"summary":"Resolve a listing slug to its id and Official status for the claim flow","tags":["Agent Services Catalog"]}},"/api/v1/catalog/listings/{id}/claim":{"patch":{"operationId":"CatalogClaimController_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"}}}},"404":{"description":"Not owned by caller (BCK.CATALOG.0042)"}},"security":[{"Authorization":[]}],"summary":"Edit a listing you have claimed","tags":["Agent Services Catalog"]}},"/api/v1/catalog/scoring/analyses":{"post":{"operationId":"CatalogScoringOwnerController_requestAnalysis","parameters":[{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestScoringDto"}}}},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoringRequestAcceptedDto"}}}},"400":{"description":"Unsafe or malformed service URL"},"409":{"description":"An analysis is already active"}},"security":[{"Authorization":[]}],"summary":"Request a readiness analysis","tags":["Agent Services Catalog"]},"get":{"operationId":"CatalogScoringOwnerController_listHistory","parameters":[{"name":"cursor","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["deferred","queued","running","succeeded","failed"]}},{"name":"listingId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"agentDid","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoringHistoryPageDto"}}}}},"security":[{"Authorization":[]}],"summary":"List readiness analysis history","tags":["Agent Services Catalog"]}},"/api/v1/catalog/scoring/analyses/{id}/result":{"get":{"operationId":"CatalogScoringOwnerController_getResult","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoringResultDto"}}}},"400":{"description":"Analysis id must be a UUID"},"404":{"description":"Analysis not found or inaccessible"}},"security":[{"Authorization":[]}],"summary":"Get an immutable readiness report","tags":["Agent Services Catalog"]}},"/api/v1/catalog/scoring/analyses/{id}":{"get":{"operationId":"CatalogScoringOwnerController_getStatus","parameters":[{"name":"id","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoringStatusDto"}}}},"400":{"description":"Analysis id must be a UUID"},"404":{"description":"Analysis not found or inaccessible"}},"security":[{"Authorization":[]}],"summary":"Poll a readiness analysis","tags":["Agent Services Catalog"]}},"/api/v1/catalog/scoring/listings/latest":{"get":{"operationId":"CatalogScoringOwnerController_getLatest","parameters":[{"name":"listingIds","required":true,"in":"query","description":"Comma-separated listing identifiers","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoringLatestPageDto"}}}}},"security":[{"Authorization":[]}],"summary":"Get latest readiness summaries for owned listings","tags":["Agent Services Catalog"]}},"/api/v1/catalog/scoring/public/{slug}":{"get":{"operationId":"CatalogScoringPublicController_publicScore","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicReadinessDto"}}}},"404":{"description":"No published current readiness score"}},"summary":"Get a published current readiness score","tags":["Agent Services Catalog"]}},"/api/v1/catalog/scoring/badge/{slug}.svg":{"get":{"operationId":"CatalogScoringPublicController_badge","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"SVG readiness badge"},"304":{"description":"Badge has not changed"},"400":{"description":"Unknown badge style"},"404":{"description":"Listing is not published"}},"summary":"Get a published readiness badge","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); or the service is paid only over an MPP session (a payment channel), which only the Router-fetched routes (`/router/route`, `/router/svc`, `/router/proxy`) can pay (BCK.ROUTER.0041 — nothing signed or charged). 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 did not proceed — no money moved. Four 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; BCK.ROUTER.0018, the fee-inclusive price is above maxTotalCents (params includes requiredTotalMicros, requiredTotalCents, merchantCents, feeCents and maxTotalCents). None is safely auto-retryable without a deliberate client decision — 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. For the first, use a plain account key — or, if you hold a `commerce` grant, `POST /api/v1/router/commerce/route`, which spends that grant’s own delegation. For the second, mint a fresh API key (issued as v2). 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"}}}},"413":{"description":"Router JSON request body exceeds 5 MiB (BCK.ROUTER.0024).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"422":{"description":"The service challenge asks for no payment (BCK.ROUTER.0035): a zero amount, typically an auth-only wallet sign-in challenge the Router answers only on an auth:siwx or follow-up endpoint after your own wallet paid the service. The request is not malformed; nothing was signed or charged. Or an 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.","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`, plus `RateLimit-Remaining: 0` and `RateLimit-Reset` at the same expiry. A per-key 429 has bare `Retry-After` and no `RateLimit-*` triple. 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 lists by `delegationId` and by `from`/`to` (ISO-8601,\ninclusive on `createdAt`). Supplying `requestId` selects a separate exact caller-scoped\nlookup and ignores those list filters; it is not subject to the 1000-row export window.\nJSON answers an exact lookup with an explicit `presence` discriminator and\nzero or one `payments`; a failed lookup is an error, never `absent`. This also prevents an\nolder Router that ignores `requestId` from being mistaken for authoritative absence.\n`format=csv` returns a CSV file download instead of the JSON lookup envelope.","operationId":"listRouterPayments","parameters":[{"name":"delegationId","required":false,"in":"query","description":"Only list payments spent against this delegation id. Ignored with requestId.","schema":{"type":"string"}},{"name":"from","required":false,"in":"query","description":"ISO-8601 lower bound on createdAt (inclusive). Ignored with requestId.","schema":{"example":"2026-07-01T00:00:00Z","type":"string"}},{"name":"to","required":false,"in":"query","description":"ISO-8601 upper bound on createdAt (inclusive). Ignored with requestId.","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"}},{"name":"requestId","required":false,"in":"query","description":"Exact caller-scoped idempotency id, matched byte for byte as it was sent (no trimming). Selects authoritative reconciliation; other list filters are ignored.","schema":{"type":"string"}}],"responses":{"200":{"description":"A JSON array for a list; an explicit lookup envelope with requestId; or CSV with format=csv.","content":{"application/json":{"schema":{"oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/RouterPaymentRecordDto"}},{"$ref":"#/components/schemas/RouterPaymentLookupDto"}]}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"BCK.ROUTER.0001 — `from`/`to` are not valid ISO-8601 timestamps, or `requestId` is empty or not a single string.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"401":{"description":"Missing/invalid Nevermined API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"413":{"description":"Router JSON request body exceeds 5 MiB (BCK.ROUTER.0024).","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`).\nFor a slug GET, supply `path` and a separate `search` query string; an optional\n`maxTotalCents` refuses a quote whose fee-inclusive price exceeds it, before purchase.\nA free (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, and\n`X-Router-Credential-Header` — the `credentialHeader` field below — for a service that needs\nthat auth AND a payment). 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. For a cataloged slug whose upstream returned a non-2xx, `body` stays null here (nothing delivered — consistent with `RouteResultDto.body`). The STREAMING forms `/router/proxy` and `/router/svc/:slug` instead return a typed, host-free error on the HTTP status line — BCK.ROUTER.0019 (upstream 4xx) or BCK.ROUTER.0020 (upstream 5xx or 429) — with the original upstream status preserved. They forward only a JSON or URL-encoded request body (none on GET/HEAD), and refuse any other non-empty body (a multipart upload above all) with BCK.ROUTER.0026 (415) before anything is paid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteResultDto"}}}},"202":{"description":"The payment was made but the merchant had not answered within the sync budget (45 s): the call keeps running on the Router (bounded at 120 s) and its result will be readable by you for 24 hours at `resultUrl` (also the `Location` header) — poll `GET /api/v1/router/payments/{paymentId}/result`. Do not repeat the call: a retry with the same `requestId` returns this same answer, then the result. Only callers on API version 1.48 or later are answered this way; older versions wait as before.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoutePendingDto"}}}},"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); or the payment credential would overwrite a header you asked the Router to forward, with no `credentialHeader` naming where the service wants it instead (BCK.ROUTER.0021 — refused before minting, so no money moved). 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 did not proceed — no money moved. Four 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; BCK.ROUTER.0018, the fee-inclusive price is above maxTotalCents (params includes requiredTotalMicros, requiredTotalCents, merchantCents, feeCents and maxTotalCents). None is safely auto-retryable without a deliberate client decision — 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. For the first, use a plain account key — or, if you hold a `commerce` grant, `POST /api/v1/router/commerce/route`, which spends that grant’s own delegation. For the second, mint a fresh API key (issued as v2). 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. BCK.ROUTER.0029 — quoteId is invalid or belongs to another account; request a new quote before paying.","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); or quoteId does not match the exact quoted request, delegation, rail or total (BCK.ROUTER.0033 — nothing charged). Or the MPP session payment channel with this service is closing (BCK.ROUTER.0042) — its deposit reached its ceiling, or the service refused the channel, a top-up of its deposit, or the payment after a top-up: no payment was signed, reserved or charged (a top-up the Router sent only moves the wallet’s own funds into its channel, returned at close); retry later with the same requestId — the next call after the close opens a new channel.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"410":{"description":"BCK.ROUTER.0032 — quoteId expired before payment began. Nothing was charged; quote again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"413":{"description":"BCK.ROUTER.0024 — the Router JSON request body exceeds the global 5 MiB ceiling. BCK.ROUTER.0027 — a slug-addressed request body is larger than the catalog endpoint accepts (its `maxRequestBytes` on the catalog service detail). Refused before the service is contacted: nothing was paid by this request (a retry of an already-paid `requestId` gets the 409 BCK.ROUTER.0002 instead). `params` gives `bodyBytes` and `maxRequestBytes`; shrink the body or pick a service that takes it. On `/select` it means every otherwise-payable match is below the body, reported against the largest of their limits. Not retryable unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"422":{"description":"The service challenge asks for no payment (BCK.ROUTER.0035): a zero amount, typically an auth-only wallet sign-in challenge the Router answers only on an auth:siwx or follow-up endpoint after your own wallet paid the service. The request is not malformed; nothing was signed or charged. Or an 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. BCK.ROUTER.0036 — every catalog endpoint this slug-addressed call reaches is known to answer after the Router abandons a paid call (120 s), and the merchant charges on receipt, so paying would charge and deliver nothing. Refused before the service is contacted: nothing was paid by this request (a retry of an already-paid `requestId` gets the 409 BCK.ROUTER.0002 instead). `params.source` is `declared` (permanent) or `observed` (lifts at `params.liftsAt`). Pick another endpoint or service. On a declared free-follow-up path it is raised only when the service answers 402 (a free answer is relayed). Not retryable unchanged. Or BCK.ROUTER.0044 — the Router cannot collect its routing fee on this MPP session payment (a session’s fee is collected later in one transfer, never per call): `params.cause` is `org-wallet` (an organization wallet funds it — pay from a delegation funded by your own wallet) or `network` (this deployment does not collect session fees on that network). Nothing was signed, reserved or charged; not retryable unchanged.","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 (for an OAuth grant, one ceiling shared by every credential minted from it, across refreshes), 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`, plus `RateLimit-Remaining: 0` and `RateLimit-Reset` at the same expiry. A per-key 429 has bare `Retry-After` and no `RateLimit-*` triple. 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. BCK.ROUTER.0040 — the Router refused an inconsistent read or write of its MPP session payment-channel state, a server-side defect; the payment was refused before its credential reached the service, so nothing moved. Report it rather than retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"502":{"description":"BCK.ROUTER.0025 — the upstream reply was too large to deliver after a paid request; or BCK.ROUTER.0034 — the paid request got no response (timeout or connection failure). Either way the payment may have gone through: params carries the paymentId — reconcile via GET /api/v1/router/payments and do not retry with a fresh requestId.","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. Or BCK.ROUTER.0043 — the MPP session payment channel with this service is busy: another payment on it held it too long, the wallet’s signer or balance read did not answer in time, or a top-up of the channel was in flight or the service could not be reached to take one (`params.stage`: `lock`, `sign`, `balance` or `top-up`). Nothing was signed, reserved or charged; retry after a few seconds with the same requestId.","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/route/with-controls":{"post":{"description":"The guarded alias of POST /route for clients that require search or maxTotalCents support. A missing alias means the API is too old; do not retry a controlled request on /route.","operationId":"routeAndPayRequestWithControls","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyRequestDto"}}}},"responses":{"201":{"description":"Upstream response, relayed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteResultDto"}}}},"202":{"description":"The payment was made but the merchant had not answered within the sync budget (45 s): the call keeps running on the Router (bounded at 120 s) and its result will be readable by you for 24 hours at `resultUrl` (also the `Location` header) — poll `GET /api/v1/router/payments/{paymentId}/result`. Do not repeat the call: a retry with the same `requestId` returns this same answer, then the result. Only callers on API version 1.48 or later are answered this way; older versions wait as before.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoutePendingDto"}}}},"402":{"description":"The spend did not proceed — no money moved. Four 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; BCK.ROUTER.0018, the fee-inclusive price is above maxTotalCents (params includes requiredTotalMicros, requiredTotalCents, merchantCents, feeCents and maxTotalCents). None is safely auto-retryable without a deliberate client decision — branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"413":{"description":"BCK.ROUTER.0024 — the Router JSON request body exceeds the global 5 MiB ceiling. BCK.ROUTER.0027 — a slug-addressed request body is larger than the catalog endpoint accepts (its `maxRequestBytes` on the catalog service detail). Refused before the service is contacted: nothing was paid by this request (a retry of an already-paid `requestId` gets the 409 BCK.ROUTER.0002 instead). `params` gives `bodyBytes` and `maxRequestBytes`; shrink the body or pick a service that takes it. On `/select` it means every otherwise-payable match is below the body, reported against the largest of their limits. Not retryable unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"422":{"description":"The service challenge asks for no payment (BCK.ROUTER.0035): a zero amount, typically an auth-only wallet sign-in challenge the Router answers only on an auth:siwx or follow-up endpoint after your own wallet paid the service. The request is not malformed; nothing was signed or charged. Or an 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. BCK.ROUTER.0036 — every catalog endpoint this slug-addressed call reaches is known to answer after the Router abandons a paid call (120 s), and the merchant charges on receipt, so paying would charge and deliver nothing. Refused before the service is contacted: nothing was paid by this request (a retry of an already-paid `requestId` gets the 409 BCK.ROUTER.0002 instead). `params.source` is `declared` (permanent) or `observed` (lifts at `params.liftsAt`). Pick another endpoint or service. On a declared free-follow-up path it is raised only when the service answers 402 (a free answer is relayed). Not retryable unchanged. Or BCK.ROUTER.0044 — the Router cannot collect its routing fee on this MPP session payment (a session’s fee is collected later in one transfer, never per call): `params.cause` is `org-wallet` (an organization wallet funds it — pay from a delegation funded by your own wallet) or `network` (this deployment does not collect session fees on that network). Nothing was signed, reserved or charged; not retryable unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}}},"security":[{"Authorization":[]}],"summary":"Route and pay with an explicit query or per-call total ceiling (mode B)","tags":["Router"]}},"/api/v1/router/quote":{"post":{"description":"Ask what `POST /route` would charge for this call, WITHOUT paying it. The Router makes the\nsame unpaid probe `/route` makes, reads the 402, selects the payment option exactly as a\npayment would (MPP first, then x402) and prices it with the Router fee — then stops. Nothing\nis signed, no credential is minted, no payment is recorded and no delegation budget is\nreserved, so no money moves. A quote is not free of consequence, though: the unpaid probe\nreaches the service (one that does not charge for the request performs it), and a quote\nspends the same per-key and per-service rate limit as a payment — so quote once per decision\nrather than repeating it.\n\nUse it to decide whether ONE call fits the allocation you planned for it: compare\n`fee.capChargedMicros` (exact) or `fee.capChargedCents` (rounded up, the figure\n`maxTotalCents` is compared against) with what you want to spend, then call `/route` with\n`maxTotalCents` set to that figure so a price change between quote and call is refused rather\nthan paid.\n\n`delegationId` is optional. With it, the quote prices the options that delegation would select\n(an organization-wallet delegation pays only in its own currency, a card delegation pays over\nMPP-stripe, a recipient allowlist is enforced); without it, the options a personal crypto\ndelegation would select. `optionSet` says which. A quote checks neither the remaining cap nor\nthe wallet balance — those are the payment’s checks (BCK.ROUTER.0003, BCK.ROUTER.0009).\n\nProvide the target `url` OR a catalog `slug` (+ optional `path`, `search`, `method`, `headers`,\n`body`), as on `/route`. A non-402 answer returns `paymentRequired: false` with the upstream\nstatus only — the upstream body and headers are never returned.","operationId":"quoteRouteRequest","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequestDto"},"examples":{"quote-catalog-service":{"summary":"Quote a cataloged service","value":{"slug":"webscrape-pro","path":"scrape","method":"POST","body":{"url":"x"}}}}}}},"responses":{"200":{"description":"The quote. `paymentRequired: false` means the upstream did not ask for payment; otherwise `settlement` and `fee` are what `/route` would pay and reserve.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResultDto"}}}},"400":{"description":"Invalid request, no fundable option, a pay-to outside the delegation’s allowed recipients, 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) — the same refusals `/route` raises before paying. 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"}}}},"403":{"description":"BCK.OAUTH.0030 — an OAuth-minted key may not use the Router spend rails; use a plain account key. Permanent — do not retry. A `commerce` credential quotes on `POST /api/v1/router/commerce/quote` instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"404":{"description":"BCK.DELEGATION.0002 — no delegation with that `delegationId` belongs to this caller; or BCK.CATALOG.0001 — no listed catalog service has that `slug`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"409":{"description":"The target is a cataloged Nevermined service that must be addressed by its slug, not by raw URL (BCK.ROUTER.0014).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"413":{"description":"BCK.ROUTER.0024 — the Router JSON request body exceeds the global 5 MiB ceiling. BCK.ROUTER.0027 — a slug-addressed request body is larger than the catalog endpoint accepts (its `maxRequestBytes` on the catalog service detail). Refused before the service is contacted: nothing was paid by this request (a retry of an already-paid `requestId` gets the 409 BCK.ROUTER.0002 instead). `params` gives `bodyBytes` and `maxRequestBytes`; shrink the body or pick a service that takes it. On `/select` it means every otherwise-payable match is below the body, reported against the largest of their limits. Not retryable unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"422":{"description":"The service challenge asks for no payment (BCK.ROUTER.0035): a zero amount, typically an auth-only wallet sign-in challenge the Router answers only on an auth:siwx or follow-up endpoint after your own wallet paid the service. The request is not malformed; nothing was signed or charged. BCK.ROUTER.0036 — every catalog endpoint this slug-addressed call reaches is known to answer after the Router abandons a paid call (120 s), and the merchant charges on receipt, so paying would charge and deliver nothing. Refused before the service is contacted: nothing was paid by this request (a retry of an already-paid `requestId` gets the 409 BCK.ROUTER.0002 instead). `params.source` is `declared` (permanent) or `observed` (lifts at `params.liftsAt`). Pick another endpoint or service. On a declared free-follow-up path it is raised only when the service answers 402 (a free answer is relayed). Not retryable unchanged. Or BCK.ROUTER.0044 — the Router cannot collect its routing fee on this MPP session payment (a session’s fee is collected later in one transfer, never per call): `params.cause` is `org-wallet` (an organization wallet funds it — pay from a delegation funded by your own wallet) or `network` (this deployment does not collect session fees on that network). Nothing was signed, reserved or charged; not retryable unchanged.","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 (for an OAuth grant, one ceiling shared by every credential minted from it, across refreshes), 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`, plus `RateLimit-Remaining: 0` and `RateLimit-Reset` at the same expiry. A per-key 429 has bare `Retry-After` and no `RateLimit-*` triple. Retryable after a backoff either way.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"500":{"description":"BCK.ROUTER.0013 — Nevermined holds no EIP-712 signing domain for the selected settlement token; report it rather than looping. Any other 500 is an unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"503":{"description":"BCK.ROUTER.0028 — the quote could not be computed because a read it depends on failed. Nothing was signed or charged; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}}},"security":[{"Authorization":[]}],"summary":"Quote a Router call: the fee-inclusive price, rail and network, without paying","tags":["Router"]}},"/api/v1/router/commerce/quote":{"post":{"description":"The OAuth counterpart of `POST /api/v1/router/quote`, for a credential minted from a\n`commerce` authorization. Identical behaviour and identical response, with one difference:\n**you do not choose the delegation.** The quote prices the options the delegation your grant\nis pinned to would select, so it is what `POST /api/v1/router/commerce/route` would charge for\nthe same call. Sending a `delegationId` is refused, not ignored.\n\nNothing is signed, no credential is minted, no payment is recorded and no budget is reserved.\nThe Router still makes the unpaid request to the service, and the quote spends the same\nper-key and per-service rate budgets as a payment. Compare `fee.capChargedCents` with what you\nwant to spend, then call `/commerce/route` with `maxTotalCents` set to that figure.\n\nA plain (non-OAuth) API key cannot use this route: it has no grant to price. Use\n`POST /api/v1/router/quote` and name your own `delegationId` instead.","operationId":"quoteRouteRequestFromGrant","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommerceQuoteRequestDto"},"examples":{"quote-catalog-service":{"summary":"Quote a cataloged service against your grant","value":{"slug":"webscrape-pro","path":"scrape","method":"POST","body":{"url":"x"}}}}}}},"responses":{"200":{"description":"The quote. `paymentRequired: false` means the upstream did not ask for payment; otherwise `settlement` and `fee` are what `/commerce/route` would pay and reserve against the grant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResultDto"}}}},"400":{"description":"A `delegationId` was supplied (BCK.OAUTH.0034 — it is derived from your grant); or the refusals `/quote` makes: invalid request, no fundable option, a pay-to outside the delegation’s allowed recipients, or an upstream/402 error (BCK.ROUTER.0001), or an EIP-712 domain its 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 — or the grant behind this credential has been revoked by the user, in which case every credential minted from it is invalid: restart the authorization to obtain a new one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"403":{"description":"BCK.OAUTH.0033 — this credential is not a commerce grant, or its grant is not pinned to a usable delegation (re-run the authorization to mint a fresh mandate). BCK.OAUTH.0039 — this credits-only commerce grant has no stablecoin spending cap: use the subscription credit routes or ask the human to reconnect with a stablecoin cap.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"404":{"description":"BCK.DELEGATION.0002 — the delegation your grant is pinned to could not be resolved for this credential (re-run the authorization to mint a fresh mandate); or BCK.CATALOG.0001 — no listed catalog service has that `slug`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"409":{"description":"The target is a cataloged Nevermined service that must be addressed by its slug, not by raw URL (BCK.ROUTER.0014).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"413":{"description":"BCK.ROUTER.0024 — the Router JSON request body exceeds the global 5 MiB ceiling. BCK.ROUTER.0027 — a slug-addressed request body is larger than the catalog endpoint accepts (its `maxRequestBytes` on the catalog service detail). Refused before the service is contacted: nothing was paid by this request (a retry of an already-paid `requestId` gets the 409 BCK.ROUTER.0002 instead). `params` gives `bodyBytes` and `maxRequestBytes`; shrink the body or pick a service that takes it. On `/select` it means every otherwise-payable match is below the body, reported against the largest of their limits. Not retryable unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"422":{"description":"The service challenge asks for no payment (BCK.ROUTER.0035): a zero amount, typically an auth-only wallet sign-in challenge the Router answers only on an auth:siwx or follow-up endpoint after your own wallet paid the service. The request is not malformed; nothing was signed or charged. BCK.ROUTER.0036 — every catalog endpoint this slug-addressed call reaches is known to answer after the Router abandons a paid call (120 s), and the merchant charges on receipt, so paying would charge and deliver nothing. Refused before the service is contacted: nothing was paid by this request (a retry of an already-paid `requestId` gets the 409 BCK.ROUTER.0002 instead). `params.source` is `declared` (permanent) or `observed` (lifts at `params.liftsAt`). Pick another endpoint or service. On a declared free-follow-up path it is raised only when the service answers 402 (a free answer is relayed). Not retryable unchanged. Or BCK.ROUTER.0044 — the Router cannot collect its routing fee on this MPP session payment (a session’s fee is collected later in one transfer, never per call): `params.cause` is `org-wallet` (an organization wallet funds it — pay from a delegation funded by your own wallet) or `network` (this deployment does not collect session fees on that network). Nothing was signed, reserved or charged; not retryable unchanged.","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 (for an OAuth grant, one ceiling shared by every credential minted from it, across refreshes), 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`, plus `RateLimit-Remaining: 0` and `RateLimit-Reset` at the same expiry. A per-key 429 has bare `Retry-After` and no `RateLimit-*` triple. Retryable after a backoff either way.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"500":{"description":"BCK.ROUTER.0013 — Nevermined holds no EIP-712 signing domain for the selected settlement token; report it rather than looping. Any other 500 is an unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"503":{"description":"BCK.ROUTER.0028 — the quote could not be computed because a read it depends on failed. Nothing was signed or charged; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}}},"security":[{"Authorization":[]}],"summary":"Quote a Router call from your commerce grant, without paying (OAuth)","tags":["Router"]}},"/api/v1/router/select":{"post":{"description":"Send a plain-language description of what you need; the Router ranks the catalog (ARD hybrid\nrelevance blended with quality, relevance-dominant), applies a fail-closed payability gate, and\nreturns the single best PAYABLE service (`chosen`, by its OPAQUE invoke alias — never a raw\nhost) plus a ranked `shortlist` and the `rankingSource` used (`semantic` or `lexical`).\n\nSelection is DETERMINISTIC — no model reads the merchant-authored listings. It is OPT-IN: with\n`autoPay:false` (the default) nothing is charged. With `autoPay:true` the Router also pays and\nrelays the winner through the identical mode-B path as `POST /api/v1/router/route` (same rail\nselection, same fee leg); `autoPay` then REQUIRES `requestId` and `delegationId`.\n\nNo listed, healthy, payable candidate → `BCK.ROUTER.0001` (no fundable match), never a\nlow-relevance or unpayable fallback — EXCEPT an autoPay retry whose catalog has since emptied,\nwhich returns `BCK.ROUTER.0002` (already paid; carries the original paymentId), or\n`BCK.ROUTER.0023` (charge indeterminate) if the prior payment cannot be confirmed.\nEvery call is logged for audit/dispute — an autoPay retry with an already-paid `requestId`\nreuses the original request’s record.","operationId":"selectService","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SelectRequestDto"},"examples":{"select-only":{"summary":"Find the best service (no payment)","value":{"intent":"translate English to German","limit":5}},"select-and-pay":{"summary":"Find and pay the best service in one call","value":{"intent":"translate English to German","autoPay":true,"delegationId":"5e7481c3-e972-45bd-bdc5-a0b99c4de4a1","requestId":"order-1234","method":"POST","body":{"text":"Hello","to":"de"}}}}}}},"responses":{"201":{"description":"The chosen service (opaque invoke alias) + ranked shortlist + ranking source. When `autoPay` was true, also the mode-B `result` (upstream response + payment receipt).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SelectResultDto"}}}},"400":{"description":"Bad input, `autoPay` without `requestId`/`delegationId`, or NO fundable catalog match for the intent and filters (BCK.ROUTER.0001); or an unsupported filter term (BCK.ARD.0001). 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 did not proceed — no money moved. Four 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; BCK.ROUTER.0018, the fee-inclusive price is above maxTotalCents (params includes requiredTotalMicros, requiredTotalCents, merchantCents, feeCents and maxTotalCents). None is safely auto-retryable without a deliberate client decision — 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. For the first, use a plain account key — or, if you hold a `commerce` grant, `POST /api/v1/router/commerce/route`, which spends that grant’s own delegation. For the second, mint a fresh API key (issued as v2). 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":"On the autoPay leg: the `requestId` was already used — idempotency conflict (BCK.ROUTER.0002). Also returned by select() itself on a RETRY that can no longer re-select the paid service (its catalog emptied, or filter/ranking failed) while a prior payment is confirmed — already paid, carrying the original paymentId. BCK.ROUTER.0031 means the exact opaque service named by filters.require cannot be selected; nothing was charged. Or the MPP session payment channel with this service is closing (BCK.ROUTER.0042) — its deposit reached its ceiling, or the service refused the channel, a top-up of its deposit, or the payment after a top-up: no payment was signed, reserved or charged (a top-up the Router sent only moves the wallet’s own funds into its channel, returned at close); retry later with the same requestId — the next call after the close opens a new channel.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"413":{"description":"BCK.ROUTER.0024 — the Router JSON request body exceeds the global 5 MiB ceiling. BCK.ROUTER.0027 — a slug-addressed request body is larger than the catalog endpoint accepts (its `maxRequestBytes` on the catalog service detail). Refused before the service is contacted: nothing was paid by this request (a retry of an already-paid `requestId` gets the 409 BCK.ROUTER.0002 instead). `params` gives `bodyBytes` and `maxRequestBytes`; shrink the body or pick a service that takes it. On `/select` it means every otherwise-payable match is below the body, reported against the largest of their limits. Not retryable unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"422":{"description":"The service challenge asks for no payment (BCK.ROUTER.0035): a zero amount, typically an auth-only wallet sign-in challenge the Router answers only on an auth:siwx or follow-up endpoint after your own wallet paid the service. The request is not malformed; nothing was signed or charged. Or an 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. BCK.ROUTER.0036 — every catalog endpoint this slug-addressed call reaches is known to answer after the Router abandons a paid call (120 s), and the merchant charges on receipt, so paying would charge and deliver nothing. Refused before the service is contacted: nothing was paid by this request (a retry of an already-paid `requestId` gets the 409 BCK.ROUTER.0002 instead). `params.source` is `declared` (permanent) or `observed` (lifts at `params.liftsAt`). Pick another endpoint or service. On a declared free-follow-up path it is raised only when the service answers 402 (a free answer is relayed). Not retryable unchanged. Or BCK.ROUTER.0044 — the Router cannot collect its routing fee on this MPP session payment (a session’s fee is collected later in one transfer, never per call): `params.cause` is `org-wallet` (an organization wallet funds it — pay from a delegation funded by your own wallet) or `network` (this deployment does not collect session fees on that network). Nothing was signed, reserved or charged; not retryable unchanged.","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 (for an OAuth grant, one ceiling shared by every credential minted from it, across refreshes), 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`, plus `RateLimit-Remaining: 0` and `RateLimit-Reset` at the same expiry. A per-key 429 has bare `Retry-After` and no `RateLimit-*` triple. 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. BCK.ROUTER.0040 — the Router refused an inconsistent read or write of its MPP session payment-channel state, a server-side defect; the payment was refused before its credential reached the service, so nothing moved. Report it rather than retrying. BCK.ROUTER.0022 — server-side service selection is not wired on this deployment (a configuration fault, not your request); nothing was ranked or charged, retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"502":{"description":"On an autoPay select the charge outcome for this requestId is INDETERMINATE (BCK.ROUTER.0023): either the downstream Router call did not complete cleanly after the payment was created, or the Router could not determine whether an earlier attempt on this requestId charged (including when there was none). This includes an oversize paid upstream reply (BCK.ROUTER.0025 on /route), which was too large to deliver, and a paid request that got no response (BCK.ROUTER.0034 on /route); the payment may have gone through. Do NOT retry with a fresh requestId. Reconcile via GET /api/v1/router/payments, then reuse the SAME requestId to retry safely; params carries the paymentId when one is known.","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. Or BCK.ROUTER.0043 — the MPP session payment channel with this service is busy: another payment on it held it too long, the wallet’s signer or balance read did not answer in time, or a top-up of the channel was in flight or the service could not be reached to take one (`params.stage`: `lock`, `sign`, `balance` or `top-up`). Nothing was signed, reserved or charged; retry after a few seconds with the same requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}}},"security":[{"Authorization":[]}],"summary":"Select the best payable catalog service for an intent, optionally pay it (mode B)","tags":["Router"]}},"/api/v1/router/commerce/select":{"post":{"description":"The OAuth counterpart of `POST /api/v1/router/select`, for a credential minted from a\n`commerce` authorization. Send a plain-language description of what you need; the Router ranks\nthe catalog (ARD hybrid relevance blended with quality, relevance-dominant), applies a fail-closed\npayability gate, and returns the single best PAYABLE service (`chosen`, by its OPAQUE invoke\nalias — never a raw host) plus a ranked `shortlist` and the `rankingSource` used.\n\nSelection is DETERMINISTIC — no model reads the merchant-authored listings. It is OPT-IN: with\n`autoPay:false` (the default) nothing is charged. With `autoPay:true` the Router also pays and\nrelays the winner through the identical path as `POST /api/v1/router/commerce/route` — **and\nyou do not choose the delegation.** It is derived from your grant: the capped, expiring mandate\nthe user approved when they connected you. Sending a `delegationId` is refused, not ignored.\n\nA plain (non-OAuth) API key cannot use this route — it has no grant to derive from. Use\n`POST /api/v1/router/select` and name your own `delegationId` instead. No listed, healthy,\npayable candidate → `BCK.ROUTER.0001`, never a fallback — EXCEPT an autoPay retry whose catalog\nhas since emptied, which returns `BCK.ROUTER.0002` (already paid; carries the original paymentId),\nor `BCK.ROUTER.0023` (charge indeterminate) if the prior payment cannot be confirmed. Every call\nis logged for audit — an autoPay retry with an already-paid `requestId` reuses the original\nrequest’s record.","operationId":"selectServiceFromGrant","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommerceSelectRequestDto"},"examples":{"select-only":{"summary":"Find the best service (no payment)","value":{"intent":"translate English to German","limit":5}},"select-and-pay":{"summary":"Find and pay the best service in one call, from your grant","value":{"intent":"translate English to German","autoPay":true,"requestId":"order-1234","method":"POST","body":{"text":"Hello","to":"de"}}}}}}},"responses":{"201":{"description":"The chosen service (opaque invoke alias) + ranked shortlist + ranking source. When `autoPay` was true, also the mode-B `result` (upstream response + payment receipt).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SelectResultDto"}}}},"400":{"description":"Bad input, a `delegationId` was supplied (BCK.OAUTH.0034 — it is derived from your grant), `autoPay` without `requestId`, NO fundable catalog match for the intent and filters (BCK.ROUTER.0001), or an unsupported filter term (BCK.ARD.0001). 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 — or the grant behind this credential has been revoked by the user, in which case every credential minted from it is invalid: restart the authorization to obtain a new one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"402":{"description":"The spend did not proceed — no money moved. Four 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; BCK.ROUTER.0018, the fee-inclusive price is above maxTotalCents (params includes requiredTotalMicros, requiredTotalCents, merchantCents, feeCents and maxTotalCents). None is safely auto-retryable without a deliberate client decision — branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"403":{"description":"This credential is not a commerce grant or has no usable delegation (BCK.OAUTH.0033); a credits-only grant must use subscription credit routes or reconnect with a stablecoin cap (BCK.OAUTH.0039); 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 — the delegation your grant is pinned to could not be resolved for this credential: it is not this account’s, or it is bound to a different grant than the one you hold. Re-run the authorization to mint a fresh mandate. You never send a delegation id on this route, so this is not a wrong-id error; an expired, exhausted or revoked delegation is a 402 (BCK.ROUTER.0003) instead. 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":"On the autoPay leg: the `requestId` was already used — idempotency conflict (BCK.ROUTER.0002), also returned by select() itself on a RETRY that can no longer re-select the paid service (its catalog emptied, or filter/ranking failed) while a prior payment is confirmed (already paid, carrying the original paymentId) — or the resolved slug targets a cataloged service that must be invoked by slug (BCK.ROUTER.0014, not retryable). BCK.ROUTER.0031 means the exact opaque service named by filters.require cannot be selected; nothing was charged. Or the MPP session payment channel with this service is closing (BCK.ROUTER.0042) — its deposit reached its ceiling, or the service refused the channel, a top-up of its deposit, or the payment after a top-up: no payment was signed, reserved or charged (a top-up the Router sent only moves the wallet’s own funds into its channel, returned at close); retry later with the same requestId — the next call after the close opens a new channel.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"413":{"description":"BCK.ROUTER.0024 — the Router JSON request body exceeds the global 5 MiB ceiling. BCK.ROUTER.0027 — a slug-addressed request body is larger than the catalog endpoint accepts (its `maxRequestBytes` on the catalog service detail). Refused before the service is contacted: nothing was paid by this request (a retry of an already-paid `requestId` gets the 409 BCK.ROUTER.0002 instead). `params` gives `bodyBytes` and `maxRequestBytes`; shrink the body or pick a service that takes it. On `/select` it means every otherwise-payable match is below the body, reported against the largest of their limits. Not retryable unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"422":{"description":"The service challenge asks for no payment (BCK.ROUTER.0035): a zero amount, typically an auth-only wallet sign-in challenge the Router answers only on an auth:siwx or follow-up endpoint after your own wallet paid the service. The request is not malformed; nothing was signed or charged. Or an 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. BCK.ROUTER.0036 — every catalog endpoint this slug-addressed call reaches is known to answer after the Router abandons a paid call (120 s), and the merchant charges on receipt, so paying would charge and deliver nothing. Refused before the service is contacted: nothing was paid by this request (a retry of an already-paid `requestId` gets the 409 BCK.ROUTER.0002 instead). `params.source` is `declared` (permanent) or `observed` (lifts at `params.liftsAt`). Pick another endpoint or service. On a declared free-follow-up path it is raised only when the service answers 402 (a free answer is relayed). Not retryable unchanged. Or BCK.ROUTER.0044 — the Router cannot collect its routing fee on this MPP session payment (a session’s fee is collected later in one transfer, never per call): `params.cause` is `org-wallet` (an organization wallet funds it — pay from a delegation funded by your own wallet) or `network` (this deployment does not collect session fees on that network). Nothing was signed, reserved or charged; not retryable unchanged.","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 (for an OAuth grant, one ceiling shared by every credential minted from it, across refreshes), 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`, plus `RateLimit-Remaining: 0` and `RateLimit-Reset` at the same expiry. A per-key 429 has bare `Retry-After` and no `RateLimit-*` triple. 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. BCK.ROUTER.0040 — the Router refused an inconsistent read or write of its MPP session payment-channel state, a server-side defect; the payment was refused before its credential reached the service, so nothing moved. Report it rather than retrying. BCK.ROUTER.0022 — server-side service selection is not wired on this deployment (a configuration fault, not your request); nothing was ranked or charged, retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"502":{"description":"On an autoPay select the charge outcome for this requestId is INDETERMINATE (BCK.ROUTER.0023): either the downstream Router call did not complete cleanly after the payment was created, or the Router could not determine whether an earlier attempt on this requestId charged (including when there was none). This includes an oversize paid upstream reply (BCK.ROUTER.0025 on /route), which was too large to deliver, and a paid request that got no response (BCK.ROUTER.0034 on /route); the payment may have gone through. Do NOT retry with a fresh requestId. Reconcile via GET /api/v1/router/payments, then reuse the SAME requestId to retry safely; params carries the paymentId when one is known.","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. Or BCK.ROUTER.0043 — the MPP session payment channel with this service is busy: another payment on it held it too long, the wallet’s signer or balance read did not answer in time, or a top-up of the channel was in flight or the service could not be reached to take one (`params.stage`: `lock`, `sign`, `balance` or `top-up`). Nothing was signed, reserved or charged; retry after a few seconds with the same requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}}},"security":[{"Authorization":[]}],"summary":"Select the best payable catalog service for an intent, optionally pay it from your grant","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"},"examples":{"invoke-cataloged-service":{"summary":"Invoke a cataloged service through the broker, paid from the grant","value":{"slug":"webscrape-pro","path":"scrape","method":"POST","body":{"url":"https://example.com"},"requestId":"order-1234"}}}}}},"responses":{"201":{"description":"Upstream response, relayed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteResultDto"}}}},"202":{"description":"The payment was made but the merchant had not answered within the sync budget (45 s): the call keeps running on the Router (bounded at 120 s) and its result will be readable by you for 24 hours at `resultUrl` (also the `Location` header) — poll `GET /api/v1/router/payments/{paymentId}/result`. Do not repeat the call: a retry with the same `requestId` returns this same answer, then the result. Only callers on API version 1.48 or later are answered this way; older versions wait as before.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoutePendingDto"}}}},"400":{"description":"Malformed request, a `delegationId` was supplied (BCK.OAUTH.0034 — it is derived from your grant), both `url` and `slug` were given (BCK.ROUTER.0001), or the payment credential would overwrite a header you asked the Router to forward and no `credentialHeader` named where the service wants it instead (BCK.ROUTER.0021 — refused before minting).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"401":{"description":"Missing/invalid Nevermined API key — or the grant behind this credential has been revoked by the user, in which case every credential minted from it is invalid: restart the authorization to obtain a new one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"402":{"description":"The spend did not proceed — no money moved. Four 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; BCK.ROUTER.0018, the fee-inclusive price is above maxTotalCents (params includes requiredTotalMicros, requiredTotalCents, merchantCents, feeCents and maxTotalCents). None is safely auto-retryable without a deliberate client decision — branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"403":{"description":"This credential is not a commerce grant or has no usable delegation (BCK.OAUTH.0033); a credits-only grant must use subscription credit routes or reconnect with a stablecoin cap (BCK.OAUTH.0039); 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 — the delegation your grant is pinned to could not be resolved for this credential: it is not this account’s, or it is bound to a different grant than the one you hold. Re-run the authorization to mint a fresh mandate. You never send a delegation id on this route, so this is not a wrong-id error; an expired, exhausted or revoked delegation is a 402 (BCK.ROUTER.0003) instead. 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. BCK.ROUTER.0029 — quoteId is invalid or belongs to another account; request a new quote before paying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"409":{"description":"The `requestId` was already used — idempotency conflict (BCK.ROUTER.0002); the raw `url` targets a cataloged service and must be invoked by `slug` (BCK.ROUTER.0014, not retryable); or quoteId does not match the exact quoted request, grant delegation, rail or total (BCK.ROUTER.0033 — nothing charged). Or the MPP session payment channel with this service is closing (BCK.ROUTER.0042) — its deposit reached its ceiling, or the service refused the channel, a top-up of its deposit, or the payment after a top-up: no payment was signed, reserved or charged (a top-up the Router sent only moves the wallet’s own funds into its channel, returned at close); retry later with the same requestId — the next call after the close opens a new channel.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"410":{"description":"BCK.ROUTER.0032 — quoteId expired before payment began. Nothing was charged; quote again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"413":{"description":"BCK.ROUTER.0024 — the Router JSON request body exceeds the global 5 MiB ceiling. BCK.ROUTER.0027 — a slug-addressed request body is larger than the catalog endpoint accepts (its `maxRequestBytes` on the catalog service detail). Refused before the service is contacted: nothing was paid by this request (a retry of an already-paid `requestId` gets the 409 BCK.ROUTER.0002 instead). `params` gives `bodyBytes` and `maxRequestBytes`; shrink the body or pick a service that takes it. On `/select` it means every otherwise-payable match is below the body, reported against the largest of their limits. Not retryable unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"422":{"description":"The service challenge asks for no payment (BCK.ROUTER.0035): a zero amount, typically an auth-only wallet sign-in challenge the Router answers only on an auth:siwx or follow-up endpoint after your own wallet paid the service. The request is not malformed; nothing was signed or charged. Or an 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. BCK.ROUTER.0036 — every catalog endpoint this slug-addressed call reaches is known to answer after the Router abandons a paid call (120 s), and the merchant charges on receipt, so paying would charge and deliver nothing. Refused before the service is contacted: nothing was paid by this request (a retry of an already-paid `requestId` gets the 409 BCK.ROUTER.0002 instead). `params.source` is `declared` (permanent) or `observed` (lifts at `params.liftsAt`). Pick another endpoint or service. On a declared free-follow-up path it is raised only when the service answers 402 (a free answer is relayed). Not retryable unchanged. Or BCK.ROUTER.0044 — the Router cannot collect its routing fee on this MPP session payment (a session’s fee is collected later in one transfer, never per call): `params.cause` is `org-wallet` (an organization wallet funds it — pay from a delegation funded by your own wallet) or `network` (this deployment does not collect session fees on that network). Nothing was signed, reserved or charged; not retryable unchanged.","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 (for an OAuth grant, one ceiling shared by every credential minted from it, across refreshes), 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`, plus `RateLimit-Remaining: 0` and `RateLimit-Reset` at the same expiry. A per-key 429 has bare `Retry-After` and no `RateLimit-*` triple. 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. BCK.ROUTER.0040 — the Router refused an inconsistent read or write of its MPP session payment-channel state, a server-side defect; the payment was refused before its credential reached the service, so nothing moved. Report it rather than retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"502":{"description":"BCK.ROUTER.0025 — the upstream reply was too large to deliver after a paid request; or BCK.ROUTER.0034 — the paid request got no response (timeout or connection failure). Either way the payment may have gone through: params carries the paymentId — reconcile via GET /api/v1/router/payments and do not retry with a fresh requestId.","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. Or BCK.ROUTER.0043 — the MPP session payment channel with this service is busy: another payment on it held it too long, the wallet’s signer or balance read did not answer in time, or a top-up of the channel was in flight or the service could not be reached to take one (`params.stage`: `lock`, `sign`, `balance` or `top-up`). Nothing was signed, reserved or charged; retry after a few seconds with the same requestId.","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/commerce/route/with-controls":{"post":{"description":"The guarded alias of POST /commerce/route for clients that require search or maxTotalCents support. A missing alias means the API is too old; do not retry a controlled request on /commerce/route.","operationId":"routeAndPayRequestFromGrantWithControls","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommerceRouteRequestDto"}}}},"responses":{"201":{"description":"Upstream response, relayed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteResultDto"}}}},"202":{"description":"The payment was made but the merchant had not answered within the sync budget (45 s): the call keeps running on the Router (bounded at 120 s) and its result will be readable by you for 24 hours at `resultUrl` (also the `Location` header) — poll `GET /api/v1/router/payments/{paymentId}/result`. Do not repeat the call: a retry with the same `requestId` returns this same answer, then the result. Only callers on API version 1.48 or later are answered this way; older versions wait as before.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoutePendingDto"}}}},"402":{"description":"The spend did not proceed — no money moved. Four 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; BCK.ROUTER.0018, the fee-inclusive price is above maxTotalCents (params includes requiredTotalMicros, requiredTotalCents, merchantCents, feeCents and maxTotalCents). None is safely auto-retryable without a deliberate client decision — branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"403":{"description":"This credential is not a commerce grant or has no usable delegation (BCK.OAUTH.0033); a credits-only grant must use subscription credit routes or reconnect with a stablecoin cap (BCK.OAUTH.0039); or the EIP-7702 wallet gate refused the key (BCK.ROUTER.0008).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"413":{"description":"BCK.ROUTER.0024 — the Router JSON request body exceeds the global 5 MiB ceiling. BCK.ROUTER.0027 — a slug-addressed request body is larger than the catalog endpoint accepts (its `maxRequestBytes` on the catalog service detail). Refused before the service is contacted: nothing was paid by this request (a retry of an already-paid `requestId` gets the 409 BCK.ROUTER.0002 instead). `params` gives `bodyBytes` and `maxRequestBytes`; shrink the body or pick a service that takes it. On `/select` it means every otherwise-payable match is below the body, reported against the largest of their limits. Not retryable unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"422":{"description":"The service challenge asks for no payment (BCK.ROUTER.0035): a zero amount, typically an auth-only wallet sign-in challenge the Router answers only on an auth:siwx or follow-up endpoint after your own wallet paid the service. The request is not malformed; nothing was signed or charged. Or an 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. BCK.ROUTER.0036 — every catalog endpoint this slug-addressed call reaches is known to answer after the Router abandons a paid call (120 s), and the merchant charges on receipt, so paying would charge and deliver nothing. Refused before the service is contacted: nothing was paid by this request (a retry of an already-paid `requestId` gets the 409 BCK.ROUTER.0002 instead). `params.source` is `declared` (permanent) or `observed` (lifts at `params.liftsAt`). Pick another endpoint or service. On a declared free-follow-up path it is raised only when the service answers 402 (a free answer is relayed). Not retryable unchanged. Or BCK.ROUTER.0044 — the Router cannot collect its routing fee on this MPP session payment (a session’s fee is collected later in one transfer, never per call): `params.cause` is `org-wallet` (an organization wallet funds it — pay from a delegation funded by your own wallet) or `network` (this deployment does not collect session fees on that network). Nothing was signed, reserved or charged; not retryable unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}}},"security":[{"Authorization":[]}],"summary":"Route and pay from a commerce grant with explicit query or per-call total ceiling","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"}}}},"413":{"description":"Router JSON request body exceeds 5 MiB (BCK.ROUTER.0024).","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/{id}/result":{"get":{"description":"Every paid call made through `POST /router/route` (and its `commerce` counterpart) is kept for\nyou, the paying user, for 24 hours after it ends, so a response lost on the way back — your\nHTTP client timed out, the connection dropped — can still be read. `/router/proxy` and\n`/router/svc` keep a result only when they answered `202` (see below); a response that had\nalready started streaming to you is never stored.\n\nA paid call whose merchant has not answered within the sync budget (45 s) is answered `202`\nwith `{ paymentId, resultUrl, status: \"Pending\" }` (or, on the streaming surfaces, `202` with\n`Location` and `X-Router-Payment-Id`) instead of holding your connection. It keeps running on\nthe Router — bounded at 120 s on the `/router/route` family; a streamed call waits up to 120 s\nfor the service to start answering, then its body may take up to the stream deadline (5\nminutes by default, never more than 10) — and its fee is collected on a 2xx or released\notherwise exactly as for a call that waited. Poll this endpoint until it leaves `Pending`:\n\n- `202`, `state: Pending` — still running.\n- `200`, `state: Ready` — `status` and `body` are the relayed response, withheld exactly as the\n  original response would have been.\n- `200`, `state: Failed` — the call ended without a response; `failureReason` says why.\n- `404` `BCK.ROUTER.0030` — nothing to return: expired, never retained, or not a payment of\n  yours (the three are deliberately indistinguishable).\n\nOnly clients on API version 1.48 or later are ever answered `202`; the result is retained for\nevery caller. Retrying the original request with the same `requestId` also returns the retained\nresult (or the same `202`) rather than `409`, from API 1.48.","operationId":"getRouterPaymentResult","parameters":[{"name":"id","required":true,"in":"path","description":"The `paymentId` of the paid call.","schema":{"example":"b1f9c2e4-8a3d-4f27-9c6b-5d2e17a04f8b","type":"string"}}],"responses":{"200":{"description":"The result is `Ready`, or the call ended `Failed`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterPaymentResultDto"}}}},"202":{"description":"The paid call is still running (`state: Pending`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterPaymentResultDto"}}}},"400":{"description":"`id` is not a valid uuid (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 retained result for this id under your account — expired, never retained, or not yours (BCK.ROUTER.0030).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"413":{"description":"Router JSON request body exceeds 5 MiB (BCK.ROUTER.0024).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}}},"security":[{"Authorization":[]}],"summary":"Read a paid Router result (retained for 24 hours)","tags":["Router"]}},"/api/v1/router/delegations/{id}":{"get":{"description":"Returns your delegation’s spending cap and the spend recorded against it, both in micros\n(millionths of the currency unit, i.e. 1/10,000 of a cent) as decimal strings. Compare the\ntwo for remaining headroom; an over-spend is reported honestly (`spentMicros > capMicros`),\nnever floored. Scoped to the calling user: a delegation that is not yours answers the same\n`404` as one that does not exist, so this is not a delegation-existence oracle.","operationId":"getRouterDelegationCap","parameters":[{"name":"id","required":true,"in":"path","description":"UUID v4 of the delegation.","schema":{"type":"string","format":"uuid","example":"28f2b44a-b643-4cb0-844f-bc454dcd3fad"}}],"responses":{"200":{"description":"The delegation’s cap and spend so far.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterDelegationCapDto"}}}},"400":{"description":"`id` is not a valid v4 uuid (BCK.DELEGATION.0009).","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 delegation with this id under your account — unknown or not yours (BCK.DELEGATION.0002).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}},"413":{"description":"Router JSON request body exceeds 5 MiB (BCK.ROUTER.0024).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterErrorResponseDto"}}}}},"security":[{"Authorization":[]}],"summary":"Read a delegation’s spend cap and spend so far","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"}}}},"413":{"description":"Router JSON request body exceeds 5 MiB (BCK.ROUTER.0024).","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/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`, a closed `matchReason`, per-item `rankingSource`, exactly one scale-specific score, 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. Optional `Authorization: Bearer <api-key>`: for an account that can use the Nevermined Subscription, each `nvm:catalog.endpoints[]` entry the subscription can pay carries `subscription: { creditsPerCall, tariffVersion }` (credits per call, from the rate card — never derived from the USD price), and `nvm:catalog.subscription` is the service default when it prices one of them. No `subscription` field means credits cannot pay that endpoint. A missing or refused key is served the anonymous response, never a 401. A keyed read counts against the per-key rate limit of that key and is never shared-cached. Peer results never carry it.","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. Optional `Authorization: Bearer <api-key>`: for an account that can use the Nevermined Subscription, each `nvm:catalog.endpoints[]` entry the subscription can pay carries `subscription: { creditsPerCall, tariffVersion }` (credits per call, from the rate card — never derived from the USD price), and `nvm:catalog.subscription` is the service default when it prices one of them. No `subscription` field means credits cannot pay that endpoint. A missing or refused key is served the anonymous response, never a 401. A keyed read counts against the per-key rate limit of that key and is never shared-cached.","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 (one of: rankScore, updatedAt, createdAt, title). Omit it for the default curated ranking (tier, editorial sortWeight, then tier-neutral rankScore). No relevance sorting (that is /search).","schema":{"example":"rankScore 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"]}},"/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","example":"true"}},{"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","example":"stripe"}}],"responses":{"200":{"description":"List of saved payment methods","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethodSummaryDto"}}}}},"400":{"description":"Bad Request - Unknown provider value"},"401":{"description":"Unauthorized - Invalid or missing API key"}},"security":[{"Authorization":[]}],"summary":"List saved payment methods","tags":["Payment Methods"]}},"/api/v1/payment-methods/{paymentMethodId}":{"patch":{"description":"Updates a saved payment method, changing its friendly alias and/or the set of NVM API keys allowed to use it. Requires a Nevermined API key.","operationId":"PaymentMethodsController_updatePaymentMethod","parameters":[{"name":"paymentMethodId","required":true,"in":"path","description":"Identifier of the payment method to update","schema":{"example":"pm_1Abc2Def3Ghi4Jkl","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePaymentMethodDto"}}}},"responses":{"200":{"description":"The updated payment method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentMethodSummaryDto"}}}},"401":{"description":"Unauthorized - Invalid or missing API key"},"404":{"description":"Not Found - Payment method does not exist"}},"security":[{"Authorization":[]}],"summary":"Update a payment method","tags":["Payment Methods"]},"delete":{"description":"Revokes (detaches) a saved payment method so it can no longer be used for delegated payments. Requires a Nevermined API key.","operationId":"PaymentMethodsController_revokePaymentMethod","parameters":[{"name":"paymentMethodId","required":true,"in":"path","description":"Identifier of the payment method to revoke","schema":{"example":"pm_1Abc2Def3Ghi4Jkl","type":"string"}}],"responses":{"200":{"description":"Payment method revoked","content":{"application/json":{"schema":{"example":{"success":true}}}}},"401":{"description":"Unauthorized - Invalid or missing API key"},"404":{"description":"Not Found - Payment method does not exist"}},"security":[{"Authorization":[]}],"summary":"Revoke a payment method","tags":["Payment Methods"]}}},"info":{"title":"NVM BACKEND API","description":"","version":"1.86.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"]},"LockedChannelFundsDto":{"type":"object","properties":{"network":{"type":"integer","example":4217,"description":"Chain id the payment channels are on"},"token":{"type":"string","example":"0x20C000000000000000000000b9537d11c60E8b50","description":"The token the channels hold in escrow, EIP-55 checksummed"},"symbol":{"type":"string","example":"USDC.e","nullable":true,"description":"Ticker, or null when the token is not one Nevermined recognises"},"decimals":{"type":"integer","example":6,"nullable":true,"description":"Decimal scale of `atomic`, or null when unknown"},"atomic":{"type":"string","example":"6000000","pattern":"^(0|[1-9][0-9]*)$","description":"Atomic (integer) amount locked, as a string: over every payment channel on this chain and token that is not closed yet, the deposit minus the payments its vouchers already authorized."},"formatted":{"type":"string","example":"6","nullable":true,"description":"Human-readable amount; null exactly when `decimals` is"}},"required":["network","token","symbol","decimals","atomic","formatted"]},"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 for every provider, including `vgs` and `visa` card delegations (whose merchant is resolved at payment time from the plan being paid).","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","enum":["stripe","braintree","erc4337","visa","vgs"]},"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","description":"What the delegation has spent, rounded UP to a whole cent. The cap accrues at sub-cent resolution — `amountSpentMicros` is the exact figure — so this is within one cent of it, and `amountSpentCents + remainingBudgetCents` equals `spendingLimitCents` while the delegation is within its cap."},"amountSpentMicros":{"type":"string","example":"24995000","description":"What the delegation has spent, in micros — millionths of the currency unit, i.e. 1/10,000 of a cent. The figure the spending cap is enforced on."},"remainingBudgetCents":{"type":"string","example":"7500","description":"Whole cents left under the cap: `spendingLimitCents - amountSpentCents`, never negative."},"remainingBudgetMicros":{"type":"string","example":"75005000","description":"Micros left under the cap, never negative. A delegation with any micros left can still take a payment that fits in them, even when `remainingBudgetCents` reads 0."},"currency":{"type":"string","example":"usd"},"transactionCount":{"type":"number","example":12},"maxTransactions":{"type":"number","example":50,"nullable":true,"description":"Maximum number of payments this delegation may make, or null for no count limit."},"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,"description":"Plan this delegation is restricted to, or null for a plan-agnostic one that can pay any plan. Applies to every provider, `visa` included: a Visa delegation created without a plan is null here, while one created with a plan keeps it and can only settle that plan."}},"required":["delegationId","provider","providerPaymentMethodId","status","spendingLimitCents","amountSpentCents","amountSpentMicros","remainingBudgetCents","remainingBudgetMicros","currency","transactionCount","maxTransactions","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","enum":["stripe","braintree","erc4337","visa","vgs"]},"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","description":"What the delegation has spent, rounded UP to a whole cent. The cap accrues at sub-cent resolution — `amountSpentMicros` is the exact figure — so this is within one cent of it, and `amountSpentCents + remainingBudgetCents` equals `spendingLimitCents` while the delegation is within its cap."},"amountSpentMicros":{"type":"string","example":"24995000","description":"What the delegation has spent, in micros — millionths of the currency unit, i.e. 1/10,000 of a cent. The figure the spending cap is enforced on."},"remainingBudgetCents":{"type":"string","example":"7500","description":"Whole cents left under the cap: `spendingLimitCents - amountSpentCents`, never negative."},"remainingBudgetMicros":{"type":"string","example":"75005000","description":"Micros left under the cap, never negative. A delegation with any micros left can still take a payment that fits in them, even when `remainingBudgetCents` reads 0."},"currency":{"type":"string","example":"usd"},"transactionCount":{"type":"number","example":12},"maxTransactions":{"type":"number","example":50,"nullable":true,"description":"Maximum number of payments this delegation may make, or null for no count limit."},"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,"description":"Plan this delegation is restricted to, or null for a plan-agnostic one that can pay any plan. Applies to every provider, `visa` included: a Visa delegation created without a plan is null here, while one created with a plan keeps it and can only settle that plan."},"lastUsedAt":{"type":"string","example":"2026-02-13T14:00:00Z","nullable":true,"format":"date-time"},"fundingWalletAddress":{"type":"string","example":"0x1234abcd5678ef901234abcd5678ef901234abcd","nullable":true,"description":"On-chain wallet the Router crypto rail spends from for this delegation — the caller EOA (7702 kernel address for migrated wallets) for a personal delegation, or the organization wallet for an org-wallet delegation. Fund/check THIS wallet before a Router call. For a personal delegation the Router does NOT spend from `providerPaymentMethodId` (the smart-account address) — it spends from the EOA; for an org-wallet delegation `providerPaymentMethodId` IS this wallet. (On the default wallet mode the same delegation used for a plan-purchase settles from the smart account instead — this field is the Router payer specifically.) Only returned when requested with `?withPayer=true`. `null` on card-backed delegations (a card is not funded from a wallet — tell them apart by `provider`: `erc4337` is the crypto rail); `null` on a crypto delegation means the payer wallet could not be resolved — either the owner profile has no wallet (permanent) or the lookup failed transiently."},"lockedInChannels":{"nullable":true,"description":"Money `fundingWalletAddress` has deposited into MPP session payment channels and can still get back, per chain and token. It has left the wallet but it is not spent and it is not charged to this budget: it comes back to the wallet when the channel closes. It is the FUNDING WALLET’s total, not a per-delegation figure: every delegation spending from the same wallet reports the same channels. Only returned when requested with `?withPayer=true`. An empty list means nothing is locked, and is what a card-backed delegation reports. `null` means it could not be determined (the funding wallet could not be resolved, or the read failed), which is not the same as nothing locked.","type":"array","items":{"$ref":"#/components/schemas/LockedChannelFundsDto"}}},"required":["delegationId","provider","providerPaymentMethodId","status","spendingLimitCents","amountSpentCents","amountSpentMicros","remainingBudgetCents","remainingBudgetMicros","currency","transactionCount","maxTransactions","expiresAt","createdAt","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},"feeCents":{"type":"string","description":"Nevermined’s routing fee for this charge, in cents, already INCLUDED in `amountCents`. Charged only on payments routed to an external merchant via the Router — `\"0\"` on every other row (a plan purchase on the card rails, or a crypto settlement), where no routing fee applies. On a Router row `amountCents - feeCents` is the merchant leg — **unless `feeReleased` is `true`, in which case `amountCents` is ALREADY net of the fee and must not be reduced again**. On other rows the identity does not hold either, because a plan purchase can carry a platform margin taken out of the price that this figure does not describe. **`\"0\"` does not by itself mean no fee applied:** the two figures round in opposite directions, so a fee too small to add a cent to the reserve still shows here as `\"0\"`. Read `feeAtomic` to answer that.","example":"0"},"feeAtomic":{"type":"string","description":"The same fee in the settlement asset’s smallest unit, rounded down. This is the field that answers “did a routing fee apply at all” — `\"0\"` means none did. The asset it is denominated in is the one the Router settled, reported on `GET /router/payments`; it is NOT the same unit as `amountCents`.","example":"0"},"feeBps":{"type":"number","description":"The fee rate applied, in basis points over a 10,000 denominator. Pinned per row, so a later rate change never rewrites what an old payment was charged. `0` when no fee applied.","example":0},"feeReleased":{"type":"boolean","description":"True when the routing fee was not collected and has been credited back to your cap. Non-delivery by the merchant is one cause; a fee leg that was refused, or expired before it could be broadcast, is another — so this does NOT mean the merchant failed you. **`amountCents` has ALREADY been reduced by `feeCents` when this is true**, so do not subtract the fee a second time. It does not follow that the remainder is the merchant leg: a payment whose merchant reserve was also released has that deducted from the same field and reads `status: 'failed'`. A fee too small to reserve a cent is released without ever setting this flag, so a row may read `false` here while `GET /router/payments` reports the fee `Released`; `amountCents` is untouched in that case, so the arithmetic above still holds.","example":false},"createdAt":{"format":"date-time","type":"string","example":"2026-02-13T14:00:00Z"}},"required":["id","delegationId","providerTransactionId","amountCents","currency","status","failureReason","feeCents","feeAtomic","feeBps","feeReleased","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?network=live","description":"Where the human goes to enter the user_code and approve."},"verification_uri_complete":{"type":"string","example":"https://nevermined.app/oauth/device?network=live&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.","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"]},"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/run","description":"Canonical HTTP(S) service target. A bare origin is a multi-endpoint gateway; a URL with a path is one payable endpoint. Surrounding whitespace, any userinfo credentials, a URL fragment, and a trailing origin slash are normalized away automatically; a query string is rejected."},"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"]},"CatalogEndpointQuoteRangeDto":{"type":"object","properties":{"minAtomic":{"type":"string","example":"1000"},"maxAtomic":{"type":"string","example":"50000"}},"required":["minAtomic","maxAtomic"]},"CatalogEndpointQuoteOfferDto":{"type":"object","properties":{"rail":{"type":"string","enum":["x402","mpp"],"example":"x402"},"network":{"type":"string","example":"eip155:8453"},"intent":{"type":"string","example":"exact"},"asset":{"type":"string","example":"USDC"},"amountAtomic":{"type":"string","example":"4000"},"selected":{"type":"boolean","description":"Present (true) on the offer the Router would pay."}},"required":["rail","network"]},"CatalogEndpointQuoteDto":{"type":"object","properties":{"rail":{"type":"string","enum":["x402","mpp"],"example":"mpp","description":"The rail the Router pays this endpoint on: its own choice for the live 402 (MPP first)."},"intent":{"type":"string","nullable":true,"example":"charge","description":"The settlement scheme: x402 `exact`, MPP `charge`."},"network":{"type":"string","example":"tempo","description":"The settlement network."},"asset":{"type":"string","nullable":true,"example":"USDC","description":"The asset: a symbol, or the token address where the rail names no symbol."},"amountAtomic":{"type":"string","example":"4000","description":"The merchant's price per call, in atomic units. It EXCLUDES the Router's routing fee, which the delegation cap is also charged; POST /api/v1/router/quote returns the total."},"decimals":{"type":"number","nullable":true,"example":6},"observedAt":{"type":"string","format":"date-time","description":"When the 402 this quote was read from was observed. Shown for 48 h."},"variable":{"type":"boolean","description":"The price depends on the request; see range and driver."},"range":{"$ref":"#/components/schemas/CatalogEndpointQuoteRangeDto"},"driver":{"type":"string","example":"max_tokens","description":"The request field that drives a variable price."},"offers":{"description":"OWNER READ ONLY (GET /api/v1/catalog/mine): every rail and network the 402 offered, the selected one marked. Never present on a public read.","type":"array","items":{"$ref":"#/components/schemas/CatalogEndpointQuoteOfferDto"}}},"required":["rail","intent","network","asset","amountAtomic","decimals","observedAt","variable"]},"CatalogEndpointDto":{"type":"object","properties":{"path":{"type":"string","example":"/scrape"},"method":{"type":"string","example":"POST"},"verificationStatus":{"type":"string","enum":["verified-by-canary","unverified","degraded"],"description":"Current endpoint verification from continuous canary observations."},"verifiedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the endpoint most recently passed its verified canary request."},"description":{"type":"string","example":"Scrape a URL to structured JSON"},"priceLabel":{"type":"string","example":"$0.004"},"auth":{"type":"string","enum":["siwx"],"description":"Set when the endpoint is not paid but wallet-authenticated (the merchant OpenAPI security scheme). siwx: free, only for the wallet that paid an earlier call to this service, e.g. a job or result poll. Call it through the Router with the id that paid call returned; the Router signs the wallet challenge. Absent for paid endpoints."},"invokePath":{"type":"string","example":"","description":"Suffix for the Router slug route, not the upstream path above. Empty means the advertised endpoint is already the slug base. Use this as the route body path or /svc subpath."},"requestExample":{"type":"object","example":{"body":{"q":"Apple"}},"description":"Redacted payable-wrapper input, sent verbatim by pay_service. Check exampleEvidence: paid-run was observed in a successful invocation, challenge proves the request shape only, docs is unverified."},"responseSchema":{"type":"object","description":"Sanitised merchant-authored JSON Schema for the response. Present on detail surfaces only."},"responseSchemaSource":{"type":"string","enum":["x402-output-example","openapi-responses","paid-run"],"description":"Where the response schema was declared or observed."},"responseExample":{"type":"object","description":"Sanitised merchant-authored example response. Harvested examples appear only after schema validation."},"responseExampleEvidence":{"type":"string","enum":["paid-run","challenge","docs"]},"responseExampleVerifiedAt":{"type":"string","format":"date-time"},"contractEvidence":{"type":"string","enum":["paid-run","fixture"],"description":"Evidence for the endpoint example, kept for compatibility: paid-run, or fixture for anything short of a paid run. Read exampleEvidence for the finer grade. Service-level operational health alone does not verify an endpoint."},"exampleEvidence":{"type":"string","enum":["paid-run","challenge","docs"],"description":"How requestExample was verified: paid-run (a bounded paid call returned the response shape), challenge (the example drew a payment challenge from a gateway shown to validate the request before pricing it; proves the request shape, not the response), or docs (from provider documentation, unverified)."},"exampleVerifiedAt":{"type":"string","format":"date","example":"2026-09-21","description":"For paid-run and challenge, the date that evidence was observed; for docs, the date the example was recorded from its source (it was never verified)."},"endpointCheck":{"type":"object","example":{"status":"unpaid-route-404","checkedAt":"2026-09-15"},"description":"Dated endpoint observation when a listed invocation is known to fail; separate from the service-level health badge."},"maxRequestBytes":{"type":"integer","minimum":1,"example":8000,"description":"Largest request body, in UTF-8 bytes, this endpoint accepts. The Router refuses a larger body before paying (BCK.ROUTER.0027), and service selection skips the endpoint for it. Absent when no limit is known."},"quote":{"description":"The merchant's live price for one call, on the rail and network the Router pays it on (a personal crypto delegation). Present while fresh (48 h); priceLabel then shows this price. It EXCLUDES the Router's routing fee, which the delegation cap is also charged: for the total a call reserves, or a price specific to your delegation, use POST /api/v1/router/quote.","allOf":[{"$ref":"#/components/schemas/CatalogEndpointQuoteDto"}]},"requestSchema":{"type":"object","example":{"type":"object","properties":{"body":{"type":"object","properties":{"q":{"type":"string"}},"required":["q"]}}},"description":"JSON Schema of the request, as the merchant declares it: `properties.query` describes the query parameters (sent as `search`), `properties.body` the JSON body. Merchant-authored and sanitised by Nevermined (a keyword allow-list, size bounds, no upstream host or URL in any string), NOT verified: read `requestSchemaSource`. Present on a service's detail only."},"requestSchemaSource":{"type":"string","enum":["orthogonal-input","x402-bazaar","x402-output-schema","openapi","docs"],"description":"Where requestSchema came from: orthogonal-input (the field list the gateway declares in its unpaid 400 input block or its 402 MPP challenge), x402-bazaar (the x402 v2 bazaar extension), x402-output-schema (an x402 v1 accepts[].outputSchema), openapi (the merchant's OpenAPI document), docs. Always merchant-declared, never Nevermined-verified."},"noParameters":{"type":"boolean","enum":[true],"description":"Present (true) when the endpoint takes no parameters: a bare request drew a payment challenge from a gateway shown to reject a request missing a required parameter. Present on a service's detail only."}},"required":["path"]},"CatalogRecipientDto":{"type":"object","properties":{"address":{"type":"string","example":"0x0000000000000000000000000000000000000001"},"network":{"type":"string","example":"eip155:8453"},"rail":{"type":"string","enum":["x402","mpp"]}},"required":["address"]},"CatalogProvenanceDto":{"type":"object","properties":{"sourceRefs":{"type":"array","description":"Where this listing came from. `mercator` is reserved (never emitted by this API yet).","items":{"type":"string","enum":["bazaar","mpp.dev","seller","curated","mercator"]}},"integration":{"type":"string","enum":["first-party","gateway"]}},"required":["sourceRefs","integration"]},"CatalogFeatureDto":{"type":"object","properties":{"title":{"type":"string","example":"Structured extraction"},"description":{"type":"string","example":"Returns clean JSON from any page"}},"required":["title"]},"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"}},"verificationStatus":{"type":"string","enum":["verified-by-canary","unverified","degraded"],"description":"Aggregate verification across the service endpoints."},"verifiedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the service most recently reached fully verified endpoint coverage."},"successRate":{"type":"number","nullable":true,"minimum":0,"maximum":100,"description":"Settled calls as a percentage of settled plus charged-not-delivered service calls. Null when no attributable outcome exists."},"lastSuccessfulCallAt":{"type":"string","format":"date-time","nullable":true,"description":"When the service last had a settled call through its opaque catalog slug."},"recipients":{"description":"Observed payment recipients.","type":"array","items":{"$ref":"#/components/schemas/CatalogRecipientDto"}},"provenance":{"$ref":"#/components/schemas/CatalogProvenanceDto"},"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 by editorial `sortWeight` descending, tier-neutral rankScore descending, then a time-seeded shuffle among ties."},"sortWeight":{"type":"number","example":100,"description":"Editorial weight, higher first. The default view uses tier + sortWeight + tier-neutral rankScore, then rotates exact ties. Use `tier` to band 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."},"official":{"type":"boolean","example":false,"description":"Official owner badge — true when the provider has verified ownership of this service. Derived from the claim; the claimer identity and proven domain are never published."},"rankScore":{"type":"number","nullable":true,"example":0.92,"description":"The Nevermined ranking value (#3473) — higher = recommended first; sort DESC. Treat as an OPAQUE quality metric, NOT a 0–1 percentage: it has no documented ceiling and MAY exceed 1. It is independent of the seller organization subscription tier. The measured inputs and the editorial Featured level that produce it are internal. null until first scored."},"readinessScore":{"type":"number","nullable":true,"example":84,"description":"Readiness score (0–100): how complete this listing is — metadata, pricing, documented endpoints. Present on the public catalog read (null until scored); absent on owner endpoints. Sort DESC with ?sortBy=readinessScore (unscored last). Advisory: it does NOT affect rankScore/qualityScore or the default order beyond breaking ties."},"readinessBand":{"type":"string","enum":["excellent","ready","almost-there","getting-started"],"nullable":true,"example":"ready","description":"Readiness band for `readinessScore`. Present on the public read (null until scored)."},"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. The monitor probes WITHOUT paying, so an `operational` status is withheld (null) while a listing has paid calls from several buyers and none settled in 30 days."},"healthConfidence":{"type":"number","nullable":true,"description":"Monitor-reported confidence (0–1): liveness is min(uptime-or-baseline liveness, confidence). Null means no cap was reported, so legacy liveness scoring is uncapped. Describes monitor evidence and may accompany degraded status when the latest probe succeeded after a recent incident."},"uptime7d":{"type":"number","nullable":true,"example":99.4,"description":"Uptime % over the trailing 7 days (conclusive probes); null when no coverage, or while the listing has paid calls from several buyers and none settled in 30 days."},"uptime30d":{"type":"number","nullable":true,"example":98.9,"description":"Uptime % over the trailing 30 days (conclusive probes); null when no coverage, or while the listing has paid calls from several buyers and none settled in 30 days."},"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; null while the listing has paid calls from several buyers and none settled in 30 days."},"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."},"validationStatus":{"type":"string","enum":["pending","running","valid","invalid","inconclusive"],"nullable":true,"example":"inconclusive"},"validationReasonCode":{"type":"string","nullable":true,"example":"ENDPOINT_4XX"},"validationMessage":{"type":"string","nullable":true,"description":"Sanitized validation feedback."},"validationRetryable":{"type":"boolean","nullable":true},"validationHttpStatus":{"type":"number","nullable":true,"example":402},"validationLatencyMs":{"type":"number","nullable":true,"example":340},"validationAttempts":{"type":"number","example":1},"validationStartedAt":{"type":"string","nullable":true,"format":"date-time"},"validationCompletedAt":{"type":"string","nullable":true,"format":"date-time"},"validationNextAttemptAt":{"type":"string","nullable":true,"format":"date-time"},"validationVersion":{"type":"string","nullable":true,"example":"catalog-validator/1"},"validationDetails":{"nullable":true,"allOf":[{"type":"object","additionalProperties":true}],"description":"Bounded, sanitized validator diagnostics. Never contains an upstream body."},"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"},"featuredLevel":{"type":"number","example":3,"description":"Editorial Nevermined Featured level 0..5 (0 = not featured). Internal; owner/admin only."},"qualityScore":{"type":"number","nullable":true,"example":0.92,"description":"Measured composite quality 0..1 (no Featured). Internal; owner/admin only — never published, so editorial promotion cannot be told from measured quality. null until first scored."}},"required":["id","slug","title","category","shortDescription","protocol","invokeUrl","logoUrl","endpoints","features","tags","isListed","tier","sortWeight","partner","featured","official","rankScore","lastSettledAt","distinctPayers30d","stale","settledPriceLabel","displayPriceLabel","displayPriceSource","createdAt","updatedAt","agentDid","orgId","submittedBy","moderationStatus","listedAt","pendingSince","unlistedReason","moderatorHold","validationStatus","validationReasonCode","validationMessage","validationRetryable","validationHttpStatus","validationLatencyMs","validationAttempts","validationStartedAt","validationCompletedAt","validationNextAttemptAt","validationVersion","validationDetails","freeFollowupPaths","paymentCount30d","activeDays30d","settledPriceAtomic","settledPriceAsset","settledPriceNetwork","signalsUpdatedAt","quotedPriceAtomic","quotedPriceAsset","quotedPriceNetwork","quotedPriceUpdatedAt","featuredLevel","qualityScore"]},"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/run","description":"Canonical HTTP(S) service target. A bare origin is a multi-endpoint gateway; a URL with a path is one payable endpoint. Surrounding whitespace, any userinfo credentials, a URL fragment, and a trailing origin slash are normalized away automatically; a query string is rejected."},"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"]},"CatalogDiscoveryDto":{"type":"object","properties":{"x402":{"type":"string","example":"https://svc.example/.well-known/x402"},"mcp":{"type":"string","example":"https://svc.example/mcp"},"a2a":{"type":"string","example":"https://svc.example/.well-known/agent-card.json"},"openapi":{"type":"string","example":"https://svc.example/openapi.json"},"llmsTxt":{"type":"string","example":"https://svc.example/llms.txt"},"apiReference":{"type":"string","example":"https://svc.example/docs"},"mppRegistry":{"type":"string","example":"https://registry.example/mpp.json"},"registryId":{"type":"string","description":"This service's id within `mppRegistry` (an id, not a URL)."}}},"IngestEndpointDto":{"type":"object","properties":{"path":{"type":"string","example":"/v1/tools/iban-check/call","description":"Host-free endpoint path (display), served verbatim to unauthenticated consumers and grouped by path segment. Must be a non-empty leading-slash path (never an absolute or protocol-relative URL — that would leak the merchant host), with no placeholder segment (`:id`, `{id}`, `*`, `<id>`)."},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE","HEAD","OPTIONS"],"example":"POST","description":"HTTP verb; an off-list value from the manifest is rejected (not persisted as a verb)."},"description":{"type":"string","example":"Validate an IBAN (ISO 13616) before a payout."},"priceLabel":{"type":"string","example":"$0.005"}},"required":["path"]},"QuotedPriceDto":{"type":"object","properties":{"atomic":{"type":"string","example":"10000","description":"Advertised 402 price in ATOMIC units, digits-only string (e.g. 10000 = 0.01 USDC)."},"asset":{"type":"string","example":"USDC","description":"Token symbol or 0x-address as the 402 declares."},"network":{"type":"string","example":"base","description":"Settlement network name (feeds the $ label)."}}},"CatalogValidationResultDto":{"type":"object","properties":{"listingId":{"type":"string","format":"uuid"},"validationVersion":{"type":"string","example":"api-v1"},"status":{"type":"string","enum":["valid","invalid","inconclusive"]},"reasonCode":{"type":"string","example":"X402_CHALLENGE_VALID"},"message":{"type":"string","example":"The endpoint returned a structurally valid x402 challenge."},"retryable":{"type":"boolean"},"httpStatus":{"type":"number","minimum":100,"maximum":599},"latencyMs":{"type":"number","minimum":0},"protocol":{"type":"string","enum":["x402","mpp","rest","a2a","other"]},"discovery":{"$ref":"#/components/schemas/CatalogDiscoveryDto"},"endpoints":{"type":"array","items":{"$ref":"#/components/schemas/IngestEndpointDto"}},"quotedPrice":{"$ref":"#/components/schemas/QuotedPriceDto"},"registered":{"type":"boolean","description":"True only when this run atomically promoted the pending row."},"registrationStatus":{"type":"string","enum":["registered","not-eligible","shadow","stale"]},"applied":{"type":"boolean","description":"False for migration shadow runs; shadow runs never mutate the listing."}},"required":["listingId","validationVersion","status","reasonCode","message","retryable","registered","registrationStatus","applied"]},"ClaimChallengeDto":{"type":"object","properties":{"domain":{"type":"string","example":"api.weatherwise.ai","description":"The confirmed public domain."},"recordHost":{"type":"string","example":"_nevermined-claim.api.weatherwise.ai","description":"The DNS TXT record host to create."},"recordValue":{"type":"string","example":"nevermined-site-verification=nvmclaim_abc123","description":"The exact DNS TXT record value (token prefixed with nevermined-site-verification=)."},"wellKnownUrl":{"type":"string","example":"https://api.weatherwise.ai/.well-known/nevermined-claim.txt","description":"The well-known URL whose body must equal the raw token (alternative to DNS)."},"token":{"type":"string","example":"nvmclaim_abc123","description":"The raw claim token (the well-known file body)."}},"required":["domain","recordHost","recordValue","wellKnownUrl","token"]},"VerifyClaimDto":{"type":"object","properties":{"method":{"type":"string","enum":["dns-txt","well-known"],"example":"dns-txt"},"domain":{"type":"string","example":"api.weatherwise.ai","description":"The public domain you control and are proving ownership of."},"orgId":{"type":"string","example":"org-123","description":"Organization that will own the claimed listing. Omit for Personal ownership. The server verifies active membership."}},"required":["method","domain"]},"ClaimListingSummaryDto":{"type":"object","properties":{"id":{"type":"string","example":"b0a1…","description":"The listing id (needed for challenge/verify/edit)."},"slug":{"type":"string","example":"webscrape-pro"},"title":{"type":"string","example":"WebScrape Pro"},"official":{"type":"boolean","description":"True when the listing's provider is verified — claimed, or published by an org or a registered agent. Drives the claim CTA vs the owner-edit path."}},"required":["id","slug","title","official"]},"RequestScoringDto":{"type":"object","properties":{"serviceUrl":{"type":"string","format":"uri"},"listingId":{"type":"string","format":"uuid"},"agentDid":{"type":"string"}},"required":["serviceUrl"]},"ScoringRequestAcceptedDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["deferred","queued","running","succeeded","failed"]},"createdAt":{"format":"date-time","type":"string"},"pollUrl":{"type":"string"}},"required":["id","status","createdAt","pollUrl"]},"ScoringSummaryDto":{"type":"object","properties":{"provisional":{"type":"boolean"},"score":{"type":"number"},"rawScore":{"type":"number"},"band":{"type":"string"},"appliedCap":{"type":"string","nullable":true},"rubricVersion":{"type":"string"},"analyzedAt":{"format":"date-time","type":"string"},"stale":{"type":"boolean","description":"True once the score is older than the readiness freshness TTL"},"topAction":{"type":"object","nullable":true}},"required":["provisional","score","rawScore","band","appliedCap","rubricVersion","analyzedAt","stale"]},"ScoringStatusDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["deferred","queued","running","succeeded","failed"]},"trigger":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"queuedAt":{"format":"date-time","type":"string"},"startedAt":{"format":"date-time","type":"string","nullable":true},"finishedAt":{"format":"date-time","type":"string","nullable":true},"attemptCount":{"type":"number"},"failureCode":{"type":"string","nullable":true},"failureMessage":{"type":"string","nullable":true},"summary":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/ScoringSummaryDto"}]},"resultUrl":{"type":"string","nullable":true}},"required":["id","serviceUrl","status","trigger","createdAt","queuedAt","startedAt","finishedAt","attemptCount","failureCode","failureMessage","summary","resultUrl"]},"ScoringHistoryPageDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ScoringStatusDto"}},"nextCursor":{"type":"string","nullable":true}},"required":["items","nextCursor"]},"ScoringResultDto":{"type":"object","properties":{"score":{"type":"number"},"rawScore":{"type":"number"},"band":{"type":"string"},"appliedCaps":{"type":"array","items":{"type":"string"}},"dimensions":{"type":"array","items":{"type":"object"}},"findings":{"type":"array","items":{"type":"object"}},"actions":{"type":"array","items":{"type":"object"}},"recommendations":{"type":"array","items":{"type":"object"}},"rubricVersion":{"type":"string"},"analyzedAt":{"format":"date-time","type":"string"}},"required":["score","rawScore","band","appliedCaps","dimensions","findings","actions","recommendations","rubricVersion","analyzedAt"]},"ScoringLatestItemDto":{"type":"object","properties":{"provisional":{"type":"boolean"},"score":{"type":"number"},"rawScore":{"type":"number"},"band":{"type":"string"},"appliedCap":{"type":"string","nullable":true},"rubricVersion":{"type":"string"},"analyzedAt":{"format":"date-time","type":"string"},"stale":{"type":"boolean","description":"True once the score is older than the readiness freshness TTL"},"topAction":{"type":"object","nullable":true},"listingId":{"type":"string","format":"uuid"},"previousRubricVersion":{"type":"string","nullable":true,"description":"Rubric version of the listing's previous full score, or null if there is none"}},"required":["provisional","score","rawScore","band","appliedCap","rubricVersion","analyzedAt","stale","listingId","previousRubricVersion"]},"ScoringLatestPageDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ScoringLatestItemDto"}}},"required":["items"]},"PublicReadinessDto":{"type":"object","properties":{"slug":{"type":"string"},"score":{"type":"number","minimum":0,"maximum":100},"band":{"type":"string","enum":["excellent","ready","almost-there","getting-started"]},"analyzedAt":{"type":"string","format":"date-time"},"rubricVersion":{"type":"string"},"catalogUrl":{"type":"string","format":"uri"}},"required":["slug","score","band","analyzedAt","rubricVersion","catalogUrl"]},"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); also returned by `/router/select` itself when a payment already exists for this requestId (a retry that can no longer re-select the paid service), carrying the original paymentId; `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). `BCK.ROUTER.0018` the fee-inclusive price exceeds maxTotalCents; params gives requiredTotalMicros, requiredTotalCents, merchantCents, feeCents and maxTotalCents (402, no charge). `BCK.ROUTER.0019` a cataloged service returned a non-retryable status — a client error (4xx), or a rare 3xx the Router does not follow (a 402 re-challenge and a 429 are NOT this code): the Router withholds the upstream body (it can name the merchant host) and returns this typed body with the original status preserved — build a valid request from the service’s Catalog detail; not retryable. `BCK.ROUTER.0020` a cataloged service returned a server error (5xx) or rate-limited (429): same withholding, original status preserved — an upstream/transient condition, retryable (back off); also an unpaid request the service did not answer at all (timeout or connection failure, 502). `BCK.ROUTER.0021` the payment credential would overwrite a header you asked the Router to forward — the rail this service advertised carries its credential in that header (on the MPP rails, `Authorization`, which is also where your own merchant auth goes): name the header the service documents for the credential via `credentialHeader` / `X-Router-Credential-Header`; nothing was minted and no money moved (400, not retryable). `BCK.ROUTER.0022` server-side service selection is not wired on this deployment — a configuration fault, nothing was ranked or charged (500, retryable). `BCK.ROUTER.0023` on a `/router/select` autoPay the charge outcome for this requestId is indeterminate — either the downstream call did not complete cleanly after the payment was created, or the Router could not determine whether an earlier attempt on this requestId charged (including when there was none): reconcile via `GET /api/v1/router/payments` and reuse the SAME requestId to retry safely; params carries the paymentId when one is known (502, not retryable). `BCK.ROUTER.0024` the Router JSON request body exceeds 5 MiB (413). `BCK.ROUTER.0025` the upstream reply was too large to deliver after a paid request; the payment may have gone through — reconcile via `GET /api/v1/router/payments` and do NOT retry with a fresh requestId (502, indeterminate). `BCK.ROUTER.0026` the streaming surfaces (`/router/svc/:slug`, `/router/proxy`) cannot forward this request body, refused before anything is paid: only JSON or a URL-encoded form is forwarded (resend in one of those), and no body at all on GET/HEAD (send none, or use POST/PUT if the service takes one); params names the refused content type, null when absent (415, not retryable). `BCK.ROUTER.0027` a slug-routed request body is larger than the catalog endpoint accepts (its `maxRequestBytes` on the catalog service detail), refused before the service is contacted or anything is paid; params gives bodyBytes and maxRequestBytes — shrink the body or pick a service that takes it (413, not retryable). `BCK.ROUTER.0028` `/router/quote` could not price the call because a read it depends on failed; nothing was signed or charged (503, retryable). `BCK.ROUTER.0029` quoteId is unknown or belongs to another account (404, no charge). `BCK.ROUTER.0030` no retained result for that paymentId under your account — expired (results are kept 24 hours), never retained, or not your payment; deliberately one answer (404). `BCK.ROUTER.0031` the exact service named by filters.require cannot be selected (409, no charge). `BCK.ROUTER.0032` quoteId expired before payment began (410, no charge). `BCK.ROUTER.0033` quoteId does not match this request, delegation, rail or exact total (409, no charge). `BCK.ROUTER.0034` a paid request got no response from the service (timeout or connection failure); the payment may have gone through — params carries the paymentId: reconcile via `GET /api/v1/router/payments/{paymentId}` and do NOT retry with a fresh requestId (502, indeterminate). `BCK.ROUTER.0035` the service challenge asks for no payment (a zero amount, typically an auth-only wallet sign-in challenge); the request is not malformed and nothing was signed or charged (422, not retryable). `BCK.ROUTER.0036` every catalog endpoint a slug-routed call reaches answers after the Router abandons a paid call (120 s), so paying would charge and deliver nothing; refused before the service is contacted or anything is paid; params.source is declared (permanent) or observed (lifts at params.liftsAt) — pick another endpoint or service (422, not retryable). `BCK.ROUTER.0040` the Router refused an inconsistent read or write of its MPP session payment-channel state — a server-side defect, refused before the credential reached the service, so nothing moved (500, not retryable). `BCK.ROUTER.0041` `POST /router/payments` met a service paid only over an MPP session (a payment channel), which only the Router-fetched routes (`/router/route`, `/router/svc`, `/router/proxy`) can pay; nothing was signed or charged (400, not retryable). `BCK.ROUTER.0042` the MPP session payment channel with this service is closing (its deposit reached its ceiling, or the service refused the channel, a top-up, or the payment after a top-up), so nothing can be signed on it until it closes; no payment was signed, reserved or charged (a top-up the Router sent only moves the wallet’s own funds into its channel) — retry later with the same requestId, and the next call after the close opens a new channel (409, retryable). `BCK.ROUTER.0043` the MPP session payment channel with this service is busy — another payment on it held it too long, the wallet's signer or balance read did not answer in time, or a top-up of the channel was in flight or the service could not be reached to take one (`params.stage`); nothing was signed, reserved or charged — retry after a few seconds (503, retryable). `BCK.ROUTER.0044` a session’s routing fee is collected later in one transfer, never per call, and the Router cannot collect it for this MPP session payment: `params.cause` is `org-wallet` (an organization wallet funds it — pay from a delegation funded by your own wallet) or `network` (this deployment does not collect session fees on that network); nothing was signed, reserved or charged (422, not retryable). `BCK.ARD.0001` `/router/select` was given an unsupported catalog filter term (400). The spend routes, and `GET /router/delegations/:id`, can also return `BCK.DELEGATION.0002` (no such delegation for this caller, 404); that read additionally returns `BCK.DELEGATION.0009` when `:id` is not a v4 uuid (400). The spend routes can also return `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/*` routes, 403), `BCK.OAUTH.0034` (a `delegationId` was supplied to one of them, where it is derived from the grant instead, 400), `BCK.OAUTH.0039` (a credits-only commerce grant must use subscription credit routes or reconnect with a stablecoin cap, 403), `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); a `slug` that names no listed catalog service returns `BCK.CATALOG.0001` (404); 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"},"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"]},"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"},"deliveryStatus":{"type":"string","description":"Buyer-visible outcome: delivered when the request settled; charged_not_delivered when it failed and the merchant charge was observed; charged_unconfirmed when the charge was observed but delivery is unconfirmed; not_charged when reconciliation proved the merchant did not charge; not_delivered when the merchant answered the paid call with an error (x402 and MPP-tempo charge), so nothing was delivered, and no merchant charge has been observed yet: the merchant can still redeem the payment until its authorization expires, so the amount stays reserved against the delegation until reconciliation decides, after that expiry, whether it becomes not_charged or a charged_ value; pending when the charge outcome is unknown. On SPT and card rails, pending is not proof of no charge.","enum":["delivered","charged_not_delivered","charged_unconfirmed","not_charged","not_delivered","pending"],"example":"charged_not_delivered"},"fundingSource":{"type":"string","description":"What paid for this payment: `delegation` (your delegation cap) or `subscription` (your Nevermined Subscription credits; Nevermined paid the merchant, so `delegationId` is null).","enum":["delegation","subscription"],"example":"delegation"},"creditsCharged":{"type":"number","description":"Credits a subscription-funded payment cost (its tariff). Null on a delegation payment.","nullable":true,"example":null},"creditsStatus":{"type":"string","description":"Where a subscription-funded payment’s credits stand: `Committed` (delivered), `Reserved` (undelivered and marked for refund, or still being decided) or `Refunded`. Null on a delegation payment.","enum":["Reserved","Committed","Refunded"],"nullable":true,"example":null},"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","description":"The delegation this payment was reserved against. Null on a payment funded by a Nevermined Subscription, which spends subscription credits and no delegation.","nullable":true},"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, where that same row breaks it out as `feeCents` / `feeAtomic` / `feeBps`, with `feeReleased` marking a fee already refunded to the cap.","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"},"paymentId":{"type":"string","description":"Alias of `id`, named explicitly for requestId reconciliation clients.","example":"b1f9c2e4-8a3d-4f27-9c6b-5d2e17a04f8b"},"chargedMicros":{"type":"string","description":"Exact amount this payment still contributes to the delegation cap, in micros (1/10,000 of a cent). A merchant or fee share that was proven uncollected and released is excluded. `null` on legacy rows that predate exact micro-reserve columns, because their amount unit is rail-dependent and cannot be reconstructed safely.","nullable":true,"example":"1020000"},"resultUrl":{"type":"string","description":"Relative URL of the retained paid result. It may answer Pending while the call is running, or 404 after retention expires, for a mode-A payment, for an unknown payment, or for a payment owned by another caller. A 404 is not delivery evidence; use `deliveryStatus`.","example":"/api/v1/router/payments/b1f9c2e4-8a3d-4f27-9c6b-5d2e17a04f8b/result"}},"required":["id","createdAt","status","deliveryStatus","fundingSource","creditsCharged","creditsStatus","protocol","network","amount","merchantAddress","delegationId","buyer","paymentId","chargedMicros","resultUrl"]},"RouterPaymentLookupDto":{"type":"object","properties":{"presence":{"type":"string","description":"`present` when the caller owns the matching payment; `absent` when the primary ledger has no match.","enum":["present","absent"],"example":"present"},"payments":{"description":"Exactly one payment when presence is `present`; empty when it is `absent`. Database read failures are non-2xx responses, never `absent`.","type":"array","items":{"$ref":"#/components/schemas/RouterPaymentRecordDto"}}},"required":["presence","payments"]},"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"}}]}},"maxTotalCents":{"type":"number","description":"Per-call whole-cent cap ceiling, including any collectable Router fee and sub-cent rounding. A larger quote is refused before anything is signed and before a payment record or delegation reserve is written.","example":5,"minimum":0,"maximum":9007199254740991},"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 verbatim and looked up byte for byte. An empty string is the same as omitting it (no id)."}},"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 whole-cent total debited from the delegation is `approxCents + fee.cents` (also reported directly as `fee.capChargedCents`; the exact sub-cent debit is `fee.capChargedMicros`). 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), `session` for an MPP-tempo payment channel (a cumulative voucher; its money moves when the service settles or closes the channel, so the payment carries no transaction hash of its own), `spt` for MPP-stripe (a Shared Payment Token). Omitted (defaults to `exact`) on the x402 path.","enum":["exact","charge","session","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":200},"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":"20"},"cents":{"type":"string","description":"Cents this fee added to the delegation-cap reserve, i.e. `capChargedCents - settlement.approxCents`.","example":"0"},"capChargedCents":{"type":"string","description":"The delegation-cap debit for this payment (merchant leg + routing fee), rounded UP to a whole cent. The cap itself accrues at sub-cent resolution, so the exact debit is `capChargedMicros`; this figure is the per-call price guard that `maxTotalCents` is compared against.","example":"1"},"capChargedMicros":{"type":"string","description":"The exact delegation-cap debit for this payment (merchant leg + routing fee), in micros — millionths of the currency unit, i.e. 1/10,000 of a cent. It is a ceiling of the true price at that resolution, never below it. It is the debit AT MINT: if the routing fee or the merchant leg is later found uncollected, that part is given back to the cap while this figure stays as minted.","example":"1020"}},"required":["bps","amount","cents","capChargedCents","capChargedMicros"]},"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"]},"ProxyRequestDto":{"type":"object","properties":{"delegationId":{"type":"string","description":"The caller's erc4337 delegation to spend against (as in POST /payments)."},"quoteId":{"type":"string","description":"Opaque id returned by POST /api/v1/router/quote for this exact call. While it is unexpired, the Router pays the sealed protocol challenge and fee-inclusive figure instead of accepting a changed merchant quote. The target, method, headers, body, credential header and delegation must match the quoted request. maxTotalCents remains an independent spend ceiling.","example":"q1.opaque-authenticated-quote-token"},"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: `//`, `..`, a backslash and an embedded absolute URL are rejected (400). An `@` is allowed (e.g. an `/inbox/foo@bar.com` route) — it stays in the path and the composed origin is re-asserted against the resolved host. Ignored when `url` is used.","example":"scrape"},"search":{"type":"string","description":"Query string for a slug-routed request, without the leading ?. It is attached to the resolved merchant URL without changing its host. Use this instead of embedding ? in path. With a raw url, include the query in url; sending search with url is refused.","example":"flight_iata=AA217&limit=1","maxLength":2048},"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."},"credentialHeader":{"type":"string","description":"Header the Router should carry the minted payment credential in on the paid hop. Send this only when the service needs its own auth AND a payment: the MPP rails carry their credential in `Authorization`, which is also where your merchant auth goes, and rather than silently replacing yours the Router refuses the call with BCK.ROUTER.0021. Naming the header the service documents for its credential (a separate `Payment` header is the common one) leaves your `Authorization` untouched. It is honoured on every rail, so do not set it by default: putting the credential somewhere the service does not read makes the paid hop fail.","example":"Payment","maxLength":64},"maxTotalCents":{"type":"number","description":"Maximum whole cents this single call may reserve against the delegation cap, including the Router buyer fee and sub-cent rounding. A larger 402 quote is refused before anything is signed and before a payment record or cap decrement. 0 refuses positive quotes. Reuse the same requestId on retries.","example":5,"minimum":0,"maximum":9007199254740991},"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"},"delegationId":{"type":"string","example":"a1b2c3d4-e5f6-4a90-8bcd-ef1234567890","description":"The delegation whose spending cap this payment was reserved against. On the commerce route it is derived from the OAuth grant, so read it here rather than assuming which delegation paid — e.g. to fetch the remaining budget with `GET /delegation/{delegationId}`."},"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.capChargedMicros` is exactly what the delegation cap was debited (`fee.capChargedCents` is that debit rounded up to a whole cent).","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"},"resultUrl":{"type":"string","description":"Where this paid result stays readable by you for 24 hours (`GET` it with the same API key), in case the response is lost on the way back to you. It is written as the call ends, so a read in the same instant may still answer `202`. Relative to the API host.","example":"/api/v1/router/payments/b1f9c2e4-8a3d-4f27-9c6b-5d2e17a04f8b/result"}},"required":["paymentId","delegationId","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 for JSON responses, text for text responses, or base64 for binary responses when bodyEncoding is base64). 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"}},"bodyEncoding":{"type":"string","description":"How body is represented: parsed JSON, UTF-8 text, or lossless base64. Absent whenever body is withheld for a cataloged call.","enum":["json","text","base64"]},"contentType":{"type":"string","description":"Normalized upstream media type without parameters. Absent whenever the response body is withheld.","nullable":true,"example":"application/json"},"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"]},"RoutePendingDto":{"type":"object","properties":{"paymentId":{"type":"string","example":"b1f9c2e4-8a3d-4f27-9c6b-5d2e17a04f8b"},"resultUrl":{"type":"string","description":"Read the result here with the same API key. Relative to the API host.","example":"/api/v1/router/payments/b1f9c2e4-8a3d-4f27-9c6b-5d2e17a04f8b/result"},"status":{"type":"string","enum":["Pending"],"example":"Pending"}},"required":["paymentId","resultUrl","status"]},"QuoteRequestDto":{"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: `//`, `..`, a backslash and an embedded absolute URL are rejected (400). An `@` is allowed (e.g. an `/inbox/foo@bar.com` route) — it stays in the path and the composed origin is re-asserted against the resolved host. Ignored when `url` is used.","example":"scrape"},"search":{"type":"string","description":"Query string for a slug-routed request, without the leading ?. It is attached to the resolved merchant URL without changing its host. Use this instead of embedding ? in path. With a raw url, include the query in url; sending search with url is refused.","example":"flight_iata=AA217&limit=1","maxLength":2048},"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."},"credentialHeader":{"type":"string","description":"Header the Router should carry the minted payment credential in on the paid hop. Send this only when the service needs its own auth AND a payment: the MPP rails carry their credential in `Authorization`, which is also where your merchant auth goes, and rather than silently replacing yours the Router refuses the call with BCK.ROUTER.0021. Naming the header the service documents for its credential (a separate `Payment` header is the common one) leaves your `Authorization` untouched. It is honoured on every rail, so do not set it by default: putting the credential somewhere the service does not read makes the paid hop fail.","example":"Payment","maxLength":64},"delegationId":{"type":"string","description":"The delegation you would pay with. Optional. When given, the quote prices the options that delegation would select: an organization-wallet delegation pays only in its own currency, a card delegation pays over the MPP-stripe rail, and a recipient allowlist refuses a pay-to address it would refuse. Without it, the quote prices what a personal crypto (erc4337) delegation would select. `optionSet` in the response says which was used. Either way the quote checks neither the remaining cap nor the wallet balance.","example":"5e7481c3-e972-45bd-bdc5-a0b99c4de4a1"}}},"QuoteResultDto":{"type":"object","properties":{"quoteId":{"type":"string","description":"Opaque id that binds this payment-required quote to the exact request, delegation, selected rail and fee-inclusive amount. Pass it as quoteId on /route before expiresAt.","example":"q1.opaque-authenticated-quote-token"},"expiresAt":{"type":"string","description":"ISO-8601 expiry of quoteId. Present with quoteId; after this instant the call must be quoted again.","example":"2026-09-29T12:01:00.000Z"},"paymentRequired":{"type":"boolean","description":"Whether the upstream asked for payment (answered 402). `false` means the call is free, or the upstream answered with an error before any payment challenge: read `upstreamStatus`, and expect every priced field below to be absent.","example":true},"upstreamStatus":{"type":"number","description":"The status the upstream answered the unpaid probe with — 402 when `paymentRequired` is true. The upstream body and headers are never returned.","example":402},"optionSet":{"type":"string","description":"Which set of payment options was priced. `delegation`: the options the supplied `delegationId` would select. `deployment`: no delegation was supplied, so the options a personal crypto (erc4337) delegation would select on this deployment. Present when `paymentRequired` is true.","enum":["delegation","deployment"],"example":"deployment"},"delegationId":{"type":"string","description":"The delegation whose options were priced, or null for the `deployment` option set. Present when `paymentRequired` is true.","nullable":true,"example":null},"protocol":{"type":"string","description":"The payment protocol the Router would pay with — the same auto-detection as `/route` (MPP first, then x402). Present when `paymentRequired` is true.","enum":["x402","mpp"],"example":"x402"},"x402Version":{"type":"number","description":"The x402 version that would be used, on the x402 rail.","example":2},"settlement":{"description":"What the payment would pay the merchant: the rail (`scheme`), `network`, `asset`, the merchant leg in atomic units (`amount`) and in cents (`approxCents`). The same descriptor `/route` returns as `payment.settlement`. Present when `paymentRequired` is true.","allOf":[{"$ref":"#/components/schemas/SettlementDescriptorDto"}]},"fee":{"description":"The Router fee and the fee-inclusive total the payment would reserve against the delegation cap — `capChargedMicros` exactly, `capChargedCents` rounded up to a whole cent, which is the figure `maxTotalCents` is compared against. The same object `/route` returns as `payment.fee`. Present when `paymentRequired` is true.","allOf":[{"$ref":"#/components/schemas/RouterFeeDto"}]}},"required":["paymentRequired","upstreamStatus"]},"CommerceQuoteRequestDto":{"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: `//`, `..`, a backslash and an embedded absolute URL are rejected (400). An `@` is allowed (e.g. an `/inbox/foo@bar.com` route) — it stays in the path and the composed origin is re-asserted against the resolved host. Ignored when `url` is used.","example":"scrape"},"search":{"type":"string","description":"Query string for a slug-routed request, without the leading ?. It is attached to the resolved merchant URL without changing its host. Use this instead of embedding ? in path. With a raw url, include the query in url; sending search with url is refused.","example":"flight_iata=AA217&limit=1","maxLength":2048},"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."},"credentialHeader":{"type":"string","description":"Header the Router should carry the minted payment credential in on the paid hop. Send this only when the service needs its own auth AND a payment: the MPP rails carry their credential in `Authorization`, which is also where your merchant auth goes, and rather than silently replacing yours the Router refuses the call with BCK.ROUTER.0021. Naming the header the service documents for its credential (a separate `Payment` header is the common one) leaves your `Authorization` untouched. It is honoured on every rail, so do not set it by default: putting the credential somewhere the service does not read makes the paid hop fail.","example":"Payment","maxLength":64},"delegationId":{"type":"string","description":"Must NOT be sent. The quote prices the delegation your grant is pinned to — the one the user consented to and capped. Supplying one is refused rather than ignored; use POST /api/v1/router/quote with a plain API key to price a delegation of your choice."}}},"SelectFiltersDto":{"type":"object","properties":{"require":{"type":"string","description":"Require this exact opaque catalog slug. The Router either selects it or fails closed; it never substitutes another service."},"prefer":{"type":"string","description":"Prefer this exact opaque catalog slug when it is a payable match; otherwise fall back to the normal ranking."},"exclude":{"type":"string","description":"Exclude this exact opaque catalog slug from the result."},"category":{"type":"string","description":"Narrow to a catalog category/tag."},"protocol":{"type":"string","description":"Narrow to a payment protocol (only x402 and mpp are payable)."},"network":{"type":"string","description":"Narrow to a settlement network."},"maxPriceLabel":{"type":"string","description":"Upper price bound as a label (e.g. \"$0.05\"); best-effort."}}},"SelectRequestDto":{"type":"object","properties":{"intent":{"type":"string","description":"Plain-language description of the service you need.","example":"translate English to German","maxLength":2048},"filters":{"description":"Optional structured narrowing.","allOf":[{"$ref":"#/components/schemas/SelectFiltersDto"}]},"limit":{"type":"number","description":"Shortlist size to return (1–20).","minimum":1,"maximum":20,"default":5},"autoPay":{"type":"boolean","description":"When true, the Router also pays and relays the winner (mode B). Requires `requestId` and `delegationId`. Default false → return the pick only, no charge.","default":false},"requestId":{"type":"string","description":"Idempotency key. Required when `autoPay` is true; forwarded to mode B verbatim."},"delegationId":{"type":"string","description":"Delegation to charge. Required when `autoPay` is true; forwarded to mode B."},"method":{"type":"string","description":"HTTP method for the paid call."},"path":{"type":"string","description":"Subpath appended to the winner when paying."},"search":{"type":"string","description":"Query string (no leading ?) for the paid call."},"headers":{"type":"object","description":"Extra headers for the paid call."},"credentialHeader":{"type":"string","description":"Header the Router should carry the minted payment credential in on the paid hop (mode B). Forwarded verbatim to route()/commerceRoute() — send it only when the winning service needs its own auth AND a payment credential (see POST /router/route). Ignored when autoPay is false.","example":"Payment","maxLength":64},"body":{"type":"object","description":"Request body to forward on the paid call."},"maxTotalCents":{"type":"number","description":"Refuse a paid quote whose fee-inclusive price exceeds this, before purchase."}},"required":["intent","autoPay"]},"SelectChosenDto":{"type":"object","properties":{"slug":{"type":"string","description":"The chosen service slug."},"title":{"type":"string","description":"The service title."},"priceLabel":{"type":"string","description":"The display price label.","nullable":true},"network":{"type":"string","description":"The settlement network.","nullable":true},"protocol":{"type":"string","description":"The payment protocol (x402 or mpp)."},"invokeUrl":{"type":"string","description":"The OPAQUE Router invoke alias for this service — never the upstream host."}},"required":["slug","title","priceLabel","network","protocol","invokeUrl"]},"SelectShortlistItemDto":{"type":"object","properties":{"slug":{"type":"string","description":"The candidate service slug."},"semanticScore":{"type":"number","description":"Absolute cosine-similarity score, present only for semantic-ranked items.","minimum":0,"maximum":100},"lexicalScore":{"type":"number","description":"Per-result-set normalized full-text rank, present only for lexical-ranked items.","minimum":0,"maximum":100},"rankingSource":{"type":"string","description":"The score scale used by this item.","enum":["semantic","lexical"]},"matchReason":{"type":"string","description":"Closed explanation of why this item matched the requested intent.","enum":["semantic_similarity","lexical_match","required_service"]},"gateReason":{"type":"string","description":"Closed payability-gate outcome for this candidate.","enum":["payable","unlisted","unpayable","non_payable_protocol","unhealthy","moderation_hold","request_too_large"]},"rankScore":{"type":"number","description":"Quality score, higher is better and independent of seller subscription tier (null until first scored). Blended with the item score to order the shortlist — an input to the pick, not just a tiebreak.","nullable":true},"healthy":{"type":"boolean","description":"Whether the service is healthy (passed the health gate)."},"priceLabel":{"type":"string","description":"The display price label.","nullable":true}},"required":["slug","rankingSource","matchReason","gateReason","rankScore","healthy","priceLabel"]},"SelectResultDto":{"type":"object","properties":{"chosen":{"description":"The chosen service.","allOf":[{"$ref":"#/components/schemas/SelectChosenDto"}]},"shortlist":{"description":"The top payable candidates, in pick order: scale-specific relevance blended with quality (`rankScore`) within each ranking scale, with semantic matches first. Read the order, not the raw numbers.","type":"array","items":{"$ref":"#/components/schemas/SelectShortlistItemDto"}},"result":{"description":"The mode-B result + payment receipt — present only when autoPay was true.","allOf":[{"$ref":"#/components/schemas/RouteResultDto"}]}},"required":["chosen","shortlist"]},"CommerceSelectRequestDto":{"type":"object","properties":{"intent":{"type":"string","description":"Plain-language description of the service you need.","example":"translate English to German","maxLength":2048},"filters":{"description":"Optional structured narrowing.","allOf":[{"$ref":"#/components/schemas/SelectFiltersDto"}]},"limit":{"type":"number","description":"Shortlist size to return (1–20).","minimum":1,"maximum":20,"default":5},"autoPay":{"type":"boolean","description":"When true, the Router also pays and relays the winner (mode B). Requires `requestId` and `delegationId`. Default false → return the pick only, no charge.","default":false},"requestId":{"type":"string","description":"Idempotency key. Required when `autoPay` is true; forwarded to mode B verbatim."},"method":{"type":"string","description":"HTTP method for the paid call."},"path":{"type":"string","description":"Subpath appended to the winner when paying."},"search":{"type":"string","description":"Query string (no leading ?) for the paid call."},"headers":{"type":"object","description":"Extra headers for the paid call."},"credentialHeader":{"type":"string","description":"Header the Router should carry the minted payment credential in on the paid hop (mode B). Forwarded verbatim to route()/commerceRoute() — send it only when the winning service needs its own auth AND a payment credential (see POST /router/route). Ignored when autoPay is false.","example":"Payment","maxLength":64},"body":{"type":"object","description":"Request body to forward on the paid call."},"maxTotalCents":{"type":"number","description":"Refuse a paid quote whose fee-inclusive price exceeds this, before purchase."},"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/select with a plain API key to choose a delegation per call."}},"required":["intent","autoPay"]},"CommerceRouteRequestDto":{"type":"object","properties":{"quoteId":{"type":"string","description":"Opaque id returned by POST /api/v1/router/quote for this exact call. While it is unexpired, the Router pays the sealed protocol challenge and fee-inclusive figure instead of accepting a changed merchant quote. The target, method, headers, body, credential header and delegation must match the quoted request. maxTotalCents remains an independent spend ceiling.","example":"q1.opaque-authenticated-quote-token"},"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: `//`, `..`, a backslash and an embedded absolute URL are rejected (400). An `@` is allowed (e.g. an `/inbox/foo@bar.com` route) — it stays in the path and the composed origin is re-asserted against the resolved host. Ignored when `url` is used.","example":"scrape"},"search":{"type":"string","description":"Query string for a slug-routed request, without the leading ?. It is attached to the resolved merchant URL without changing its host. Use this instead of embedding ? in path. With a raw url, include the query in url; sending search with url is refused.","example":"flight_iata=AA217&limit=1","maxLength":2048},"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."},"credentialHeader":{"type":"string","description":"Header the Router should carry the minted payment credential in on the paid hop. Send this only when the service needs its own auth AND a payment: the MPP rails carry their credential in `Authorization`, which is also where your merchant auth goes, and rather than silently replacing yours the Router refuses the call with BCK.ROUTER.0021. Naming the header the service documents for its credential (a separate `Payment` header is the common one) leaves your `Authorization` untouched. It is honoured on every rail, so do not set it by default: putting the credential somewhere the service does not read makes the paid hop fail.","example":"Payment","maxLength":64},"maxTotalCents":{"type":"number","description":"Maximum whole cents this single call may reserve against the delegation cap, including the Router buyer fee and sub-cent rounding. A larger 402 quote is refused before anything is signed and before a payment record or cap decrement. 0 refuses positive quotes. Reuse the same requestId on retries.","example":5,"minimum":0,"maximum":9007199254740991},"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"]},"RouterPaymentResultPaymentDto":{"type":"object","properties":{"paymentId":{"type":"string","example":"b1f9c2e4-8a3d-4f27-9c6b-5d2e17a04f8b"},"status":{"type":"string","enum":["Issued","Settled","Failed"],"example":"Settled"},"txHash":{"type":"string","description":"The settlement reference, once the merchant reported one.","nullable":true,"example":"0xfc8af37baae588b5ee4a5e9212532b3d46702ac009b64c17e8ff810fd90ac493"}},"required":["paymentId","status","txHash"]},"RouterPaymentResultDto":{"type":"object","properties":{"paymentId":{"type":"string","example":"b1f9c2e4-8a3d-4f27-9c6b-5d2e17a04f8b"},"state":{"type":"string","enum":["Pending","Ready","Failed"],"example":"Ready"},"resultUrl":{"type":"string","description":"This resource, relative to the API host.","example":"/api/v1/router/payments/b1f9c2e4-8a3d-4f27-9c6b-5d2e17a04f8b/result"},"expiresAt":{"type":"string","description":"When the result is deleted. Until then only you can read it.","example":"2026-09-26T10:12:00.000Z"},"status":{"type":"number","description":"The upstream HTTP status of the paid call. `Ready` only.","nullable":true,"example":200},"body":{"description":"The relayed response body, exactly as the original call would have returned it — so for a cataloged (slug) service a non-2xx body is withheld (null) here too. Its form is named by `bodyEncoding` (null when there is none). `Ready` only.","nullable":true,"oneOf":[{"type":"object"},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"boolean"}],"example":{"ok":true,"data":"the paid resource"}},"bodyEncoding":{"type":"string","description":"`json` — `body` is the parsed JSON value; `text` — a UTF-8 string; `base64` — binary, base64-encoded (read `contentType`). Null when there is no body.","enum":["json","text","base64"],"nullable":true,"example":"json"},"contentType":{"type":"string","description":"The upstream `content-type`, when it was a streamed call (`/router/proxy`, `/router/svc`).","nullable":true,"example":"application/json"},"headers":{"type":"object","description":"The response headers the streamed call would have relayed (already filtered as the live relay filters them). Empty for a `/router/route` result, whose headers are never relayed.","additionalProperties":{"type":"string"},"example":{"content-type":"application/json"}},"failureReason":{"type":"string","description":"Why a `Failed` result has no response.","nullable":true,"example":"paid hop failed (upstream error)"},"payment":{"$ref":"#/components/schemas/RouterPaymentResultPaymentDto"}},"required":["paymentId","state","resultUrl","expiresAt","payment"]},"RouterSpendByDeliveryStatusDto":{"type":"object","properties":{"delivered":{"type":"string","description":"Delivered (request settled).","example":"1020"},"charged_not_delivered":{"type":"string","description":"Failed, and the merchant charge was observed on-chain.","example":"1020"},"charged_unconfirmed":{"type":"string","description":"Charge observed; delivery unconfirmed.","example":"0"},"not_charged":{"type":"string","description":"Reconciliation proved no merchant charge; any routing fee not released is still counted.","example":"0"},"not_delivered":{"type":"string","description":"The merchant answered the paid call with an error, so nothing was delivered, and no charge has been observed yet: held until reconciliation decides, once the payment authorization has expired, whether the merchant charged.","example":"0"},"pending":{"type":"string","description":"Charge outcome not decided yet (in flight, or failed and awaiting reconciliation).","example":"0"}},"required":["delivered","charged_not_delivered","charged_unconfirmed","not_charged","not_delivered","pending"]},"RouterDelegationCapDto":{"type":"object","properties":{"id":{"type":"string","description":"The delegation id (echoed).","example":"28f2b44a-b643-4cb0-844f-bc454dcd3fad"},"capMicros":{"type":"string","description":"The delegation spending cap in micros — millionths of the currency unit, i.e. 1/10,000 of a cent.","example":"100000"},"spentMicros":{"type":"string","description":"Spend recorded against the cap so far, in micros (1/10,000 of a cent). Read at sub-cent resolution. Compare against capMicros for remaining headroom.","example":"2040"},"spentMicrosByDeliveryStatus":{"description":"The spend split by each payment’s `deliveryStatus` (the same values `GET /payments` reports), in micros, from what each payment still contributes to the cap (`chargedMicros`): its merchant leg plus any routing fee not given back. So `charged_not_delivered` is the total spent on calls whose merchant charge was observed and which delivered nothing — the merchant charge and any such fee together, not the merchant’s share alone. `not_delivered` is what is held for calls the merchant answered with an error, until reconciliation decides whether it charged. `pending` includes failed payments whose charge reconciliation has not decided yet, whose reserve is held until it does.","allOf":[{"$ref":"#/components/schemas/RouterSpendByDeliveryStatusDto"}]},"unattributedSpentMicros":{"type":"string","description":"`spentMicros` minus the sum of `spentMicrosByDeliveryStatus`: spend no payment record itemizes — older payments without exact micro reserves, and spend recorded outside the Router (direct x402 card settlements). Signed: a negative value means the records exceed the recorded spend and is reported as-is.","example":"0"}},"required":["id","capMicros","spentMicros","spentMicrosByDeliveryStatus","unattributedSpentMicros"]},"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},"chargedNotDelivered":{"type":"number","description":"Count of failed payments in the period whose merchant charge reconciliation OBSERVED on-chain (`deliveryStatus: charged_not_delivered`). A failed payment reconciliation has not decided yet is not counted, though it may still turn out charged. A count, not money: for the amount, read `spentMicrosByDeliveryStatus` on `GET /delegations/{id}`.","example":2},"series":{"description":"Per-bucket counts, oldest first.","type":"array","items":{"$ref":"#/components/schemas/PaymentsSummaryPointDto"}}},"required":["total","chargedNotDelivered","series"]},"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"},"semanticScore":{"type":"number","minimum":0,"maximum":100,"example":95,"description":"Absolute cosine-similarity score (0–100). Present only when `rankingSource` is `semantic`."},"lexicalScore":{"type":"number","minimum":0,"maximum":100,"example":82,"description":"Per-result-set normalized full-text rank (0–100). Present only when `rankingSource` is `lexical`."},"federatedScore":{"type":"number","minimum":0,"maximum":100,"description":"Peer-provided relevance score, sanitized to 0–100 but not comparable across registries. Present only when `rankingSource` is `federated`."},"rankingSource":{"type":"string","enum":["semantic","lexical","federated"],"description":"The scale used by this result item."},"matchReason":{"type":"string","enum":["semantic_similarity","lexical_match","federated_match"],"description":"Closed match explanation: semantic similarity, a lexical full-text match, or a relayed peer match."},"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","rankingSource","matchReason","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"]},"ArdExploreFacetBucketDto":{"type":"object","properties":{"value":{"type":"string","example":"application/a2a-agent-card+json"},"count":{"type":"number","example":389}},"required":["value","count"]},"ArdExploreFacetResultDto":{"type":"object","properties":{"buckets":{"type":"array","items":{"$ref":"#/components/schemas/ArdExploreFacetBucketDto"}},"otherCount":{"type":"number","description":"Matching entries in buckets beyond `limit`."}},"required":["buckets"]},"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"]},"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}}},"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"},"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"},"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"},"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"},"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"},"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"},"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"]}}}}