AI Agents: Buy Access Autonomously - Nevermined Documentation

This is the end-to-end path for an autonomous AI agent — Claude Code, an OpenAI agent, or your own — to discover a Nevermined-monetized service and pay for it on its own. A human is needed only twice, and only the first time: to create an API key, and (for card payments) to enroll a card. Everything after that is programmatic and reusable.

Always pay through the x402 flow (verify → settle). Never call Stripe or any other payment processor directly. x402 is the only supported payment path, and it works the same whether you pay with a card or with stablecoins.

What you’ll do

1. Discover

Read an organization’s agent-discoverable instructions to learn its plans, agents, and which environment you’re in.

2. Log in

Get a Nevermined API Key (one-time, human), then store and reuse it.

3. Get a payment method

Use the stablecoin method created for you, or enroll a card via the embedded flow.

4. Delegate & buy

Authorize a spending budget, then buy plan credits with x402.

Sandbox vs. Live

Nevermined runs two environments. Develop against Sandbox, then switch to Live.

Environment	Money	API base URL	Web app
Sandbox	Test only — no real charges	`https://api.sandbox.nevermined.app/api/v1`	nevermined.app
Live	Real charges	`https://api.live.nevermined.app/api/v1`	nevermined.app

API keys are environment-specific: Sandbox keys start with sandbox:, Live keys with live:. Use the key that matches the environment you’re calling.

The flow

Discover what an organization sells

Every organization exposes two agent-discoverable files. Start here — they tell you the plans, the agents, and which environment you’re in:

GET {API_BASE}/organizations/{orgId}/agentic-instructions.md — human/agent-readable instructions, including an Environment block (the exact API base URL to use) and a How to purchase section.
GET {API_BASE}/organizations/{orgId}/llms.txt — a compact index of plans, agents, and reference links.

Both are plain text and need no authentication. Use the API base URL printed in the Environment block for every later call, and grab the per-environment OpenAPI reference at {API_BASE}/rest/docs-json (human-browsable UI at {API_BASE}/rest/docs).

Get a Nevermined API Key (one-time, needs a human)

You can’t mint the first key yourself — a human creates it in the web app. Ask them to follow Get Your API Key: sign in at nevermined.app, open Settings → Global NVM API Keys, create a key for the right environment, and hand it back to you.Store it and reuse it — you don’t need a new key per request. Keep it in an environment variable and initialize the SDK once:

TypeScript
Python

import { Payments } from '@nevermined-io/payments'

const payments = Payments.getInstance({
  nvmApiKey: process.env.NVM_API_KEY, // "sandbox:..." or "live:..."
  environment: 'sandbox',
})

import os
from payments_py import Payments, PaymentOptions

payments = Payments.get_instance(
    PaymentOptions(
        nvm_api_key=os.environ["NVM_API_KEY"],  # "sandbox:..." or "live:..."
        environment="sandbox",
    )
)

Send the key as Authorization: Bearer <api-key> if you’re calling the REST API directly instead of the SDK.

Pick how you'll pay

List the payment methods available to your account:

GET {API_BASE}/payment-methods
Authorization: Bearer <api-key>

Stablecoin (no human needed): your account’s smart-account wallet — an ERC-4337 wallet provisioned for you — appears here as a Crypto Wallet payment method. Fund it and you can pay right away, no enrollment required: skip to the last step.
Card (one-time human enrollment): enroll a credit or debit card through a supported provider — Stripe, Braintree, or Visa Intelligent Commerce. Which providers apply depends on the plan, and enrolling is a one-time human step via the embedded flow in the next step.

Enroll a card and delegate a budget (embedded flow, no CLI)

To pay by card, a human enrolls one once and grants you a delegation — a spending budget with a hard limit and expiry. Drive it with the embedded redirect handshake (no CLI, any language):

Mint a session with your API key:

POST {API_BASE}/widgets/session/self
Authorization: Bearer <api-key>
Content-Type: application/json

{ "orgId": "<your-org-id>", "returnUrl": "http://127.0.0.1:<port>/callback" }

The response carries a sessionToken. The self-mint flow only accepts a localhost returnUrl, so run a tiny one-shot callback server on 127.0.0.1 first.

Hand the human a URL to complete card setup in their browser:

https://embed.nevermined.app/cards/setup
  ?sessionToken=<sessionToken>
  &returnUrl=http://127.0.0.1:<port>/callback
  &state=<random-nonce>
  &provider=stripe

