{"openapi":"3.0.0","paths":{"/api/v1/api-keys/register-key":{"post":{"description":"Register an API key from an encrypted NVM key. Supports two authentication methods: 1) Privy identity token (privy-id-token header) for frontend apps, 2) Client assertion JWT (clientAssertion in body) for backend/SDK usage.","operationId":"ApiKeysController_registerKey","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterApiKeyFromEncryptedKeyDto"}}}},"responses":{"201":{"description":"The API key hash and user information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginDto"}}}},"400":{"description":"Invalid NVM key"},"401":{"description":"Unauthorized - Invalid or missing authentication"},"403":{"description":"Forbidden - NVM key does not belong to authenticated user"}},"summary":"Privy identity token or Client Assertion authentication required","tags":["ApiKeys"]}},"/api/v1/api-keys":{"post":{"description":"Registers a new User API Key","operationId":"ApiKeysController_registerAPIKey","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterApiKeyDto"}}}},"responses":{"201":{"description":"Api Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyEntity"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"Public","tags":["ApiKeys"]},"get":{"description":"Get the user API Keys","operationId":"ApiKeysController_getUserApiKeys","parameters":[],"responses":{"200":{"description":"List of API Keys"},"400":{"description":"Bad Request"},"404":{"description":"Not Found"}},"security":[{"Authorization":[]}],"summary":"User (Backend Assertion Claim) required","tags":["ApiKeys"]},"patch":{"description":"Updates the name of a User API Key","operationId":"ApiKeysController_updateAPIKeyName","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateApiKeyNameDto"}}}},"responses":{"200":{"description":"Updated API Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyEntity"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"API Key not found or does not belong to user"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["ApiKeys"]},"delete":{"description":"Revokes a User API Key","operationId":"ApiKeysController_revokeAPIKey","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hash":{"type":"string","description":"The hash of the API key to revoke. If not provided, revokes the authenticated key."}}}}}},"responses":{"201":{"description":"Revoke result"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["ApiKeys"]}},"/api/v1/api-keys/search":{"post":{"description":"Searches for API Keys based on the provided criteria belonging to the user","operationId":"ApiKeysController_searchUserAPIKeys","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchApiKeyDto"}}}},"responses":{"200":{"description":"Api Keys"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"User (Backend Assertion Claim) required","tags":["ApiKeys"]}},"/api/v1/api-keys/txs":{"post":{"description":"Get the usage transactions of a session key","operationId":"ApiKeysController_getUsageSessionTxs","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchApiKeyTxsDto"}}}},"responses":{"200":{"description":"Session Key Txs"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["ApiKeys"]}},"/api/v1/api-keys/validate":{"post":{"description":"Validates an API Key Hash","operationId":"ApiKeysController_validateAPIKey","parameters":[],"responses":{"200":{"description":"Session Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyEntity"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["ApiKeys"]}},"/api/v1/metadata/profiles/me":{"get":{"description":"Get the current user profile based on Privy authentication. Creates the profile if it does not exist.","operationId":"UserProfileController_getMyProfile","parameters":[],"responses":{"200":{"description":"User profile returned (created if it did not exist)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUserProfileDto"}}}},"401":{"description":"Unauthorized - Invalid or missing Privy identity token"}},"security":[{"Authorization":[]}],"summary":"Get or create current user profile","tags":["User Profile"]}},"/api/v1/metadata/profiles":{"post":{"description":"Create a user profile entry","operationId":"UserProfileController_createUserProfile","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserProfileDto"}}}},"responses":{"201":{"description":"User profile is created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUserProfileDto"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Bad Request"}},"security":[{"Authorization":[]}],"summary":"Admin","tags":["User Profile"]}},"/api/v1/metadata/profiles/address/{publicAddress}":{"get":{"description":"Get the metadata of a user profile given an address","operationId":"UserProfileController_getUserProfileByAddress","parameters":[{"name":"publicAddress","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"202":{"description":"User profile returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUserProfileDto"}}}},"404":{"description":"Not found"}},"summary":"Public","tags":["User Profile"]}},"/api/v1/metadata/profiles/{userId}":{"put":{"description":"Update the user profile","operationId":"UserProfileController_updateUserProfileByUserId","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserProfileDto"}}}},"responses":{"200":{"description":"Return a updated user profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUserProfileDto"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Bad Request"},"404":{"description":"Not found"}},"security":[{"Authorization":[]}],"summary":"","tags":["User Profile"]},"delete":{"description":"Disable the user profile","operationId":"UserProfileController_disableUserProfileByUserId","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"User profile disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUserProfileDto"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Not found"}},"security":[{"Authorization":[]}],"summary":"","tags":["User Profile"]}},"/api/v1/organizations/account":{"post":{"description":"Authenticates user and creates wallet using Privy.","operationId":"OrganizationsController_createUserByOrganization","parameters":[],"requestBody":{"required":true,"description":"User credentials for JWT login","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateTokenDto"},"examples":{"example1":{"summary":"Privy login request","value":{"uniqueExternalId":"test-user-123","email":"user@example.com","role":"Member"}}}}}},"responses":{"200":{"description":"Login successful, returns wallet information","content":{"application/json":{"schema":{"type":"object","properties":{"signer":{"type":"object","properties":{"address":{"type":"string"}}}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"Authorization":[]}],"summary":"Create user by organization using Privy","tags":["Organizations"]}},"/api/v1/organizations/organizations":{"post":{"description":"Creates a new organization with the provided details. Requires NVM API Key authentication.","operationId":"OrganizationsController_createOrganization","parameters":[],"requestBody":{"required":true,"description":"Organization data to create","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrganizationDto"},"examples":{"example1":{"summary":"Basic organization creation","value":{"name":"My Organization","description":"A sample organization","url":"https://example.com","organizationWallet":"0x1234567890abcdef1234567890abcdef12345678"}}}}}},"responses":{"201":{"description":"Organization created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"organization":{"type":"object","properties":{"orgId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string"},"organizationWallet":{"type":"string"},"isActive":{"type":"boolean"},"orgType":{"type":"string"},"creatorId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Bad Request - Invalid input data"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"Authorization":[]}],"summary":"Create a new organization","tags":["Organizations"]}},"/api/v1/organizations/user-info/{userId}":{"get":{"description":"Get the organization info of a user","operationId":"OrganizationsController_getUserOrganizationInfo","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}},{"name":"environment","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"User organization info returned"},"404":{"description":"Not found"}},"security":[{"Authorization":[]}],"summary":"NVM API key or Privy identity token required","tags":["Organizations"]}},"/api/v1/organizations/members":{"post":{"description":"Get the members of an organization","operationId":"OrganizationsController_getOrganizationMembers","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchOrganizationMembersDto"}}}},"responses":{"200":{"description":"Organization details"},"400":{"description":"Bad Request"},"404":{"description":"Not Found"}},"security":[{"Authorization":[]}],"summary":"User","tags":["Organizations"]}},"/api/v1/organizations":{"put":{"description":"Allows organization admins to update metadata like name, description or url.","operationId":"OrganizationsController_updateOrganization","parameters":[],"requestBody":{"required":true,"description":"Organization properties that should be updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrganizationDto"}}}},"responses":{"200":{"description":"Organization updated successfully"},"404":{"description":"Organization not found"}},"security":[{"Authorization":[]}],"summary":"Update organization details","tags":["Organizations"]}},"/api/v1/organizations/branding":{"get":{"description":"Get organization branding by userId","operationId":"OrganizationsController_getOrganizationBrandingByUserId","parameters":[{"name":"userId","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Branding info or null"}},"summary":"Organization branding","tags":["Organizations"]},"post":{"description":"Save organization branding by userId","operationId":"OrganizationsController_saveOrganizationBrandingByUserId","parameters":[],"requestBody":{"required":true,"description":"Branding data to save","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveBrandingDto"}}}},"responses":{"200":{"description":"Branding saved successfully"},"404":{"description":"Organization not found"}},"security":[{"Authorization":[]}],"summary":"Save organization branding","tags":["Organizations"]}},"/api/v1/email/challenge":{"post":{"description":"Creates an email validation challenge","operationId":"EmailChallengeController_createEmailChallenge","parameters":[],"responses":{"201":{"description":"Email Challenge Event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailChallengeEntity"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"Admin","tags":["Email"]}},"/api/v1/email/challenge/search":{"get":{"description":"Given a user id get the email challenges associated to it","operationId":"EmailChallengeController_searchChallengesByAdmin","parameters":[],"responses":{"200":{"description":"Email Challenges","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailChallengeEntity"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"}},"security":[{"Authorization":[]}],"summary":"Admin","tags":["Email"]}},"/api/v1/email/validate/{id}/{token}":{"get":{"description":"Validates an email challenge via direct link (public endpoint)","operationId":"EmailChallengeController_validateEmailChallengeByLink","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Email successfully validated - Redirects to success page"},"403":{"description":"Invalid or expired token"},"404":{"description":"Challenge not found"}},"summary":"Public","tags":["Email"]}},"/api/v1/email/validate-challenge":{"post":{"description":"Validates an email challenge","operationId":"EmailChallengeController_validateEmailChallenge","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateEmailChallengeDto"}}}},"responses":{"201":{"description":"Suceess"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"Admin","tags":["Email"]}},"/api/v1/notifications/notification/{id}":{"get":{"description":"Given a notification id get the notification associated to it","operationId":"NotificationsController_getUserNotificationsById","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Notification details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationEntity"}}}},"400":{"description":"Bad Request"},"404":{"description":"Not Found"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["Notifications"]}},"/api/v1/notifications/search":{"post":{"description":"Search for notifications belonging to the user","operationId":"NotificationsController_searchNotifications","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchNotificationsDto"}}}},"responses":{"200":{"description":"List of notifications"},"400":{"description":"Bad Request"},"404":{"description":"Not Found"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["Notifications"]}},"/api/v1/notifications/status/{id}":{"put":{"description":"Update the notification status","operationId":"NotificationsController_updateNotificationStatus","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"readStatus","required":true,"in":"query","description":"read status of the notification","schema":{}}],"responses":{"201":{"description":"Notification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NvmAPIResultDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"User","tags":["Notifications"]}},"/api/v1/fiat/paypal/client-token":{"get":{"description":"Get Paypal client token. Requires Braintree configuration (BRAINTREE_MERCHANT_ID, BRAINTREE_PUBLIC_KEY, BRAINTREE_PRIVATE_KEY environment variables).","operationId":"FiatController_getClientToken","parameters":[],"responses":{"200":{"description":"Paypal client token"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"503":{"description":"Service Unavailable - Braintree/PayPal payment provider is not configured. Required environment variables: BRAINTREE_MERCHANT_ID, BRAINTREE_PUBLIC_KEY, BRAINTREE_PRIVATE_KEY"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required. Braintree must be configured.","tags":["Stripe"]}},"/api/v1/fiat/paypal/checkout":{"post":{"description":"Create paypal checkout. Requires Braintree configuration (BRAINTREE_MERCHANT_ID, BRAINTREE_PUBLIC_KEY, BRAINTREE_PRIVATE_KEY environment variables).","operationId":"FiatController_createPaypalCheckout","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaypalCheckoutDto"},"examples":{"basicCheckout":{"summary":"Basic PayPal checkout","description":"Create a PayPal checkout with required fields","value":{"nonce":"fake-valid-nonce","planId":"43298432984329","userId":"1234567890"}},"completeCheckout":{"summary":"Complete PayPal checkout with parameters","description":"Create a PayPal checkout with return URL parameters and NVM export","value":{"nonce":"fake-valid-nonce","planId":"43298432984329","userId":"1234567890","returnUrlQueryParams":{"source":"webapp","feature":"premium-plan"},"nvmExport":"true"}}}}}},"responses":{"200":{"description":"PayPal checkout created successfully","content":{"application/json":{"schema":{"example":{"success":true,"transactionId":"txn_1O4KfNBYvSRKcV42ABC123","status":"submitted_for_settlement"}}}}},"400":{"description":"Bad Request - Invalid checkout data","content":{"application/json":{"schema":{"example":{"code":"BCK.STRIPE.0010","httpStatus":400,"message":"Unable to create PayPal checkout","params":{"error":"Invalid nonce or plan ID"}}}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"example":{"code":"BCK.APIKEY.0004","httpStatus":401,"message":"Invalid API key"}}}}},"403":{"description":"Forbidden - Insufficient permissions"},"503":{"description":"Service Unavailable - Braintree/PayPal payment provider is not configured. Required environment variables: BRAINTREE_MERCHANT_ID, BRAINTREE_PUBLIC_KEY, BRAINTREE_PRIVATE_KEY","content":{"application/json":{"schema":{"example":{"code":"BCK.STRIPE.0011","httpStatus":503,"message":"Braintree/PayPal service unavailable","params":{"reason":"Missing configuration"}}}}}}},"security":[{"Authorization":[]}],"summary":"","tags":["Stripe"]}},"/api/v1/fiat/paypal/webhook":{"post":{"description":"Handle Paypal webhook. Requires Braintree configuration (BRAINTREE_MERCHANT_ID, BRAINTREE_PUBLIC_KEY, BRAINTREE_PRIVATE_KEY environment variables).","operationId":"FiatController_handleWebhook","parameters":[],"responses":{"200":{"description":"Webhook processed"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable - Braintree/PayPal payment provider is not configured. Required environment variables: BRAINTREE_MERCHANT_ID, BRAINTREE_PUBLIC_KEY, BRAINTREE_PRIVATE_KEY"}},"summary":"","tags":["Stripe"]}},"/api/v1/fiat/stripe/account":{"post":{"description":"Create stripe account","operationId":"FiatController_createStripeAccount","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStripeAccountDto"}}}},"responses":{"201":{"description":"Stripe Account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStripeAccountDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["Stripe"]}},"/api/v1/fiat/stripe/account/balance":{"get":{"description":"It gets the account balance of the connected Stripe account","operationId":"FiatController_getAccountBalance","parameters":[],"responses":{"200":{"description":"Stripe Account Balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeAccountBalanceDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["Stripe"]}},"/api/v1/fiat/stripe/payment":{"post":{"description":"Create stripe checkout payment intent","operationId":"FiatController_createStripePaymentIntent","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStripePaymentIntentDto"},"examples":{"basicPayment":{"summary":"Basic payment intent","description":"Create a payment intent with minimal required fields","value":{"planId":"43298432984329","language":"en"}},"completePayment":{"summary":"Complete payment intent with customer details","description":"Create a payment intent with customer email, name, and return URL parameters","value":{"planId":"43298432984329","language":"en","sessionId":"39293121O4KfNBYvSRKcV42","nvmExport":"true","returnUrlQueryParams":{"source":"webapp","feature":"premium-plan"},"email":"john.doe@example.com","name":"John Doe"}}}}}},"responses":{"200":{"description":"Stripe Payment Intent created successfully","content":{"application/json":{"schema":{"example":{"clientSecret":"pi_3O4KfNBYvSRKcV42_secret_ABC123XYZ456","paymentIntentId":"pi_3O4KfNBYvSRKcV42","sessionId":"39293121O4KfNBYvSRKcV42"}}}}},"400":{"description":"Bad Request - Invalid payment data","content":{"application/json":{"schema":{"example":{"code":"BCK.STRIPE.0003","httpStatus":400,"message":"Unable to create Stripe payment intent","params":{"sessionId":"39293121O4KfNBYvSRKcV42","error":"Invalid plan ID or payment configuration"}}}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"example":{"code":"BCK.APIKEY.0004","httpStatus":401,"message":"Invalid API key"}}}}},"403":{"description":"Forbidden - Insufficient permissions"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["Stripe"]}},"/api/v1/fiat/stripe/subscription":{"post":{"description":"Create stripe subscription","operationId":"FiatController_createStripeSubscription","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStripeSubscriptionDto"},"examples":{"basicSubscription":{"summary":"Basic subscription","description":"Create a subscription with minimal required fields","value":{"planId":"43298432984329"}},"completeSubscription":{"summary":"Complete subscription with payment method","description":"Create a subscription with price ID, payment method, and customer details","value":{"planId":"43298432984329","priceId":"price_1O4KfNBYvSRKcV42ABC123","paymentMethodId":"pm_1O4KfNBYvSRKcV42XYZ789","email":"john.doe@example.com","name":"John Doe","language":"en","returnUrl":"https://example.com/payment-success","returnUrlQueryParams":{"source":"webapp","tier":"premium"},"nvmExport":"true"}}}}}},"responses":{"201":{"description":"Stripe Subscription created successfully","content":{"application/json":{"schema":{"example":{"subscriptionId":"sub_1O4KfNBYvSRKcV42ABC123","clientSecret":"seti_1O4KfNBYvSRKcV42_secret_XYZ789","status":"active"}}}}},"400":{"description":"Bad Request - Invalid subscription data","content":{"application/json":{"schema":{"example":{"code":"BCK.STRIPE.0021","httpStatus":400,"message":"Unable to create Stripe subscription","params":{"sessionId":"39293121O4KfNBYvSRKcV42","error":"Invalid price ID or payment method"}}}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"example":{"code":"BCK.APIKEY.0004","httpStatus":401,"message":"Invalid API key"}}}}},"403":{"description":"Forbidden - Insufficient permissions"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["Stripe"]}},"/api/v1/fiat/stripe/webhook/account":{"post":{"description":"Process Stripe Webhooks of Account type. This endpoint receives webhook events from Stripe for account-related activities (payment intents, charges, etc.). Requires stripe-signature header for verification.","operationId":"FiatController_processStripeWebhookAccount","parameters":[],"responses":{"200":{"description":"Webhook processed successfully","content":{"application/json":{"schema":{"example":{"received":true}}}}},"400":{"description":"Bad Request - Webhook processing failed","content":{"application/json":{"schema":{"example":{"code":"BCK.STRIPE.0004","httpStatus":400,"message":"Unable to process Stripe webhook","params":{"error":"Invalid signature or malformed payload"}}}}}}},"summary":"Stripe Webhook Authorization","tags":["Stripe"]}},"/api/v1/fiat/stripe/webhook/connect":{"post":{"description":"Process Stripe Webhooks of Connect type. This endpoint receives webhook events from Stripe Connect for connected account activities. Requires stripe-signature header for verification.","operationId":"FiatController_processStripeWebhookConnect","parameters":[],"responses":{"200":{"description":"Webhook processed successfully","content":{"application/json":{"schema":{"example":{"received":true}}}}},"400":{"description":"Bad Request - Webhook processing failed","content":{"application/json":{"schema":{"example":{"code":"BCK.STRIPE.0005","httpStatus":400,"message":"Unable to process Stripe Connect webhook","params":{"error":"Invalid signature or malformed payload"}}}}}}},"summary":"Stripe Webhook Authorization","tags":["Stripe"]}},"/api/v1/fiat/stripe/payment-intent/{paymentIntentId}/metadata":{"get":{"description":"Get PaymentIntent metadata by client secret","operationId":"FiatController_getPaymentIntentMetadata","parameters":[{"name":"paymentIntentId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"PaymentIntent metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentMetadataDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"PaymentIntent not found"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["Stripe"]}},"/api/v1/fiat/stripe/invoices/{planId}":{"get":{"description":"Get invoice details","operationId":"FiatController_getInvoices","parameters":[{"name":"planId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Invoice details"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["Stripe"]}},"/api/v1/fiat/stripe/subscription/{planId}":{"get":{"description":"Get subscription by planId","operationId":"FiatController_getSubscriptionByPlanId","parameters":[{"name":"planId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Subscription"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["Stripe"]},"delete":{"description":"Cancel a subscription","operationId":"FiatController_cancelSubscription","parameters":[{"name":"planId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Subscription canceled"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["Stripe"]}},"/api/v1/fiat/stripe/connect/countries":{"get":{"description":"List countries supported by Stripe Connect (from Stripe Country Specs)","operationId":"FiatController_getConnectSupportedCountries","parameters":[],"responses":{"200":{"description":"Array of countries supported by Stripe Connect","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","example":"us"},"label":{"type":"string","example":"United States"}}}}}}}},"summary":"Get supported countries","tags":["Stripe"]}},"/":{"get":{"description":"Get API info","operationId":"InfoController_getInfo","parameters":[],"responses":{"200":{"description":"Return API Info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetInfoDto"}}}}},"summary":"Public","tags":["Info"]}},"/api/v1/protocol/plans/{planId}":{"get":{"description":"Retrieve complete payment plan details including metadata, pricing configuration, credits configuration, and associated agents","operationId":"ProtocolController_getPlan","parameters":[{"name":"planId","required":true,"in":"path","description":"Unique identifier of the payment plan (BigInt as string)","schema":{"format":"int64","example":"43298432984329","type":"integer"}}],"responses":{"200":{"description":"Payment plan details retrieved successfully","content":{"application/json":{"schema":{"example":{"planId":"43298432984329","metadata":{"main":{"name":"Premium AI Access","description":"Pay-as-you-go AI agent access","author":"Nevermined AI Inc.","tags":["AI","Premium","Credits"]},"plan":{"isTrialPlan":false,"recurringSubscription":false,"accessLimit":"credits"}},"registry":{"price":{"isCrypto":true,"amounts":["1000000000000000000"],"receivers":["0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"],"tokenAddress":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","templateAddress":"0x0000000000000000000000000000000000000000"},"credits":{"isRedemptionAmountFixed":true,"redemptionType":2,"amount":"1000","minAmount":"1","maxAmount":"1"}},"owner":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"}}}}},"400":{"description":"Bad Request - Invalid plan ID format","content":{"application/json":{"schema":{"example":{"code":"BCK.COMMON.0014","httpStatus":404,"message":"Plan not found"}}}}},"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":"Public endpoint - no authentication required","tags":["Protocol"]},"put":{"description":"Update the Plan Metadata","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":"Nevermined API Key required","tags":["Protocol"]}},"/api/v1/protocol/agents/{agentId}":{"get":{"description":"Retrieve complete AI agent details including metadata, API endpoints, authentication configuration, and associated payment plans","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 agent ID format"},"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":"Public endpoint - no authentication required","tags":["Protocol"]},"put":{"description":"Update the AI Agent Metadata","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":"Nevermined API Key required","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","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 plan ID or address format"},"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":"Public endpoint - no authentication required","tags":["Protocol"]}},"/api/v1/protocol/plans":{"post":{"description":"Register a new payment plan on the blockchain and store its metadata","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,"proofRequired":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":"Nevermined API Key required","tags":["Protocol"]},"get":{"description":"Get paginated payment plans for the current user. Supports pagination and sorting by any indexed field.","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":"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":"Nevermined API Key or Privy identity token required","tags":["Protocol"]}},"/api/v1/protocol/agents/plans":{"post":{"description":"Register a new AI agent and its associated payment plan in a single transaction","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,"proofRequired":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":"Nevermined API Key required","tags":["Protocol"]}},"/api/v1/protocol/agents":{"post":{"description":"Register a new AI agent with its API endpoints, authentication, and associated payment plans","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":"Nevermined API Key required","tags":["Protocol"]},"get":{"description":"Get paginated agents for the current user. Supports pagination and sorting by any indexed field.","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":"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":"Nevermined API Key or Privy ID Token required","tags":["Protocol"]}},"/api/v1/protocol/plans/{planId}/order":{"post":{"description":"Register a new agent","operationId":"ProtocolController_order","parameters":[{"name":"planId","required":true,"in":"path","description":"unique identifier of the payment plan","schema":{"format":"int64","type":"integer"}}],"responses":{"201":{"description":"Agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","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.","operationId":"ProtocolController_mintCredits","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MintPlanDto"},"examples":{"mintCredits":{"summary":"Mint 150 credits","description":"Add 150 credits to the payment plan for the specified user address","value":{"planId":"43298432984329","creditsReceiver":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","amount":"150"}}}}}},"responses":{"201":{"description":"Credits successfully minted","content":{"application/json":{"schema":{"example":{"success":true,"message":"Credits minted successfully","txHash":"0xdef456...","httpStatus":201}}}}},"400":{"description":"Bad Request - Invalid plan ID or amount","content":{"application/json":{"schema":{"example":{"code":"BCK.PROTOCOL.0007","httpStatus":400,"message":"Error minting plan","params":{"planId":"43298432984329","amount":"150"}}}}}},"401":{"description":"Unauthorized - Invalid or missing API key"},"403":{"description":"Forbidden - Only the plan owner can mint credits","content":{"application/json":{"schema":{"example":{"code":"BCK.PROTOCOL.0017","httpStatus":401,"message":"The user doesnt own this plan"}}}}}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["Protocol"]}},"/api/v1/protocol/plans/mintExpirable":{"post":{"description":"Mint credits for a payment plan","operationId":"ProtocolController_mintCreditsExpirable","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MintPlanExpirableDto"}}}},"responses":{"201":{"description":"Result of the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NvmAPIResultDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["Protocol"]}},"/api/v1/protocol/agents/{agentId}/plan/{planId}":{"delete":{"description":"Remove a payment plan from an agent","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":"Nevermined API Key required","tags":["Protocol"]},"post":{"description":"Adds a payment plan to an agent","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":"Nevermined API Key required","tags":["Protocol"]}},"/api/v1/protocol/agents/{agentId}/list/{activate}":{"put":{"description":"Update the AI Agent Metadata","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":"Nevermined API Key required","tags":["Protocol"]}},"/api/v1/protocol/plans/{planId}/list/{activate}":{"put":{"description":"List or Unlist a Plan","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":"Nevermined API Key required","tags":["Protocol"]}},"/api/v1/protocol/all-plans":{"get":{"description":"Get all paginated payment plans. Supports pagination, sorting, and filtering by plan name (prefix match).","operationId":"ProtocolController_getAllPlans","parameters":[{"name":"sortBy","required":false,"in":"query","description":"Sorting criteria by field","schema":{"example":"created","type":"string"}},{"name":"sortOrder","required":false,"in":"query","description":"Sorting order (asc or desc)","schema":{"example":"desc","type":"string"}},{"name":"name","required":false,"in":"query","description":"Filter by plan name or plan ID (substring match, case-insensitive for names)","schema":{"example":"Premium","type":"string"}},{"name":"offset","required":false,"in":"query","description":"Number of items per page (default: 10)","schema":{"example":10,"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number to retrieve (default: 1)","schema":{"example":1,"type":"number"}}],"responses":{"200":{"description":"Paginated payment plans","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedPaymentPlansDto"}}}}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key or Privy identity token required","tags":["Protocol"]}},"/api/v1/protocol/agents/{agentId}/plans":{"get":{"description":"Get paginated payment plans for an agent","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":"","tags":["Protocol"]}},"/api/v1/protocol/plans/{planId}/agents":{"get":{"description":"Get paginated agents associated to a plan","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":"","tags":["Protocol"]}},"/api/v1/protocol/agent-sub-tasks":{"post":{"description":"Track an agent sub task","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":"Nevermined API Key required","tags":["Protocol"]}},"/api/v1/protocol/agents/simulate/start":{"post":{"description":"Simulate an agent request","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":"Nevermined API Key required","tags":["Protocol"]}},"/api/v1/protocol/agents/simulate/finish":{"post":{"description":"Simulate the redemption of credits for an agent request","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":"Nevermined API Key required","tags":["Protocol"]}},"/api/v1/observability/requests":{"get":{"description":"Get paginated observability requests for the current user. Supports pagination.","operationId":"ObservabilityController_getRequests","parameters":[{"name":"planName","required":false,"in":"query","description":"Filter requests by plan name","schema":{"example":"premium-plan","type":"string"}},{"name":"agentName","required":false,"in":"query","description":"Filter requests by agent name","schema":{"example":"agent-name","type":"string"}},{"name":"customerName","required":false,"in":"query","description":"Filter requests by customer name","schema":{"example":"customer-name","type":"string"}},{"name":"model","required":false,"in":"query","description":"Filter requests by model","schema":{"example":"gpt-4o-mini-2024-07-18","type":"string"}},{"name":"provider","required":false,"in":"query","description":"Filter requests by provider","schema":{"example":"OPENAI","type":"string"}},{"name":"textSearch","required":false,"in":"query","description":"Text search across request and response bodies","schema":{"example":"financial report","type":"string"}},{"name":"time","required":false,"in":"query","description":"Time filter for requests","schema":{"enum":["4h","8h","24h","week","all"],"type":"string"}},{"name":"offset","required":false,"in":"query","description":"Number of items per page (default: 25)","schema":{"example":25,"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number to retrieve (default: 1)","schema":{"example":1,"type":"number"}}],"responses":{"200":{"description":"Paginated observability requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedRequestsDto"}}}},"400":{"description":"Invalid response from Helicone API"},"401":{"description":"Unauthorized access to Helicone API"},"429":{"description":"Rate limit exceeded for Helicone API"},"500":{"description":"Error fetching observability data from Helicone"},"502":{"description":"Helicone API service unavailable"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["Observability"]}},"/api/v1/observability/analytics/timeseries":{"get":{"operationId":"ObservabilityController_getAnalyticsTimeseries","parameters":[{"name":"currency","required":true,"in":"query","schema":{"type":"string"}},{"name":"planName","required":true,"in":"query","schema":{"type":"string"}},{"name":"agentName","required":true,"in":"query","schema":{"type":"string"}},{"name":"customerName","required":true,"in":"query","schema":{"type":"string"}},{"name":"model","required":true,"in":"query","schema":{"type":"string"}},{"name":"provider","required":true,"in":"query","schema":{"type":"string"}},{"name":"textSearch","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"Authorization":[]}],"summary":"Aggregated analytics time series","tags":["Observability"]}},"/api/v1/observability/analytics/cumulative":{"get":{"operationId":"ObservabilityController_getAnalyticsCumulative","parameters":[{"name":"currency","required":true,"in":"query","schema":{"type":"string"}},{"name":"planName","required":true,"in":"query","schema":{"type":"string"}},{"name":"agentName","required":true,"in":"query","schema":{"type":"string"}},{"name":"customerName","required":true,"in":"query","schema":{"type":"string"}},{"name":"model","required":true,"in":"query","schema":{"type":"string"}},{"name":"provider","required":true,"in":"query","schema":{"type":"string"}},{"name":"textSearch","required":true,"in":"query","schema":{"type":"string"}},{"name":"perHour","required":true,"in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":""}},"security":[{"Authorization":[]}],"summary":"Aggregated analytics cumulative series","tags":["Observability"]}},"/api/v1/observability/analytics/summary":{"get":{"operationId":"ObservabilityController_getAnalyticsSummary","parameters":[{"name":"currency","required":true,"in":"query","schema":{"type":"string"}},{"name":"planName","required":true,"in":"query","schema":{"type":"string"}},{"name":"agentName","required":true,"in":"query","schema":{"type":"string"}},{"name":"customerName","required":true,"in":"query","schema":{"type":"string"}},{"name":"model","required":true,"in":"query","schema":{"type":"string"}},{"name":"provider","required":true,"in":"query","schema":{"type":"string"}},{"name":"textSearch","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"Authorization":[]}],"summary":"Aggregated analytics summary","tags":["Observability"]}},"/api/v1/transactions/plans/{planId}":{"get":{"description":"Given a planId get the asset transactions related to it","operationId":"TransactionsController_getPlanTransactionsById","parameters":[{"name":"planId","required":true,"in":"path","description":"ID of the plan to retrieve transactions for","schema":{"format":"int64","type":"integer"}},{"name":"offset","required":false,"in":"query","description":"number of transactions to retrieve in one page","schema":{"default":10000,"type":"number"}},{"name":"page","required":false,"in":"query","description":"page of the transaction list to retrieve","schema":{"default":1,"type":"number"}}],"responses":{"200":{"description":"List of incoming transactions"},"400":{"description":"Bad Request"},"404":{"description":"Not Found"}},"summary":"Public","tags":["Transactions"]}},"/api/v1/transactions/search":{"post":{"description":"Search for plan transactions","operationId":"TransactionsController_searchPlanTransactions","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPlanTransactionsDto"}}}},"responses":{"200":{"description":"List of incoming transactions"},"400":{"description":"Bad Request"},"404":{"description":"Not Found"}},"summary":"Public","tags":["Transactions"]}},"/api/v1/transactions/search-org":{"post":{"description":"Search for plan transactions for all members of the organization (admin only)","operationId":"TransactionsController_searchOrganizationPlanTransactions","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPlanTransactionsDto"}}}},"responses":{"200":{"description":"List of organization plan transactions"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["Transactions"]}},"/api/v1/transactions/plans-purchased":{"get":{"description":"Get the different plans purchased by an account","operationId":"TransactionsController_getPlansPurchased","parameters":[{"name":"offset","required":false,"in":"query","description":"number of transactions to retrieve in one page","schema":{"default":10000,"type":"number"}},{"name":"page","required":false,"in":"query","description":"page of the transaction list to retrieve","schema":{"default":1,"type":"number"}}],"responses":{"200":{"description":"List of plans purchased"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["Transactions"]}},"/api/v1/transactions/plans-purchased-detailed":{"get":{"description":"Get the different plans purchased by an account with detailed plan and agent information","operationId":"TransactionsController_getPlansPurchasedDetailed","parameters":[{"name":"offset","required":false,"in":"query","description":"number of transactions to retrieve in one page","schema":{"default":10000,"type":"number"}},{"name":"page","required":false,"in":"query","description":"page of the transaction list to retrieve","schema":{"default":1,"type":"number"}}],"responses":{"200":{"description":"List of plans purchased with detailed information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanPurchasedDetailedDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"summary":"NVM API Key or Privy ID Token required","tags":["Transactions"]}},"/api/v1/transactions/incoming":{"get":{"description":"Get the incoming transactions received by an account","operationId":"TransactionsController_getIncomingTransactions","parameters":[{"name":"offset","required":false,"in":"query","description":"number of transactions to retrieve in one page","schema":{"default":10000,"type":"number"}},{"name":"page","required":false,"in":"query","description":"page of the transaction list to retrieve","schema":{"default":1,"type":"number"}}],"responses":{"200":{"description":"List of incoming transactions"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["Transactions"]}},"/api/v1/transactions/expending":{"get":{"description":"Get the expending transactions made by an account","operationId":"TransactionsController_getExpendingAccountTransactions","parameters":[{"name":"offset","required":false,"in":"query","description":"number of transactions to retrieve in one page","schema":{"default":10000,"type":"number"}},{"name":"page","required":false,"in":"query","description":"page of the transaction list to retrieve","schema":{"default":1,"type":"number"}}],"responses":{"200":{"description":"List of expending transactions"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["Transactions"]}},"/api/v1/transactions/ranking":{"get":{"description":"Get metrics for accounts","operationId":"TransactionsController_getRanking","parameters":[],"responses":{"200":{"description":"ranking transactions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetRankingDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["Transactions"]}},"/api/v1/transactions/dashboard-metrics":{"get":{"description":"Get all dashboard metrics for an account in a single call (active users, API calls, and revenue)","operationId":"TransactionsController_getDashboardMetrics","parameters":[{"name":"startDate","required":false,"in":"query","description":"Start date for the period (ISO string format)","schema":{"example":"2024-01-01T00:00:00.000Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date for the period (ISO string format)","schema":{"example":"2024-01-31T23:59:59.999Z","type":"string"}}],"responses":{"200":{"description":"Complete dashboard metrics including active users, API calls, and revenue data with variations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardMetricsResponseDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"Nevermined API Key required","tags":["Transactions"]}},"/api/v1/files/avatar":{"post":{"description":"Upload avatar image file to the cloud and send to transcoder server","operationId":"TranscodingProviderController_sendAvatar","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataFileDto"}}}},"responses":{"201":{"description":"Avatar image file is uploaded and sended to transcode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFileUrlDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"User","tags":["TranscodingProvider"]}},"/api/v1/files/cover":{"post":{"description":"Upload cover image file to the cloud and send to transcoder server","operationId":"TranscodingProviderController_sendCover","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataFileDto"}}}},"responses":{"201":{"description":"Cover image file is uploaded and sended to transcode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFileUrlDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"User","tags":["TranscodingProvider"]}},"/api/v1/files/animation":{"post":{"description":"Upload animation file to the cloud and send to transcoder server","operationId":"TranscodingProviderController_sendAnimation","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataFileDto"}}}},"responses":{"201":{"description":"Animation file is uploaded and sended to transcode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFileUrlDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"User","tags":["TranscodingProvider"]}},"/api/v1/files/image":{"post":{"description":"Upload image file to the cloud and send to transcoder server","operationId":"TranscodingProviderController_sendImage","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataFileDto"}}}},"responses":{"201":{"description":"Image file is uploaded and sended to transcode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFileUrlDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"User","tags":["TranscodingProvider"]}},"/api/v1/files/terms":{"post":{"description":"Upload terms and conditions file to the cloud and send to transcoder server","operationId":"TranscodingProviderController_sendTerms","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataFileDto"}}}},"responses":{"201":{"description":"Terms and conditions file is uploaded and sended to transcode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFileUrlDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"User","tags":["TranscodingProvider"]}},"/api/v1/files/video":{"post":{"description":"Upload video file to the cloud and send to transcoder server","operationId":"TranscodingProviderController_sendVideo","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataFileDto"}}}},"responses":{"201":{"description":"Video file is uploaded and sended to transcode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFileUrlDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"User","tags":["TranscodingProvider"]}},"/api/v1/files/audio":{"post":{"description":"Upload video file to the cloud and send to transcoder server","operationId":"TranscodingProviderController_sendAudio","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataFileDto"}}}},"responses":{"201":{"description":"Video file is uploaded and sended to transcode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFileUrlDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"User","tags":["TranscodingProvider"]}},"/api/v1/files/private-file":{"post":{"description":"Upload file to the restricted bucket cloud","operationId":"TranscodingProviderController_sendPrivateFile","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataFileDto"}}}},"responses":{"201":{"description":"Private file is uploaded in restricted bucket","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFileUrlDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"User","tags":["TranscodingProvider"]}},"/api/v1/files/sample-data":{"post":{"description":"Upload sample data in google storage","operationId":"TranscodingProviderController_sendSampleDataFile","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataFileDto"}}}},"responses":{"201":{"description":"Sample data file is uploaded in google storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFileUrlDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"Authorization":[]}],"summary":"User","tags":["TranscodingProvider"]}},"/api/v1/files/{ugcId}":{"get":{"description":"Get the url where is hosted the file","operationId":"TranscodingProviderController_findFile","parameters":[{"name":"ugcId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":"The url of the file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFileUrlDto"}}}},"404":{"description":"Not found"}},"summary":"Public","tags":["TranscodingProvider"]}},"/oauth/authorize":{"post":{"description":"Generate OAuth 2.1 authorization code. Frontend handles checkout/validation. Backend only generates and stores the code.","operationId":"OAuthController_authorize","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorizeRequestDto"}}}},"responses":{"201":{"description":"Authorization code generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorizeResponseDto"}}}},"400":{"description":"Bad Request - Invalid parameters"},"401":{"description":"Unauthorized - User not authenticated"},"404":{"description":"Not Found - Agent not found"}},"security":[{"Authorization":[]}],"summary":"Generate Authorization Code","tags":["OAuth"]}},"/oauth/token":{"post":{"description":"OAuth 2.1 Token endpoint. Exchanges authorization code for access token (JWT). Does not require user authentication - the code contains user information.","operationId":"OAuthController_token","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequestDto"}}}},"responses":{"200":{"description":"Access token response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponseDto"}}}},"400":{"description":"Bad Request - Invalid code, PKCE validation failed, or other errors"}},"summary":"OAuth Token Endpoint","tags":["OAuth"]}},"/api/v1/x402/permissions":{"post":{"description":"Create a permission and generate an x402 access token for a payment plan","operationId":"X402Controller_createPermission","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateX402TokenDto"},"examples":{"basicPermission":{"summary":"Basic crypto permission (nvm:erc4337)","description":"Create a permission with minimal x402 PaymentPayload structure","value":{"accepted":{"scheme":"nvm:erc4337","network":"eip155:84532","planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071"}}},"permissionWithAgent":{"summary":"Crypto permission with agent and endpoint","description":"Create a permission with agentId, endpoint, and httpVerb for validation","value":{"resource":{"url":"https://myagent.ai/api/v1/tasks","description":"AI agent task execution"},"accepted":{"scheme":"nvm:erc4337","network":"eip155:84532","planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071","extra":{"agentId":"80918427023170428029540261117198154464497879145267720259488529685089104529015","httpVerb":"POST"}}}},"permissionWithLimits":{"summary":"Crypto permission with session key limits","description":"Create a permission with redemption limit, order limit, and expiration","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"}},"sessionKeyConfig":{"redemptionLimit":100,"orderLimit":"1000000000000000000","expiration":"2025-12-31T23:59:59Z"}}},"cardDelegation":{"summary":"Card delegation permission (nvm:card-delegation)","description":"Create a delegation-based permission using a Stripe payment method for fiat settlement","value":{"accepted":{"scheme":"nvm:card-delegation","network":"stripe","planId":"delegation"},"delegationConfig":{"providerPaymentMethodId":"pm_1Abc2Def3Ghi4Jkl","spendingLimitCents":10000,"durationSecs":604800,"currency":"usd"}}},"cardDelegationWithMerchant":{"summary":"Card delegation with merchant routing","description":"Create a delegation-based permission with Stripe Connect merchant account routing","value":{"accepted":{"scheme":"nvm:card-delegation","network":"stripe","planId":"delegation"},"delegationConfig":{"providerPaymentMethodId":"pm_1Abc2Def3Ghi4Jkl","spendingLimitCents":50000,"durationSecs":2592000,"currency":"usd","merchantAccountId":"acct_1ReAt6BTy5gR9Yy6","maxTransactions":100}}}}}}},"responses":{"201":{"description":"Permission successfully created and X402 access token generated","content":{"application/json":{"schema":{"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":"Get paginated list of permissions for the authenticated user","operationId":"X402Controller_getPermissions","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Number of results per page (default: 10)","schema":{"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":{"example":{"totalResults":137,"page":1,"offset":20,"permissions":[{"permissionHash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071","planName":"Premium AI Access","orderLimit":"1000000000000000000","redemptionLimit":10,"createdAt":"2025-01-10T12:00:00Z","status":"Active"},{"permissionHash":"0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890","planId":"79102475636047497640080230236781474129970992727896593861997347135613135571085","planName":"Basic API Access","orderLimit":"500000000000000000","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","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"}}}}}}},"summary":"Verify permission usage","tags":["X402"]}},"/api/v1/x402/settle":{"post":{"description":"Settles delegated permissions for a plan using an existing session key","operationId":"X402Controller_settlePermissions","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlePermissionsDto"},"examples":{"settleBasic":{"summary":"Basic settlement","description":"Settle permissions by redeeming a fixed credit amount. The facilitator validates that the accepted payment method matches one of the accepts.","value":{"paymentRequired":{"x402Version":2,"error":"Payment required to access resource","resource":{"url":"/api/v1/agents/tasks","description":"AI agent task execution"},"accepts":[{"scheme":"nvm:erc4337","network":"eip155:84532","planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071","extra":{"version":"1"}}],"extensions":{}},"x402AccessToken":"eyJ4NDAyVmVyc2lvbiI6MiwicmVzb3VyY2UiOnsidXJsIjoiL2FwaS92MS9hZ2VudHMvdGFza3MifSwiYWNjZXB0ZWQiOnsic2NoZW1lIjoibnZtOmVyYzQzMzciLCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMyIiwicGxhbklkIjoiNDQ3NDI3NjMwNzYwNDc0OTc2NDAwODAyMzAyMzY3ODE0NzQxMjk5NzA5OTI3Mjc4OTY1OTM4NjE5OTczNDcxMzU2MTMxMzU1NzEwNzEiLCJleHRyYSI6eyJ2ZXJzaW9uIjoiMSJ9fSwicGF5bG9hZCI6eyJzaWduYXR1cmUiOiIweDEyMzQiLCJhdXRob3JpemF0aW9uIjp7ImZyb20iOiIweGYzOUZkNmU1MWFhZDg4RjZGNGNlNmFCODgyNzI3OWNmZkZiOTIyNjYiLCJzZXNzaW9uS2V5c1Byb3ZpZGVyIjoiemVyb2RldiIsInNlc3Npb25LZXlzIjpbXX19LCJleHRlbnNpb25zIjp7fX0=","maxAmount":"2","agentRequestId":"arId-123e4567-e89b-12d3-a456-426614174000"}},"settleWithMargin":{"summary":"Settle with margin percentage","description":"Settle permissions using actual cost with a margin percentage added. Useful when the exact cost is determined after processing.","value":{"paymentRequired":{"x402Version":2,"error":"Payment required to access resource","resource":{"url":"/api/v1/agents/tasks","description":"AI agent task execution"},"accepts":[{"scheme":"nvm:erc4337","network":"eip155:84532","planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071","extra":{"version":"1"}}],"extensions":{}},"x402AccessToken":"eyJ4NDAyVmVyc2lvbiI6MiwicmVzb3VyY2UiOnsidXJsIjoiL2FwaS92MS9hZ2VudHMvdGFza3MifSwiYWNjZXB0ZWQiOnsic2NoZW1lIjoibnZtOmVyYzQzMzciLCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMyIiwicGxhbklkIjoiNDQ3NDI3NjMwNzYwNDc0OTc2NDAwODAyMzAyMzY3ODE0NzQxMjk5NzA5OTI3Mjc4OTY1OTM4NjE5OTczNDcxMzU2MTMxMzU1NzEwNzEiLCJleHRyYSI6eyJ2ZXJzaW9uIjoiMSJ9fSwicGF5bG9hZCI6eyJzaWduYXR1cmUiOiIweDEyMzQiLCJhdXRob3JpemF0aW9uIjp7ImZyb20iOiIweGYzOUZkNmU1MWFhZDg4RjZGNGNlNmFCODgyNzI3OWNmZkZiOTIyNjYiLCJzZXNzaW9uS2V5c1Byb3ZpZGVyIjoiemVyb2RldiIsInNlc3Npb25LZXlzIjpbXX19LCJleHRlbnNpb25zIjp7fX0=","agentRequestId":"arId-123e4567-e89b-12d3-a456-426614174000","marginPercent":0.2}},"settleBatch":{"summary":"Settle batch request","description":"Settle permissions for a batch of LLM calls under a single agentRequestId. Use this when aggregating multiple operations.","value":{"paymentRequired":{"x402Version":2,"error":"Payment required to access resource","resource":{"url":"/api/v1/agents/tasks","description":"AI agent task execution"},"accepts":[{"scheme":"nvm:erc4337","network":"eip155:84532","planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071","extra":{"version":"1"}}],"extensions":{}},"x402AccessToken":"eyJ4NDAyVmVyc2lvbiI6MiwicmVzb3VyY2UiOnsidXJsIjoiL2FwaS92MS9hZ2VudHMvdGFza3MifSwiYWNjZXB0ZWQiOnsic2NoZW1lIjoibnZtOmVyYzQzMzciLCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMyIiwicGxhbklkIjoiNDQ3NDI3NjMwNzYwNDc0OTc2NDAwODAyMzAyMzY3ODE0NzQxMjk5NzA5OTI3Mjc4OTY1OTM4NjE5OTczNDcxMzU2MTMxMzU1NzEwNzEiLCJleHRyYSI6eyJ2ZXJzaW9uIjoiMSJ9fSwicGF5bG9hZCI6eyJzaWduYXR1cmUiOiIweDEyMzQiLCJhdXRob3JpemF0aW9uIjp7ImZyb20iOiIweGYzOUZkNmU1MWFhZDg4RjZGNGNlNmFCODgyNzI3OWNmZkZiOTIyNjYiLCJzZXNzaW9uS2V5c1Byb3ZpZGVyIjoiemVyb2RldiIsInNlc3Npb25LZXlzIjpbXX19LCJleHRlbnNpb25zIjp7fX0=","maxAmount":"10","agentRequestId":"arId-batch-456e7890-e89b-12d3-a456-426614174000","batch":true}}}}}},"responses":{"201":{"description":"Permission settlement successful (x402 facilitator response)","schema":{"example":{"success":true,"payer":"0xD4f58B60330bC59cB0A07eE6A1A66ad64244eC8c","transaction":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","network":"eip155:84532","creditsRedeemed":"2","remainingBalance":"98"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402SettleResponseDto"}}}},"400":{"description":"Bad Request - Settlement failed","content":{"application/json":{"schema":{"example":{"success":false,"errorReason":"Credit redemption failed","payer":"0xD4f58B60330bC59cB0A07eE6A1A66ad64244eC8c","transaction":"","network":"eip155:84532"}}}}},"401":{"description":"Unauthorized - Invalid or expired X402 token","content":{"application/json":{"schema":{"example":{"code":"BCK.X402.0003","httpStatus":401,"message":"Invalid X402 Access Token","params":{"reason":"Token has expired"}}}}}}},"summary":"Settle permission usage","tags":["X402"]}},"/api/v1/x402/permissions/{permissionHash}":{"get":{"description":"Get details of a specific permission","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":{"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","orderLimit":"1000000000000000000","redemptionLimit":100,"planCost":"500000000000000000","creditsPerOrder":"1000"}}}}},"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.0008","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","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":{"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.0008","httpStatus":404,"message":"Permission not found","params":{"permissionHash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"}}}}}}},"security":[{"Authorization":[]}],"summary":"Revoke permission","tags":["X402"]}},"/.well-known/jwks.json":{"get":{"description":"Get JSON Web Key Set (JWKS) for OAuth token verification","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":"JWKS Endpoint","tags":["Well-Known"]}},"/.well-known/oauth-authorization-server":{"get":{"description":"Get OAuth 2.0 Authorization Server metadata (RFC 8414)","operationId":"WellKnownController_getOAuthAuthorizationServer","parameters":[],"responses":{"200":{"description":"Returns OAuth Authorization Server metadata","content":{"application/json":{"schema":{"type":"object","properties":{"issuer":{"type":"string"},"authorization_endpoint":{"type":"string"},"token_endpoint":{"type":"string"},"jwks_uri":{"type":"string"},"response_types_supported":{"type":"array","items":{"type":"string"}},"response_modes_supported":{"type":"array","items":{"type":"string"}},"grant_types_supported":{"type":"array","items":{"type":"string"}},"token_endpoint_auth_methods_supported":{"type":"array","items":{"type":"string"}},"scopes_supported":{"type":"array","items":{"type":"string"}},"code_challenge_methods_supported":{"type":"array","items":{"type":"string"}}}}}}}},"summary":"OAuth Authorization Server Metadata","tags":["Well-Known"]}},"/api/v1/delegation/setup-intent":{"post":{"operationId":"DelegationController_createSetupIntent","parameters":[],"responses":{"201":{"description":"SetupIntent created"}},"security":[{"Authorization":[]}],"summary":"Create a Stripe SetupIntent for saving a payment method","tags":["Delegation"]}},"/api/v1/delegation/enroll-card":{"post":{"operationId":"DelegationController_enrollCard","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrollCardDto"}}}},"responses":{"201":{"description":"Card enrollment initiated"}},"security":[{"Authorization":[]}],"summary":"Enroll a card via VGS tokenized aliases","tags":["Delegation"]}},"/api/v1/delegation/payment-methods":{"get":{"operationId":"DelegationController_listPaymentMethods","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethodSummaryDto"}}}}}},"security":[{"Authorization":[]}],"summary":"List saved payment methods for the authenticated user","tags":["Delegation"]}},"/api/v1/delegation/payment-methods/{paymentMethodId}":{"delete":{"operationId":"DelegationController_revokePaymentMethod","parameters":[{"name":"paymentMethodId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Payment method revoked"}},"security":[{"Authorization":[]}],"summary":"Revoke (detach) a payment method","tags":["Delegation"]}},"/api/v1/delegation/create":{"post":{"deprecated":true,"description":"Deprecated: Use POST /x402/permissions with scheme \"nvm:card-delegation\" instead for unified permission management.","operationId":"DelegationController_createDelegation","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDelegationDto"}}}},"responses":{"201":{"description":"Delegation created"}},"security":[{"Authorization":[]}],"summary":"Create a spending delegation and return a signed JWT token","tags":["Delegation"]}},"/api/v1/delegation":{"get":{"operationId":"DelegationController_listDelegations","parameters":[{"name":"page","required":true,"in":"query","schema":{"type":"number"}},{"name":"offset","required":true,"in":"query","schema":{"type":"number"}}],"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":{"operationId":"DelegationController_getDelegation","parameters":[{"name":"delegationId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegationDetailsDto"}}}}},"security":[{"Authorization":[]}],"summary":"Get delegation details including remaining budget","tags":["Delegation"]},"delete":{"operationId":"DelegationController_revokeDelegation","parameters":[{"name":"delegationId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Delegation revoked"}},"security":[{"Authorization":[]}],"summary":"Revoke a delegation","tags":["Delegation"]}},"/api/v1/delegation/{delegationId}/transactions":{"get":{"operationId":"DelegationController_getTransactions","parameters":[{"name":"delegationId","required":true,"in":"path","schema":{"type":"string"}},{"name":"page","required":true,"in":"query","schema":{"type":"number"}},{"name":"offset","required":true,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegationTransactionListDto"}}}}},"security":[{"Authorization":[]}],"summary":"List transactions for a delegation","tags":["Delegation"]}}},"info":{"title":"NVM BACKEND API","description":"","version":"0.1.56","contact":{}},"tags":[{"name":"Nevermined","description":"Nevermined Backend API"}],"servers":[{"url":"https://api.live.nevermined.app"}],"components":{"securitySchemes":{"Authorization":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"RegisterApiKeyFromEncryptedKeyDto":{"type":"object","properties":{"nvmKey":{"type":"string","description":"The encrypted NVM API key containing the session key","example":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0.eyJpc3Mi[...omitted for brevity...]"},"clientAssertion":{"type":"string","description":"JWT client assertion for backend authentication (RFC-7523). When provided, authenticates using the Nevermined passport strategy instead of Privy identity token.","example":"eyJhbGciOiJFUzI1NksiLCJ0eXAiOiJKV1QifQ.eyJpc3Mi[...omitted for brevity...]"}},"required":["nvmKey"]},"LoginDto":{"type":"object","properties":{"hash":{"type":"string","description":"The Hash of the Nevermined API key","example":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0.eyJpc3Mi[...omitted for brevity...]"},"userId":{"type":"string","example":"u-12345","description":"The userId identifying the user"},"userWallet":{"type":"string","example":"0x1234567890abcdef1234567890abcdef12345678","description":"Address of the user"}},"required":["hash","userId","userWallet"]},"RegisterApiKeyDto":{"type":"object","properties":{"nvmKey":{"type":"string","example":"my api key","description":"The Nevermined API Key Encrypted"},"orgId":{"type":"string","example":"org-aaa-bbb","description":"The organization id of the user creating the api key"},"name":{"type":"string","example":"my api key","description":"Name of the api key given by the user"},"isBrowser":{"type":"boolean","example":true,"default":false,"description":"Indicates if the api key is for browser usage"},"expiresAt":{"format":"date-time","type":"string","description":"Expiration date of the api key given by the user"}},"required":["nvmKey","orgId","name","isBrowser","expiresAt"]},"ApiKeyEntity":{"type":"object","properties":{}},"SearchApiKeyDto":{"type":"object","properties":{"skId":{"type":"string","example":"sk-1234567890abcdef","description":"The unique identifier of the API key"},"userId":{"type":"string","example":"us-0d725471-3d70-4982-8080-63adcd5b9765","description":"The unique identifier of the user"},"userWallet":{"type":"string","example":"0x1234567890abcdef1234567890abcdef12345678","description":"Address of the user"},"hash":{"type":"string","example":"eY......","description":"Api key hash"},"name":{"type":"string","example":"test key","description":"Name of the Api key"},"orgId":{"type":"string","example":"Acme Corp","description":"Name of the organization"},"isActive":{"type":"boolean","example":true,"default":true,"description":"Indicates if the api key is active"},"isBrowser":{"type":"boolean","example":true,"description":"Indicates if the api key is for browser usage"},"canRegister":{"type":"boolean","example":true,"description":"Indicates if the api key can register plans and agents"},"canOrder":{"type":"boolean","example":true,"description":"Indicates if the api key can order plans"},"canMint":{"type":"boolean","example":true,"description":"Indicates if the api key can mint credits of plans that belong to the user"},"canBurn":{"type":"boolean","example":true,"description":"Indicates if the api key can burn credits of plans that belong to the user"},"createdBetweenBeginning":{"format":"date-time","type":"string","description":"Filter to search between two dates, this one is the beginning"},"createdBetweenEnd":{"format":"date-time","type":"string","description":"Filter to search between two dates, this one is the end"},"page":{"type":"number","example":1,"description":"Page of the points list"},"offset":{"type":"number","example":20,"description":"Page offset of the points list"}},"required":["skId","userId","userWallet","hash","name","orgId","isActive","isBrowser","canRegister","canOrder","canMint","canBurn","createdBetweenBeginning","createdBetweenEnd","page","offset"]},"SearchApiKeyTxsDto":{"type":"object","properties":{"skId":{"type":"string","example":"sk-1234567890abcdef","description":"The unique identifier of the API key"},"userId":{"type":"string","example":"us-0d725471-3d70-4982-8080-63adcd5b9765","description":"The unique identifier of the user"},"userWallet":{"type":"string","example":"0x1234567890abcdef1234567890abcdef12345678","description":"Address of the user"},"txType":{"type":"object","example":"NewPlan","description":"Type of usage of the session key"},"result":{"type":"number","example":200,"description":"The result of the transaction"},"amount":{"type":"number","example":10,"description":"The amount of the transaction"},"createdBetweenBeginning":{"format":"date-time","type":"string","description":"Filter to search between two dates, this one is the beginning"},"createdAt":{"format":"date-time","type":"string","example":"2026-03-07T02:51:00.570Z","description":"The date when the transaction was created"},"createdBetweenEnd":{"format":"date-time","type":"string","description":"Filter to search between two dates, this one is the end"},"page":{"type":"number","example":1,"description":"Page of the points list"},"offset":{"type":"number","example":20,"description":"Page offset of the points list"}},"required":["skId","userId","userWallet","txType","result","amount","createdBetweenBeginning","createdAt","createdBetweenEnd","page","offset"]},"UpdateApiKeyNameDto":{"type":"object","properties":{"hash":{"type":"string","description":"The hash of the API key to update"},"name":{"type":"string","example":"My API Key","description":"New name for the API key","minLength":1,"maxLength":255}},"required":["hash","name"]},"AdditionalInformationDto":{"type":"object","properties":{"privyUserId":{"type":"string","example":"http://example.com/avatar.jpg","description":"Profile image url"}},"required":["privyUserId"]},"GetUserProfileDto":{"type":"object","properties":{"userId":{"type":"string","example":"jifdwqejidqwa9okdasodkaso","description":"Unique identifier of the user"},"isListed":{"type":"boolean","example":true,"description":"Flag identifying if the user is listed in the marketplace. Possible values: true or false"},"state":{"type":"object","example":"confirmed","description":"State of the user in the marketplace. Possible options: disabled, unconfirmed, confirmed"},"address":{"type":"string","example":"0x37BB53e3d293494DE59fBe1FF78500423dcFd43B","description":"The address owned by the user. Address cannot be shared between different users"},"nickname":{"type":"string","example":"john.doe","description":"The nickname of the user"},"name":{"type":"string","example":"John Doe","description":"The name of the user"},"email":{"type":"string","example":"john.doe@example.com","description":"The email of the user"},"creationDate":{"type":"string","example":"2019-01-01T19:73:24Z","description":"When the user information was created"},"updateDate":{"type":"string","example":"2019-01-01T19:73:24Z","description":"When was the last time the user information was updated"},"additionalInformation":{"description":"List of additional key-value attributes with additional information","allOf":[{"$ref":"#/components/schemas/AdditionalInformationDto"}]},"live":{"type":"object","description":"Stripe information for live environment"},"sandbox":{"type":"object","description":"Stripe information for sandbox environment"},"paymentCountry":{"type":"string","example":"US","description":"The country of the user"},"acceptedTermsAndConditions":{"type":"boolean","example":true,"description":"True if the user accepted terms and conditions."},"acceptedTermsAndConditionsDate":{"type":"string","example":"2019-01-01T19:73:24Z","description":"Date when the user accepted terms and conditions"},"paymentMethodsAccepted":{"type":"string","example":"all","description":"Payment methods accepted by the user"},"role":{"type":"string","enum":["Admin","Member"],"description":"Role of the user within an organization if the user is a member"}},"required":["userId","isListed","state","address","nickname","name","email","creationDate","updateDate","additionalInformation","paymentCountry","acceptedTermsAndConditions","acceptedTermsAndConditionsDate","paymentMethodsAccepted"]},"CreateUserProfileDto":{"type":"object","properties":{"isListed":{"type":"boolean","example":true,"description":"Flag identifying if the user is listed in the marketplace. Possible values: true or false"},"state":{"type":"object","example":"confirmed","description":"State of the user in the marketplace. Possible options: disabled, unconfirmed, confirmed"},"address":{"type":"string","example":"0x37BB53e3d293494DE59fBe1FF78500423dcFd43B","description":"The address owned by the user. Address cannot be shared between different users"},"nickname":{"type":"string","example":"john.doe","description":"The nickname of the user"},"name":{"type":"string","example":"John Doe","description":"The name of the user"},"email":{"type":"string","example":"john.doe@example.com","description":"The email of the user"},"paymentCountry":{"type":"string","example":"US","description":"The country of the user"},"additionalInformation":{"description":"List of additional key-value attributes with additional information","allOf":[{"$ref":"#/components/schemas/AdditionalInformationDto"}]}},"required":["isListed","state","address","nickname","paymentCountry"]},"UpdateUserProfileDto":{"type":"object","properties":{"isListed":{"type":"boolean","example":true,"description":"Flag identifying if the user is listed in the marketplace. Possible values: true or false"},"state":{"type":"object","example":"confirmed","description":"State of the user in the marketplace. Possible options: disabled, unconfirmed, confirmed"},"address":{"type":"string","example":"0x37BB53e3d293494DE59fBe1FF78500423dcFd43B","description":"The address owned by the user. Address cannot be shared between different users"},"eoaAddress":{"type":"string","example":"0x37BB53e3d293494DE59fBe1FF78500423dcFd43B","description":"The eoa of the address. In case that the address is an eoa will be the same that address."},"nickname":{"type":"string","example":"john.doe","description":"The nickname of the user"},"name":{"type":"string","example":"John Doe","description":"The name of the user"},"email":{"type":"string","example":"john.doe@example.com","description":"The email of the user"},"paymentCountry":{"type":"string","example":"US","description":"The country of the user"},"acceptedTermsAndConditions":{"type":"boolean","example":true,"description":"True if the user accepted terms and conditions."},"additionalInformation":{"description":"List of additional key-value attributes with additional information","allOf":[{"$ref":"#/components/schemas/AdditionalInformationDto"}]},"updateDate":{"format":"date-time","type":"string","example":"2019-01-01T19:73:24Z","description":"When was the last time the user information was updated"}},"required":["isListed","state","address","eoaAddress","nickname","name","email","paymentCountry","acceptedTermsAndConditions","additionalInformation","updateDate"]},"GenerateTokenDto":{"type":"object","properties":{}},"ErrorResponseDto":{"type":"object","properties":{}},"CreateOrganizationDto":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the organization","example":"Nevermined Labs"},"description":{"type":"string","description":"Short description of the organization","example":"AI infrastructure for knowledge agents."},"url":{"type":"string","description":"Organization public URL","example":"https://nevermined.app"},"organizationWallet":{"type":"string","description":"Wallet address for the organization","example":"0x1234567890abcdef1234567890abcdef12345678"},"cryptoFees":{"type":"string","description":"Fee percentage for crypto payments (as decimal, e.g., 0.05 for 5%)","example":"0"},"fiatFees":{"type":"string","description":"Fee percentage for fiat payments (as decimal, e.g., 0.05 for 5%)","example":"0"},"isActive":{"type":"boolean","description":"Whether the organization is active","example":true,"default":true},"orgType":{"type":"string","description":"Type of organization subscription","enum":["Free","Premium","Enterprise","Other"],"example":"Free","default":"Free"},"branding":{"type":"object","description":"Branding configuration for the organization","example":{"themeName":"default","logo":"https://example.com/logo.png"}},"live":{"type":"object","description":"Stripe configuration for live environment","example":{"accountId":"acct_1234567890","isAccountValidated":false}},"sandbox":{"type":"object","description":"Stripe configuration for sandbox environment","example":{"accountId":"acct_test_1234567890","isAccountValidated":false}}},"required":["name","organizationWallet"]},"SearchOrganizationMembersDto":{"type":"object","properties":{"role":{"type":"object","example":"Admin","description":"Role of the organization member"},"isActive":{"type":"boolean","example":true,"description":"Active status of the organization member"},"page":{"type":"number","example":1,"description":"Page of the organization members list"},"offset":{"type":"number","example":20,"description":"Page offset of the organization members list"},"environment":{"type":"string","example":"sandbox","description":"Environment to get stripe account id from (live or sandbox)","enum":["live","sandbox"]}},"required":["role","isActive","page","offset","environment"]},"UpdateOrganizationDto":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the organization","example":"Nevermined Labs"},"description":{"type":"string","description":"Short description that will be shown publicly","example":"AI infrastructure for knowledge agents."},"url":{"type":"string","description":"Organization public URL","example":"https://nevermined.app"},"isActive":{"type":"boolean","description":"Whether the organization is active. If set to false, all members will also be deactivated.","example":true},"cryptoFees":{"type":"string","description":"Fee percentage for crypto payments, multiplied by 10000 (e.g., 1500 = 15%)","example":"1500"},"fiatFees":{"type":"string","description":"Fee percentage for fiat payments, multiplied by 10000 (e.g., 1500 = 15%)","example":"1500"}}},"SaveBrandingDto":{"type":"object","properties":{}},"EmailChallengeEntity":{"type":"object","properties":{}},"ValidateEmailChallengeDto":{"type":"object","properties":{"id":{"type":"string","example":"em-abcd","description":"The email challenge id reference"},"userId":{"type":"string","example":"us-01234","description":"The unique identifier of the user associated to the email"},"email":{"type":"string","example":"john.doe@example.com","description":"The email address of the user to validate"},"challenge":{"type":"string","example":"123456","description":"The email challenge sent by email"}},"required":["id","userId","email","challenge"]},"NotificationEntity":{"type":"object","properties":{}},"SearchNotificationsDto":{"type":"object","properties":{"id":{"type":"string","example":"nid-99970808-0a86-45c0-ac7b-7917d45961a6","description":"Unique identifier of the notification"},"notificationType":{"type":"string","example":"purchase","description":"Type of notification"},"receiver":{"type":"string","example":"uid-99970808-0a86-45c0-ac7b-7917d45961a6","description":"Unique identifier of the user receiving the notification"},"originator":{"type":"string","example":"uid-99970808-0a86-45c0-ac7b-7917d45961a6","description":"Unique identifier of the user originating the notification"},"readStatus":{"type":"object","example":"Pending","description":"Read status of the notification"},"deliveryStatus":{"type":"object","example":"Pending","description":"Delivery status of the notification"},"title":{"type":"string","example":"Your subscription has been purchased","description":"Title of the notification"},"did":{"type":"string","example":"112715147946069636715282379221777166315490656636137176534659157141164168807749","description":"Identifier of the asset related to the notification"},"messageTemplate":{"type":"string","example":"abcd1234","description":"Identifier of the template used to build the message of the notification"},"deliveryRetries":{"type":"number","example":"2","description":"Number of times the notification has been retried to be delivered"},"page":{"type":"number","example":1,"description":"Page of the notifications list"},"offset":{"type":"number","example":20,"description":"Page offset of the notifications list"}},"required":["id","notificationType","receiver","originator","readStatus","deliveryStatus","title","did","messageTemplate","deliveryRetries","page","offset"]},"NvmAPIResultDto":{"type":"object","properties":{"success":{"type":"boolean","example":true,"description":"Indicates whether the API call was successful"},"message":{"type":"string","example":"Successfully minted","description":"Message describing the result of the API call"},"txHash":{"type":"string","example":"0x923812b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef12345678","description":"Blockchain transaction hash associated with the API call"},"httpStatus":{"type":"number","example":200,"description":"HTTP status code of the API response"},"data":{"type":"object","description":"Additional parameters related to the API call","additionalProperties":true},"when":{"format":"date-time","type":"string","description":"Timestamp when the API call was made"}},"required":["success","message","txHash","httpStatus","data","when"]},"CreatePaypalCheckoutDto":{"type":"object","properties":{"nonce":{"type":"string","example":"fake-valid-nonce","description":"Braintree payment method nonce for PayPal"},"planId":{"format":"int64","type":"integer","example":"43298432984329","description":"Unique identifier of the payment plan being purchased"},"returnUrlQueryParams":{"type":"object","description":"Return URL query parameters"},"nvmExport":{"type":"string","example":"true","description":"Export NVM API key","default":false},"userId":{"type":"string","example":"1234567890","description":"User ID"}},"required":["nonce","planId","returnUrlQueryParams","nvmExport","userId"]},"CreateStripeAccountDto":{"type":"object","properties":{"stripeAccountId":{"type":"string","example":"acct_1O4KfNBYvSRKcV42","description":"Unique identifier of stripe account"},"userEmail":{"type":"string","example":"john.doe@example.com","description":"User email. If given it wont be asked by Stripe account creation"},"userCountryCode":{"type":"string","example":"GB","description":"User country code (ISO 3166-1 alpha-2). It will be used by Stripe for account creation"},"returnUrl":{"type":"string","example":"https://example.com","description":"Return URL"}},"required":["stripeAccountId","userEmail","userCountryCode","returnUrl"]},"StripeAccountBalanceDto":{"type":"object","properties":{"balance":{"type":"object","description":"Account balance by currency. Each currency (USD, EUR, GBP, etc.) maps to the available balance in cents/pence","example":{"usd":15000,"eur":12500,"gbp":10000}}},"required":["balance"]},"CreateStripePaymentIntentDto":{"type":"object","properties":{"planId":{"format":"int64","type":"integer","example":"43298432984329","description":"Unique identifier of the payment plan being purchased"},"language":{"type":"string","example":"en","description":"Language of the app","default":"en"},"sessionId":{"type":"string","example":"39293121O4KfNBYvSRKcV42","description":"Unique identifier of the checkout session"},"nvmExport":{"type":"string","example":"true","description":"Export NVM API key","default":false},"returnUrlQueryParams":{"type":"object","description":"Return URL query parameters passed back after payment completion","example":{"source":"webapp","feature":"premium-plan"}},"email":{"type":"string","example":"john.doe@example.com","description":"Customer email address for Stripe payment intent"},"name":{"type":"string","example":"John Doe","description":"Customer name for Stripe payment intent"}},"required":["planId","language","sessionId","nvmExport"]},"CreateStripeSubscriptionDto":{"type":"object","properties":{"planId":{"format":"int64","type":"integer","example":"43298432984329","description":"Unique identifier of the payment plan being purchased"},"priceId":{"type":"string","example":"price_1O4KfNBYvSRKcV42ABC123","description":"Stripe price ID for the subscription plan"},"paymentMethodId":{"type":"string","example":"pm_1O4KfNBYvSRKcV42XYZ789","description":"Stripe payment method ID to use for the subscription"},"email":{"type":"string","example":"john.doe@example.com","description":"Customer email address"},"name":{"type":"string","example":"John Doe","description":"Customer name"},"sessionId":{"type":"string","example":"39293121O4KfNBYvSRKcV42","description":"Unique identifier of the checkout session"},"returnUrl":{"type":"string","example":"https://example.com/payment-success","description":"URL to redirect after subscription creation"},"language":{"type":"string","example":"en","description":"Language preference for the subscription flow","default":"en"},"returnUrlQueryParams":{"type":"object","description":"Return URL query parameters passed back after subscription creation","example":{"source":"webapp","tier":"premium"}},"nvmExport":{"type":"string","example":"true","description":"Export NVM API key","default":false}},"required":["planId"]},"PaymentIntentMetadataDto":{"type":"object","properties":{"metadata":{"type":"object","description":"PaymentIntent metadata","example":{"planId":"123456789","userId":"user_123","sessionId":"session_456","returnUrl":"https://example.com/return"}},"paymentIntentId":{"type":"string","description":"PaymentIntent ID","example":"pi_1234567890abcdef"},"status":{"type":"string","description":"PaymentIntent status","example":"succeeded","enum":["requires_payment_method","requires_confirmation","requires_action","processing","requires_capture","canceled","succeeded"]}},"required":["metadata","paymentIntentId","status"]},"DeploymentInfoDto":{"type":"object","properties":{"version":{"type":"string","example":"1.3.2","description":"Contract deployment version"},"contracts":{"type":"object","example":{"PayAsYouGoTemplate":"0x5e852077b30099106Aa65B4d329FFF9b5C9a8e7C","FixedPaymentTemplate":"0x32037D176558Eb02f6980eFA14bde14B0C61d059"},"description":"Contract addresses"}},"required":["contracts"]},"GetInfoDto":{"type":"object","properties":{"APIversion":{"type":"string","example":"1.0.4","description":"Marketplace API Version"},"docs":{"type":"string","example":"http://localhost:3100/api/v1/docs","description":"API docs url"},"provider-address":{"type":"string","example":"0x068Ed00cF0441e4829D9784fCBe7b9e26D4BD8d0","description":"Provider address"},"ecdsa-public-key":{"type":"string","example":"http://localhost:3100/api/v1/docs","description":"ecdsa public key"},"environment":{"type":"string","example":"local","description":"Environment"},"networkId":{"type":"number","example":"8453","description":"Network ID"},"networkName":{"type":"string","example":"base","description":"Network Name"},"organizationUpgradePlan":{"type":"string","example":"12345678901234567890","description":"Plan ID for upgrading to organization"},"deployment":{"description":"Contract deployment information","allOf":[{"$ref":"#/components/schemas/DeploymentInfoDto"}]}},"required":["APIversion","docs","provider-address","ecdsa-public-key","environment","networkId","networkName","deployment"]},"MetadataMainAttributesPlanDto":{"type":"object","properties":{"name":{"type":"string","example":"Premium AI Agent Access","description":"Name of the agent or payment plan (required)"},"author":{"type":"string","example":"Nevermined AI Inc.","description":"Author or creator of the agent or plan (optional)"},"license":{"type":"string","example":"MIT","description":"License type (e.g., MIT, Apache-2.0, Proprietary) (optional)"},"tags":{"example":["AI","Assistant","Personal","GPT"],"description":"Tags associated with the agent or plan for categorization and search","type":"array","items":{"type":"string"}},"dateCreated":{"type":"string","example":"2025-01-15T10:00:00Z","description":"Date of creation of the agent or plan (ISO 8601 format)"},"description":{"type":"string","example":"This plan provides access to the agent services.","description":"Description of the plan"}},"required":["name","author","license","tags"]},"PricingConfigDto":{"type":"object","properties":{"isCrypto":{"type":"boolean","example":true,"description":"Indicates whether the price is in cryptocurrency or fiat","default":true},"amounts":{"example":["1000000000000000000","200000000000000000"],"description":"The distributions of amounts to be paid for the plan. Amounts are provided as strings representing wei values and converted to BigInt internally.","type":"array","items":{"type":"string"}},"receivers":{"example":["0x731E7a35DDBB7d2b168D16824B371034f0DD0024","0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"],"description":"The distributions of receivers of the payments of the plan. Array of Ethereum addresses that will receive the payment amounts.","type":"array","items":{"type":"string"}},"tokenAddress":{"type":"string","example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","description":"if the price type is fixed price, the address of the token to be used"},"externalPriceAddress":{"type":"string","example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","description":"If the price type is smart contract price, the address of the smart contract that calculates the price"},"feeController":{"type":"string","example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","description":"The address of the fee controller contract, if any"},"templateAddress":{"type":"string","example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","description":"If is not the zero address, the Nevermined template contract address associated with the plan"}},"required":["isCrypto","amounts","receivers","tokenAddress","externalPriceAddress","feeController","templateAddress"]},"CreditsConfigDto":{"type":"object","properties":{"isRedemptionAmountFixed":{"type":"boolean","example":true,"description":"Indicates if the redemption amount is fixed (true) or dynamic (false)","default":true},"redemptionType":{"type":"object","example":1,"description":"How the credits can be redeemed","default":1},"proofRequired":{"type":"boolean","example":true,"description":"Whether the credits burn proof signed by the user is required","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","proofRequired","amount","minAmount","maxAmount","durationSecs","nftAddress"]},"RegisterPaymentPlanDto":{"type":"object","properties":{"metadataAttributes":{"description":"Metadata attributes for the payment plan (name, description, author, etc.)","allOf":[{"$ref":"#/components/schemas/MetadataMainAttributesPlanDto"}]},"priceConfig":{"description":"Definition of the price configuration for a plan","allOf":[{"$ref":"#/components/schemas/PricingConfigDto"}]},"creditsConfig":{"description":"Definition of the credits configuration for a plan","allOf":[{"$ref":"#/components/schemas/CreditsConfigDto"}]},"nonce":{"format":"int64","type":"integer","example":"3494494882712371273123737237","description":"nonce used to register the payment plan"},"isTrialPlan":{"type":"boolean","example":false,"description":"Indicates if the plan is a trial plan and only can be purchased once","default":false},"recurringSubscription":{"type":"boolean","example":false,"description":"Indicates if the plan is a recurring subscription","default":false},"accessLimit":{"type":"string","example":"credits","description":"Type of access limit for the plan","enum":["credits","time"]},"fiatPaymentProvider":{"type":"string","example":"stripe","description":"Payment provider for the plan","enum":["stripe","braintree"]},"appId":{"type":"string","example":"1","description":"The app id"}},"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":"List of endpoints available in the agent API. Each endpoint is an object with HTTP method as key and URL pattern as value. Use (.*)  for dynamic path segments."},"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":"URL of the OpenAPI definition of the agent API"},"authType":{"type":"object","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":["endpoints","openEndpoints","agentDefinitionUrl","authType","username","password","token"]},"RegisterAgentDto":{"type":"object","properties":{"metadataAttributes":{"description":"Metadata attributes for the agent (name, description, author, tags, etc.)","allOf":[{"$ref":"#/components/schemas/MetadataMainAttributesAgentDto"}]},"agentApiAttributes":{"description":"Definition of the Agent API","allOf":[{"$ref":"#/components/schemas/AgentAPIAttributesDto"}]},"plans":{"example":["43298432984329","12345678901234"],"description":"Array of payment plan IDs to associate with the agent (optional). Plan IDs are BigInt values provided as strings.","type":"array","items":{"type":"string"}}},"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"]},"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"]},"MintPlanDto":{"type":"object","properties":{"planId":{"format":"int64","type":"integer","example":"43298432984329","description":"Unique identifier of the payment plan. Provided as a string and converted to BigInt internally."},"creditsReceiver":{"type":"string","example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","description":"The Ethereum address of the account that will receive the minted credits (checksummed, 0x-prefixed)"},"amount":{"format":"int64","type":"integer","example":"150","description":"The number of credits to be minted. Provided as a string and converted to BigInt internally."}},"required":["planId","creditsReceiver","amount"]},"MintPlanExpirableDto":{"type":"object","properties":{"planId":{"format":"int64","type":"integer","example":"43298432984329","description":"Unique identifier of the payment plan. Provided as a string and converted to BigInt internally."},"creditsReceiver":{"type":"string","example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","description":"The Ethereum address of the account that will receive the minted credits (checksummed, 0x-prefixed)"},"amount":{"format":"int64","type":"integer","example":"150","description":"The number of credits to be minted. Provided as a string and converted to BigInt internally."},"duration":{"format":"int64","type":"integer","example":86400,"description":"The duration of the expirable credits in seconds (e.g., 86400 for 24 hours). Provided as a number or string and converted to BigInt internally.","default":0}},"required":["planId","creditsReceiver","amount","duration"]},"UpdateAgentDto":{"type":"object","properties":{"metadataAttributes":{"description":"Updated metadata attributes for the agent (name, description, author, tags, etc.)","allOf":[{"$ref":"#/components/schemas/MetadataMainAttributesAgentDto"}]},"agentApiAttributes":{"description":"Updated API configuration for the agent (endpoints, authentication, OpenAPI definition URL)","allOf":[{"$ref":"#/components/schemas/AgentAPIAttributesDto"}]}},"required":["metadataAttributes","agentApiAttributes"]},"PaymentPlanDto":{"type":"object","properties":{"planId":{"format":"int64","type":"integer","example":"43298432984329","description":"Unique identifier of the payment plan"},"owner":{"type":"string","example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","description":"The owner of the payment plan"},"priceConfig":{"description":"Definition of the price configuration for a plan","allOf":[{"$ref":"#/components/schemas/PricingConfigDto"}]},"creditsConfig":{"description":"Definition of the credits configuration for a plan","allOf":[{"$ref":"#/components/schemas/CreditsConfigDto"}]},"creditsNftAddress":{"type":"string","example":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","description":"The address of the contract that will be used to store the credits"},"lastUpdated":{"format":"date-time","type":"string","example":"2025-01-15T14:30:00Z","description":"When was the last time the plan was updated (ISO 8601 format)"}},"required":["planId","owner","priceConfig","creditsConfig","creditsNftAddress","lastUpdated"]},"PaginatedPaymentPlansDto":{"type":"object","properties":{"total":{"type":"number","description":"Total number of payment plans matching the query","example":42},"page":{"type":"number","description":"Current page number (0-indexed)","example":0},"offset":{"type":"number","description":"Number of items skipped","example":0},"plans":{"description":"Array of payment plan objects for the current page","type":"array","items":{"$ref":"#/components/schemas/PaymentPlanDto"}}},"required":["total","page","offset","plans"]},"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":"object","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":"object","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":"object","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":"object","example":0.2,"description":"The margin percentage to apply. This percentage will be applied to the actual cost of the request."},"batch":{"type":"object","example":true,"description":"Whether the request is a batch request"}},"required":["agentRequestId"]},"RequestProperties":{"type":"object","properties":{"model":{"type":"string","example":"gpt-3.5-turbo-0125","description":"Request model name"},"provider":{"type":"string","example":"OPENAI","description":"AI provider name"},"promptTokens":{"type":"string","example":"34","description":"Prompt tokens used"},"completionTokens":{"type":"string","example":"16","description":"Completion tokens used"},"totalTokens":{"type":"string","example":"50","description":"Total tokens used"},"inputCost":{"type":"number","example":0.000041,"description":"Cost of the request"},"outputCost":{"type":"number","example":0.000041,"description":"Cost of the request"},"latency":{"type":"number","example":1065,"description":"Request delay in milliseconds"},"isMarginBased":{"type":"boolean","example":true,"description":"Whether request is margin based"},"marginPercent":{"type":"number","example":0.02,"description":"The percentage of the request that is margin"}},"required":["model","provider","promptTokens","completionTokens","totalTokens","inputCost","outputCost","latency","isMarginBased","marginPercent"]},"RequestDto":{"type":"object","properties":{"createdAt":{"type":"string","example":"2021-02-01T10:55:11Z","description":"Date when the request was made"},"requestId":{"type":"string","example":"arId-f7a775d9-42ef-43c4-87b7-6051497f667b","description":"Agent request ID"},"customerName":{"type":"string","example":"0xb3381Dd920a4D1FEDD067E05b15Bf52d328AF912","description":"Customer name. For now it is the customer address"},"agentName":{"type":"string","example":"Financial Advisor","description":"The name of the agent"},"planName":{"type":"string","example":"Basic Plan","description":"The name of the plan"},"totalCost":{"type":"number","example":100,"description":"The total cost of the request"},"creditAmount":{"type":"number","example":100,"description":"The amount of credits used"},"requestPrice":{"type":"number","example":100,"description":"The price of the request"},"batch":{"type":"boolean","example":true,"description":"Whether the request is a batch request"},"pnl":{"type":"number","example":1.23,"description":"The PNL of the request"},"completedAt":{"type":"string","example":"2021-02-01T10:55:11Z","description":"Date when the request was completed"},"customerId":{"type":"string","example":"0xb3381Dd920a4D1FEDD067E05b15Bf52d328AF912","description":"Customer ID. For now it is the customer address"},"agentId":{"type":"string","example":"112715147946069636715282379221777166315490656636137176534659157141164168807749","description":"The ID of the agent"},"planId":{"type":"string","example":"6072893147918618836991510631432710862057010729602249220531461142018256888522","description":"The ID of the plan"},"planType":{"type":"string","example":"credits","description":"The type of the plan"},"status":{"type":"string","example":"Success","description":"Request status - Success or Failed","enum":["Success","Failed"]},"signedBodyUrl":{"type":"string","example":"https://minio.helicone.nevermined.dev/helm-request-response-storage/organizations/4fe3c803-a27d-455d-b6f6-bd8627f033e9/requests/e3b6308c-a1e5-4e64-b48a-abf12e9c1951/request_response_body?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=minioadmin%2F20250922%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20250922T121419Z&X-Amz-Expires=86400&X-Amz-Signature=e45f44556f459ea90d962a0c3d6e6500b01a28acce889b8cc9160d51a4139ea28d&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject","description":"The signed body URL"},"properties":{"description":"Request properties including model, provider, tokens, and costs","allOf":[{"$ref":"#/components/schemas/RequestProperties"}]}},"required":["createdAt","requestId","customerName","agentName","planName","totalCost","creditAmount","requestPrice","batch","pnl","completedAt","customerId","agentId","planId","planType","status","signedBodyUrl","properties"]},"PaginatedRequestsDto":{"type":"object","properties":{"total":{"type":"number","example":156,"description":"Total number of requests across all pages"},"page":{"type":"number","example":1,"description":"Current page number"},"offset":{"type":"number","example":10,"description":"Number of items per page"},"requests":{"description":"Array of request objects","type":"array","items":{"$ref":"#/components/schemas/RequestDto"}},"filters":{"type":"object","description":"Available filter options","example":{"planNames":["Financial Agent Plan","Premium Plan"],"agentNames":["Financial Agent","Customer Support Agent"],"customerNames":["0xb3381Dd920a4D1FEDD067E05b15Bf52d328AF912"]}}},"required":["total","page","offset","requests","filters"]},"SearchPlanTransactionsDto":{"type":"object","properties":{"txId":{"type":"string","example":"tid-8fd70808-0a86-45c0-ac7b-7917d45961a6","description":"Identifier of the transaction in the database"},"planId":{"type":"string","example":"93821938219382198329183921312","description":"PlanId the transaction is about"},"planOwner":{"type":"string","example":"0xb6c82652E91B8bd90E68b9F8F4E33Bac1716AEC7","description":"Address of the owner of the plan"},"planOwners":{"example":["0xb6c82652E91B8bd90E68b9F8F4E33Bac1716AEC7","0x73C5D5cF8482ae5631ac18E6C67B690f1f1E6167"],"description":"List of addresses of plan owners to filter by","type":"array","items":{"type":"string"}},"planConsumer":{"type":"string","example":"0x73C5D5cF8482ae5631ac18E6C67B690f1f1E6167","description":"Address of the consumer of the plan"},"txType":{"type":"object","example":"Mint","description":"Type of plan transaction"},"minPrice":{"format":"int64","type":"integer","example":"3.50","description":"Min price of the plan"},"maxPrice":{"format":"int64","type":"integer","example":"150.99","description":"Max price of the plan"},"currency":{"type":"string","example":"USD","description":"Currency"},"paymentType":{"type":"object","example":"Crypto","description":"Payment type"},"txHash":{"type":"string","example":"0x0e826d720490480fdd4ecc6890a01bee0593a8808153c51f3a6d4c352496901f","description":"Blockchain transaction hash"},"page":{"type":"number","example":1,"description":"Page of the plan transaction list"},"offset":{"type":"number","example":20,"description":"Page offset of the plan transaction list"},"order":{"type":"object","example":"DESC","description":"Order by. DESC to have more recent first or ASC to older first. Default is DESC"},"time":{"type":"string","example":"24h","description":"Time filter for transactions"}},"required":["txId","planId","planOwner","planConsumer","txType","minPrice","maxPrice","currency","paymentType","txHash","page","offset","order","time"]},"PlanCreditsInfo":{"type":"object","properties":{"isRedemptionAmountFixed":{"type":"boolean","description":"Indicates if the redemption amount is fixed (true) or dynamic (false)","example":true},"consumptionInfo":{"type":"number","description":"For EXPIRABLE plans: percentage consumed (0-100). For FIXED/DYNAMIC: remaining credits","example":25.5},"isExpired":{"type":"boolean","description":"For EXPIRABLE plans: true if expired, false otherwise. For FIXED/DYNAMIC: true if no credits left","example":false},"currentBalance":{"type":"string","description":"Current credits balance","example":"75"},"totalCredits":{"type":"string","description":"Total credits originally granted","example":"100"},"purchaseDate":{"type":"string","description":"Purchase date for expirable plans","example":"2024-01-15T10:30:00Z"},"durationSecs":{"type":"number","description":"Duration in seconds for expirable plans","example":2592000}},"required":["isRedemptionAmountFixed","consumptionInfo","isExpired","currentBalance","totalCredits","purchaseDate","durationSecs"]},"PlanTransactionEntity":{"type":"object","properties":{}},"PlanPurchasedDetailedItem":{"type":"object","properties":{"plan":{"type":"object","description":"Plan detailed information"},"agents":{"description":"Agents associated to this plan","type":"array","items":{"type":"string"}},"creditsInfo":{"description":"Credits consumption information","allOf":[{"$ref":"#/components/schemas/PlanCreditsInfo"}]},"transactions":{"description":"List of transactions for this plan","type":"array","items":{"$ref":"#/components/schemas/PlanTransactionEntity"}}},"required":["plan","agents","creditsInfo","transactions"]},"PlanPurchasedDetailedDto":{"type":"object","properties":{"page":{"type":"number","example":1,"description":"Page of the plan transaction list"},"totalPages":{"type":"number","example":1,"description":"Total number of pages"},"totalResults":{"type":"number","example":137,"description":"Total number of results found"},"results":{"description":"List of transactions with detailed plan and agent information","type":"array","items":{"$ref":"#/components/schemas/PlanPurchasedDetailedItem"}}},"required":["page","totalPages","totalResults","results"]},"NvmConfigVersionsDto":{"type":"object","properties":{"id":{"type":"number","example":"1","description":"The id of the revision"},"updated":{"type":"string","example":"2020-01-01T19:13:24Z","description":"The date of the revision"},"checksum":{"type":"string","example":"89328493849328493284932","description":"The checksum of the revision"}},"required":["id","updated","checksum"]},"NvmConfigDto":{"type":"object","properties":{"userId":{"type":"string","example":"u-12345","description":"The userId who created the asset"},"appId":{"type":"string","example":"12345","description":"The application id that created the asset"},"versions":{"example":"12345","description":"The application id that created the asset","type":"array","items":{"$ref":"#/components/schemas/NvmConfigVersionsDto"}}}},"MetadataDto":{"type":"object","properties":{}},"Plan":{"type":"object","properties":{}},"GetPlanDto":{"type":"object","properties":{"@context":{"type":"string","example":"https://w3id.org/did/v1","description":"Context of the asset"},"_nvm":{"description":"Nevermined config section","allOf":[{"$ref":"#/components/schemas/NvmConfigDto"}]},"created":{"type":"string","example":"2021-02-01T10:55:11Z","description":"Date when the asset is created"},"updated":{"type":"string","example":"2021-02-01T10:55:11Z","description":"Date when the asset is created"},"id":{"type":"string","example":"112715147946069636715282379221777166315490656636137176534659157141164168807749","description":"ID of the asset"},"metadata":{"description":"Metadata that contains the asset","allOf":[{"$ref":"#/components/schemas/MetadataDto"}]},"registry":{"description":"The object representing the on-chain registry of the asset","allOf":[{"$ref":"#/components/schemas/Plan"}]}},"required":["@context","_nvm","created","updated","id","metadata"]},"GetRankingDto":{"type":"object","properties":{"mostPopularPlan":{"description":"Get the most claimed plan","allOf":[{"$ref":"#/components/schemas/GetPlanDto"}]},"lastPlanCreated":{"description":"Get the last asset created","allOf":[{"$ref":"#/components/schemas/GetPlanDto"}]},"lastTransaction":{"type":"object","description":"Get the last transaction"}},"required":["mostPopularPlan","lastPlanCreated","lastTransaction"]},"DashboardMetricsResponseDto":{"type":"object","properties":{"activeUsers":{"type":"number","description":"Number of unique active users","example":1213},"activeUsersVariation":{"type":"string","description":"Percentage variation of active users compared to previous period","example":"15.25"},"totalApiCalls":{"type":"number","description":"Total number of API calls","example":5847},"totalApiCallsVariation":{"type":"string","description":"Percentage variation of API calls compared to previous period","example":"-8.50"},"usdRevenue":{"type":"number","description":"Total revenue in USD/USDC currencies","example":1250.5},"otherCurrencies":{"type":"object","description":"Revenue grouped by other currencies","example":{"ETH":2.5,"BTC":0.1}},"revenueVariation":{"type":"string","description":"Percentage variation of USD/USDC revenue compared to previous period","example":"22.75"}},"required":["activeUsers","activeUsersVariation","totalApiCalls","totalApiCallsVariation","usdRevenue","otherCurrencies","revenueVariation"]},"MetadataFileDto":{"type":"object","properties":{"title":{"type":"string","example":"My avatar","description":"File title"},"description":{"type":"string","example":"The avatar of my profile","description":"Description of the file"},"author":{"type":"string","example":"Heroquest","description":"File owner"},"category":{"type":"string","example":"sales","description":"Category of the file"}},"required":["title","description","author","category"]},"CreateFileUrlDto":{"type":"object","properties":{"url":{"type":"string","example":"http://localhost:3000/cover/2493939919391293567/2493939919391293567.jpg","description":"url generated where the file will host"},"ugcId":{"type":"string","example":"2493939919391293567","description":"ugc id of the files"}},"required":["url","ugcId"]},"AuthorizeRequestDto":{"type":"object","properties":{"client_id":{"type":"string","example":"agent-123","description":"Client ID (contains agent_id value - MCP Server identifier)"},"resource":{"type":"string","example":"https://mcp-server.example.com","description":"MCP Server URI (resource identifier)"},"redirect_uri":{"type":"string","example":"cursor://oauth/callback","description":"Redirect URI where the authorization code will be sent"},"code_challenge":{"type":"string","example":"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM","description":"PKCE code challenge (base64url encoded SHA256 hash)"},"code_challenge_method":{"type":"string","example":"S256","description":"PKCE code challenge method","enum":["S256"],"default":"S256"},"state":{"type":"string","example":"xyz","description":"State parameter for CSRF protection"},"plan_id":{"type":"string","example":"plan-456","description":"Payment plan ID to use (optional, will use first available if not provided)"}},"required":["client_id","redirect_uri","code_challenge","code_challenge_method"]},"AuthorizeResponseDto":{"type":"object","properties":{"code":{"type":"string","example":"abc123...","description":"Authorization code to be exchanged for access token"}},"required":["code"]},"TokenRequestDto":{"type":"object","properties":{"grant_type":{"type":"string","example":"authorization_code","description":"Grant type","enum":["authorization_code"]},"code":{"type":"string","example":"abc123...","description":"Authorization code received from /oauth/authorize"},"redirect_uri":{"type":"string","example":"cursor://oauth/callback","description":"Redirect URI (must match the one used in authorization request)"},"client_id":{"type":"string","example":"agent-123","description":"Client ID (MCP Server identifier - same value used in authorization request)"},"code_verifier":{"type":"string","example":"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk","description":"PKCE code verifier (original random string)"},"resource":{"type":"string","example":"https://mcp-server.example.com","description":"MCP Server URI (resource identifier)"}},"required":["grant_type","code","redirect_uri","client_id","code_verifier"]},"TokenResponseDto":{"type":"object","properties":{"access_token":{"type":"string","example":"eyJhbGciOiJFUzI1NksifQ...","description":"Access token (JWT)"},"token_type":{"type":"string","example":"Bearer","description":"Token type","enum":["Bearer"],"default":"Bearer"},"expires_in":{"type":"number","example":3600,"description":"Token expiration time in seconds"},"scope":{"type":"string","example":"calendar contacts","description":"Scope of the access token"}},"required":["access_token","token_type","expires_in"]},"X402ResourceDto":{"type":"object","properties":{"url":{"type":"string","description":"URL of the protected resource/endpoint","example":"/api/v1/agents/80918427023170428029540261117198154464497879145267720259488529685089104529015/tasks"},"description":{"type":"string","description":"Description of the resource","example":"AI agent task execution"},"mimeType":{"type":"string","description":"Expected response MIME type","example":"application/json"}},"required":["url"]},"X402SchemeExtraDto":{"type":"object","properties":{"version":{"type":"string","description":"Scheme version","example":"1"},"agentId":{"type":"string","description":"Agent ID for endpoint validation","example":"80918427023170428029540261117198154464497879145267720259488529685089104529015"},"httpVerb":{"type":"string","description":"HTTP verb for endpoint validation","example":"POST"}}},"X402SchemeDto":{"type":"object","properties":{"scheme":{"type":"string","description":"Payment scheme identifier","example":"nvm:erc4337"},"network":{"type":"string","description":"Network in CAIP-2 format","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"]},"SessionKeyConfigDto":{"type":"object","properties":{"redemptionLimit":{"type":"number","description":"Maximum number of redemptions allowed","example":100},"orderLimit":{"format":"int64","type":"integer","description":"Maximum spend limit in token units (wei) for ordering","example":"1000000000000000000"},"expiration":{"format":"date-time","type":"string","description":"Expiration date for the permission (ISO 8601 format)","example":"2025-12-31T23:59:59Z"}}},"DelegationConfigDto":{"type":"object","properties":{"providerPaymentMethodId":{"type":"string","description":"Stripe payment method ID (from SetupIntent confirmation)","example":"pm_1Abc2Def3Ghi4Jkl"},"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 (ISO 4217 lowercase)","example":"usd","default":"usd"},"merchantAccountId":{"type":"string","description":"Optional merchant Stripe account ID for Connect routing","example":"acct_1Abc2Def3Ghi"},"maxTransactions":{"type":"number","description":"Maximum number of transactions allowed (null = unlimited)","example":50}},"required":["providerPaymentMethodId","spendingLimitCents","durationSecs"]},"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"}]},"sessionKeyConfig":{"description":"Session key configuration options (nvm:erc4337 scheme only)","allOf":[{"$ref":"#/components/schemas/SessionKeyConfigDto"}]},"delegationConfig":{"description":"Card delegation configuration (nvm:card-delegation scheme only)","allOf":[{"$ref":"#/components/schemas/DelegationConfigDto"}]}},"required":["accepted"]},"X402PaymentRequiredDto":{"type":"object","properties":{"x402Version":{"type":"number","description":"x402 protocol version","example":2},"error":{"type":"string","description":"Human-readable error message","example":"Payment required to access resource"},"resource":{"description":"Protected resource information","allOf":[{"$ref":"#/components/schemas/X402ResourceDto"}]},"accepts":{"description":"Array of accepted payment schemes","type":"array","items":{"$ref":"#/components/schemas/X402SchemeDto"}},"extensions":{"type":"object","description":"Extensions object (empty for nvm:erc4337)","example":{}}},"required":["x402Version","resource","accepts","extensions"]},"SettlePermissionsDto":{"type":"object","properties":{"paymentRequired":{"description":"The server's 402 PaymentRequired response. The facilitator validates that the accepted payment method in the token matches one of the accepts in this object.","allOf":[{"$ref":"#/components/schemas/X402PaymentRequiredDto"}]},"x402AccessToken":{"type":"string","description":"The x402 payment payload (base64-encoded). Contains all required fields: planId, subscriberAddress, agentId, endpoint, httpVerb. Alias: paymentPayload","example":"eyJ4NDAyVmVyc2lvbiI6MiwicmVzb3VyY2UiOnsidXJsIjoiaHR0cHM6Ly9teWFnZW50LmFpL2FwaS92MS90YXNrcyJ9LCJhY2NlcHRlZCI6eyJzY2hlbWUiOiJudm06ZXJjNDMzNyIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MzIiLCJwbGFuSWQiOiI0NDc0Mjc2MzA3NjA0NzQ5NzY0MDA4MDIzMDIzNjc4MTQ3NDEyOTk3MDk5MjcyNzg5NjU5Mzg2MTk5NzM0NzEzNTYxMzEzNTU3MTA3MSIsImV4dHJhIjp7InZlcnNpb24iOiIxIiwiYWdlbnRJZCI6IjgwOTE4NDI3MDIzMTcwNDI4MDI5NTQwMjYxMTE3MTk4MTU0NDY0NDk3ODc5MTQ1MjY3NzIwMjU5NDg4NTI5Njg1MDg5MTA0NTI5MDE1IiwiaHR0cFZlcmIiOiJQT1NUIn19LCJwYXlsb2FkIjp7InNpZ25hdHVyZSI6IjB4MTIzNCIsImF1dGhvcml6YXRpb24iOnsiZnJvbSI6IjB4ZjM5RmQ2ZTUxYWFkODhGNkY0Y2U2YUI4ODI3Mjc5Y2ZmRmI5MjI2NiIsInNlc3Npb25LZXlzUHJvdmlkZXIiOiJ6ZXJvZGV2Iiwic2Vzc2lvbktleXMiOltdfX0sImV4dGVuc2lvbnMiOnt9fQ=="},"maxAmount":{"format":"int64","type":"integer","description":"Maximum amount of credits needed to redeem during settlement","example":"2"},"agentRequestId":{"type":"string","example":"arId-123e4567-e89b-12d3-a456-426614174000","description":"Agent request ID for observability tracking. Returned by verify endpoint."},"batch":{"type":"boolean","example":true,"description":"Whether this is a batch request (multiple LLM calls under one agentRequestId)"},"marginPercent":{"type":"number","example":0.2,"description":"Margin percentage (0-10) for credit calculation. Mutually exclusive with maxAmount when agentRequestId provided."}},"required":["paymentRequired","x402AccessToken"]},"X402VerifyResponseDto":{"type":"object","properties":{"isValid":{"type":"boolean","description":"Whether the payment authorization is valid","example":true},"invalidReason":{"type":"string","description":"Reason for invalidity (only present if isValid is false)","example":"Insufficient balance"},"payer":{"type":"string","description":"Address of the payer's wallet","example":"0xD4f58B60330bC59cB0A07eE6A1A66ad64244eC8c"},"network":{"type":"string","description":"Network identifier (e.g. CAIP-2 chain ID or payment provider)","example":"eip155:84532"},"agentRequestId":{"type":"string","description":"Agent request ID for observability tracking (Nevermined extension)","example":"arId-123e4567-e89b-12d3-a456-426614174000"},"urlMatching":{"type":"string","description":"URL pattern that matched the endpoint (only present when endpoint validation is performed)","example":"/api/v1/agents/:agentId/tasks"},"agentRequest":{"type":"object","description":"Agent request context for observability (Nevermined extension)","example":{"agentRequestId":"arId-123e4567-e89b-12d3-a456-426614174000","agentName":"AI Assistant Agent","agentId":"80918427023170428029540261117198154464497879145267720259488529685089104529015","balance":{"planId":"44742763076047497640080230236781474129970992727896593861997347135613135571071","planName":"Premium AI Access","planType":"credits","holderAddress":"0xD4f58B60330bC59cB0A07eE6A1A66ad64244eC8c","balance":"98","creditsContract":"0x1234567890abcdef1234567890abcdef12345678","isSubscriber":true,"pricePerCredit":0.001},"urlMatching":"/api/v1/agents/:agentId/tasks","verbMatching":"POST","batch":false}}},"required":["isValid"]},"X402SettleResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether settlement was successful","example":true},"errorReason":{"type":"string","description":"Reason for settlement failure (only present if success is false)","example":"UserOperation reverted"},"payer":{"type":"string","description":"Address of the payer's wallet","example":"0xD4f58B60330bC59cB0A07eE6A1A66ad64244eC8c"},"transaction":{"type":"string","description":"Blockchain transaction hash (not present if settlement failed before a transaction)","example":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"},"network":{"type":"string","description":"Blockchain network identifier in CAIP-2 format","example":"eip155:84532"},"creditsRedeemed":{"type":"string","description":"Number of credits redeemed (Nevermined extension)","example":"2"},"remainingBalance":{"type":"string","description":"Subscriber's remaining balance (Nevermined extension)","example":"98"},"orderTx":{"type":"string","description":"Transaction hash of the order operation if auto top-up occurred (Nevermined extension)","example":"0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"}},"required":["success","network"]},"EnrollCardDto":{"type":"object","properties":{"vgsCardNumber":{"type":"string","description":"VGS alias for the card number (tokenized by VGS Collect)","example":"tok_sandbox_abc123"},"vgsExpDate":{"type":"string","description":"VGS alias for the card expiration date (tokenized by VGS Collect)","example":"tok_sandbox_exp456"},"vgsCvc":{"type":"string","description":"VGS alias for the card CVC (tokenized by VGS Collect)","example":"tok_sandbox_cvc789"},"alias":{"type":"string","description":"Optional friendly name for the card","example":"My Card"}},"required":["vgsCardNumber","vgsExpDate","vgsCvc"]},"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":"number","example":12},"expYear":{"type":"number","example":2027},"alias":{"type":"object","example":"My Card","nullable":true},"status":{"type":"string","example":"Active","enum":["Active","Revoked"]}},"required":["id","type","last4","brand","expMonth","expYear","alias","status"]},"CreateDelegationDto":{"type":"object","properties":{"providerPaymentMethodId":{"type":"string","description":"Stripe payment method ID (from SetupIntent confirmation)","example":"pm_1Abc2Def3Ghi4Jkl"},"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 (ISO 4217 lowercase)","example":"usd","default":"usd"},"planId":{"type":"string","description":"Optional plan ID to restrict this delegation to","example":"123456789"},"merchantAccountId":{"type":"string","description":"Optional merchant Stripe account ID to restrict payments to","example":"acct_1Abc2Def3Ghi"},"maxTransactions":{"type":"number","description":"Maximum number of transactions allowed (null = unlimited)","example":50}},"required":["providerPaymentMethodId","spendingLimitCents","durationSecs"]},"DelegationSummaryDto":{"type":"object","properties":{"delegationId":{"type":"string","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"provider":{"type":"string","example":"stripe"},"providerPaymentMethodId":{"type":"string","example":"pm_1Abc2Def3Ghi4Jkl"},"status":{"type":"string","example":"Active","enum":["Active","Revoked","Expired","Exhausted"]},"spendingLimitCents":{"type":"string","example":"10000"},"amountSpentCents":{"type":"string","example":"2500"},"remainingBudgetCents":{"type":"string","example":"7500"},"currency":{"type":"string","example":"usd"},"transactionCount":{"type":"number","example":12},"expiresAt":{"format":"date-time","type":"string","example":"2026-02-20T00:00:00Z"},"createdAt":{"format":"date-time","type":"string","example":"2026-02-13T10:30:00Z"}},"required":["delegationId","provider","providerPaymentMethodId","status","spendingLimitCents","amountSpentCents","remainingBudgetCents","currency","transactionCount","expiresAt","createdAt"]},"DelegationListDto":{"type":"object","properties":{"totalResults":{"type":"number"},"page":{"type":"number"},"offset":{"type":"number"},"delegations":{"type":"array","items":{"$ref":"#/components/schemas/DelegationSummaryDto"}}},"required":["totalResults","page","offset","delegations"]},"DelegationDetailsDto":{"type":"object","properties":{"delegationId":{"type":"string","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"provider":{"type":"string","example":"stripe"},"providerPaymentMethodId":{"type":"string","example":"pm_1Abc2Def3Ghi4Jkl"},"status":{"type":"string","example":"Active","enum":["Active","Revoked","Expired","Exhausted"]},"spendingLimitCents":{"type":"string","example":"10000"},"amountSpentCents":{"type":"string","example":"2500"},"remainingBudgetCents":{"type":"string","example":"7500"},"currency":{"type":"string","example":"usd"},"transactionCount":{"type":"number","example":12},"expiresAt":{"format":"date-time","type":"string","example":"2026-02-20T00:00:00Z"},"createdAt":{"format":"date-time","type":"string","example":"2026-02-13T10:30:00Z"},"planId":{"type":"object","example":"123456789","nullable":true},"merchantAccountId":{"type":"object","example":"acct_1Abc2Def3Ghi","nullable":true},"maxTransactions":{"type":"object","example":50,"nullable":true},"lastUsedAt":{"type":"object","example":"2026-02-13T14:00:00Z","nullable":true}},"required":["delegationId","provider","providerPaymentMethodId","status","spendingLimitCents","amountSpentCents","remainingBudgetCents","currency","transactionCount","expiresAt","createdAt","planId","merchantAccountId","maxTransactions","lastUsedAt"]},"DelegationTransactionDto":{"type":"object","properties":{"id":{"type":"string","example":"tx-uuid"},"providerTransactionId":{"type":"string","example":"pi_1Abc2Def3Ghi4Jkl"},"amountCents":{"type":"string","example":"1000"},"currency":{"type":"string","example":"usd"},"status":{"type":"string","example":"succeeded"},"failureReason":{"type":"object","example":null,"nullable":true},"createdAt":{"format":"date-time","type":"string","example":"2026-02-13T14:00:00Z"}},"required":["id","providerTransactionId","amountCents","currency","status","failureReason","createdAt"]},"DelegationTransactionListDto":{"type":"object","properties":{"totalResults":{"type":"number"},"page":{"type":"number"},"offset":{"type":"number"},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/DelegationTransactionDto"}}},"required":["totalResults","page","offset","transactions"]}}}}