Receive the result. When they finish, the browser redirects to your returnUrl with paymentMethodId and delegationId. Verify the state echo, then store the delegationId.

Full handshake (callback server, state/CSRF, returnUrl rules) and the alternatives — embedding the widget in your own page, or enrolling directly in the app — are in Card Delegation and Card Enrollment.

If you can’t host a localhost callback, ask the human to enroll a card and create a delegation directly at nevermined.app (Payment Methods → Enroll card → Delegate), then continue.

Pay with x402

Mint an x402 access token for the plan, then send it in the payment-signature header. Each plan uses one of two schemes, and you tell the SDK which budget to charge through delegationConfig:

nvm:card-delegation (your delegated card) — pass scheme: 'nvm:card-delegation' and the delegationId you stored during enrollment. Braintree and Visa cards also need a matching network ('braintree' / 'visa'); Stripe is the default.
nvm:erc4337 (stablecoins) — the default scheme, so you can omit scheme. Create a delegation inline from a spendingLimitCents + durationSecs budget, or reuse one by delegationId.

Either way the token charges through the verify → settle flow.

TypeScript
Python

// Card (nvm:card-delegation): reuse the delegation you created during enrollment.
const { accessToken } = await payments.x402.getX402AccessToken(planId, agentId, {
  scheme: 'nvm:card-delegation',
  delegationConfig: { delegationId },
})

// Stablecoin (nvm:erc4337, the default scheme): create a delegation inline
// from a budget — max spend in cents + lifetime in seconds.
// const { accessToken } = await payments.x402.getX402AccessToken(planId, agentId, {
//   delegationConfig: { spendingLimitCents: 10000, durationSecs: 604800 }, // $100 / 7 days
// })

// Call the paid agent — x402 endpoints read the token from the payment-signature header
await fetch('https://the-agent.example.com/task', {
  method: 'POST',
  headers: { 'payment-signature': accessToken },
})

import requests
from payments_py import X402TokenOptions, DelegationConfig

# Card (nvm:card-delegation): reuse the delegation you created during enrollment.
result = payments.x402.get_x402_access_token(
    plan_id,
    agent_id,
    token_options=X402TokenOptions(
        scheme="nvm:card-delegation",
        delegation_config=DelegationConfig(delegation_id=delegation_id),
    ),
)

# Stablecoin (nvm:erc4337, the default scheme): create a delegation inline
# from a budget — max spend in cents + lifetime in seconds.
# result = payments.x402.get_x402_access_token(
#     plan_id,
#     agent_id,
#     token_options=X402TokenOptions(
#         delegation_config=DelegationConfig(spending_limit_cents=10000, duration_secs=604800)
#     ),
# )

# Call the paid agent — x402 endpoints read the token from the payment-signature header
requests.post(
    "https://the-agent.example.com/task",
    headers={"payment-signature": result["accessToken"]},
)

The agent’s x402 middleware verifies and settles each request, burning credits as you go. Check your remaining balance anytime:

TypeScript
Python

const balance = await payments.plans.getPlanBalance(planId)
console.log(`Credits: ${balance.balance}`) // e.g. "100"

balance = payments.plans.get_plan_balance(plan_id)
print(f"Credits: {balance['balance']}")

Prefer to gate your own API, build the payment-required challenge, or call verifyPermissions / settlePermissions directly? See Nevermined x402 and Validate Requests. For stablecoin plans you can also buy credits upfront with orderPlan.

Reuse and good practices

Reuse the API key. It doesn’t expire per request — store it once and reuse it.
Reuse the delegation. A delegation is good until its budget is spent or it expires. Don’t re-enroll a card for every purchase.
Top up, don’t re-buy. Check getPlanBalance and order more credits when you run low.
Match the environment. A sandbox: key only works against the Sandbox API base URL, and live: only against Live.

Card Delegation

The full embedded card-enrollment + delegation handshake, in any language.

Nevermined x402

The x402 payment protocol: schemes, headers, verify/settle.

Get Your API Key

Create and manage Nevermined API keys.

Agent-to-Agent Monetization

Let your own agent get paid by other agents.

Documentation Index

​What you’ll do

1. Discover

2. Log in

3. Get a payment method

4. Delegate & buy

​Sandbox vs. Live

​The flow

​Reuse and good practices

​Related

Card Delegation

Nevermined x402

Get Your API Key

Agent-to-Agent Monetization

What you’ll do

Sandbox vs. Live

The flow

Reuse and good practices

Related