API Providers

Agents are a new buyer of your API, and they don’t onboard the way humans do. They don’t sit at a browser, fill out a Stripe Checkout, or remember to top up a credit balance. Today they either stall at your paywall or hardcode a human’s API key. Nevermined turns that failure mode into revenue with a small server-side integration. Agents holding a delegated card mint an x402 access token, send it to your endpoint, and you provision or top up access in response. You verify and settle through Nevermined’s x402 facilitator; the buyer’s card is charged on Stripe or Visa Intelligent Commerce rails, depending on how it was enrolled.

Featured provider

Exa is the live reference. Agents pay Exa $7 via a Nevermined-delegated card and receive an Exa API key with $7 of credits. When the key runs out, the agent tops up through the same endpoint. Same key, more credits, no human touched it.

Exa integration mirror: exa.ai/docs/integrations/nevermined.md

What you build, in five steps

Create a pay-as-you-go plan

On the Nevermined App, choose pay-as-you-go pricing (one charge per purchase), set your price (e.g. $7), and grant 1 credit per purchase. The 1-credit grant means each call to your purchase endpoint maps cleanly to one card charge of your plan price. See Manage Plans.

Expose one endpoint

Accept a payment-signature header on a new route or an existing one. Existing customers keep their flow unchanged.

Verify with the facilitator

Call payments.facilitator.verifyPermissions(...). Missing or invalid token returns 402 Payment Required with the payment requirements body.

Run your business logic

Provision an API key, top up credits, unlock a resource, whatever your product is.

Settle

Call payments.facilitator.settlePermissions(...). The card is charged, credits are minted and burned, you get paid.

Server-side handler

Your handler does three things: read the payment-signature header, verify the token with the Nevermined facilitator, and settle after running your business logic. Examples below for TypeScript, Python, and raw HTTP.

TypeScript
Python
HTTP (any language)

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

const payments = Payments.getInstance({
  nvmApiKey: process.env.NVM_API_KEY!,
  environment: 'live',
})

const paymentRequired = buildPaymentRequired(process.env.PLAN_ID!, {
  endpoint: '/purchase-key',
  httpVerb: 'POST',
  scheme: 'nvm:card-delegation',
})

// Pre-encode for the `payment-required` response header (per x402 spec §4.3).
const paymentRequiredHeader = Buffer.from(
  JSON.stringify(paymentRequired),
).toString('base64')

const send402 = (res) =>
  res
    .status(402)
    .setHeader('payment-required', paymentRequiredHeader)
    .json(paymentRequired)

app.post('/purchase-key', async (req, res) => {
  const token = req.header('payment-signature')
  if (!token) return send402(res)

  // maxAmount = credits to burn (not cents). PAYG plan with 1 credit
  // per purchase means burning 1n triggers one card charge.
  const verification = await payments.facilitator.verifyPermissions({
    paymentRequired,
    x402AccessToken: token,
    maxAmount: 1n,
  })
  if (!verification.isValid) return send402(res)

  const apiKey = await provisionOrTopUp(req)

  const settlement = await payments.facilitator.settlePermissions({
    paymentRequired,
    x402AccessToken: token,
    maxAmount: 1n,
  })

  // Settlement receipt in the `payment-response` header (per x402 spec §4.3).
  res
    .setHeader(
      'payment-response',
      Buffer.from(JSON.stringify(settlement)).toString('base64'),
    )
    .json({ apiKey })
})

import base64
import os
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from payments_py import Payments, PaymentOptions
from payments_py.x402.helpers import build_payment_required

app = FastAPI()

payments = Payments.get_instance(
    PaymentOptions(nvm_api_key=os.environ['NVM_API_KEY'], environment='live')
)

payment_required = build_payment_required(
    plan_id=os.environ['PLAN_ID'],
    endpoint='/purchase-key',
    http_verb='POST',
    scheme='nvm:card-delegation',
)

# Pre-encode for the `payment-required` response header (per x402 spec §4.3).
payment_required_header = base64.b64encode(
    payment_required.model_dump_json(by_alias=True).encode()
).decode()

def send_402() -> JSONResponse:
    return JSONResponse(
        status_code=402,
        content=payment_required.model_dump(by_alias=True),
        headers={'payment-required': payment_required_header},
    )

@app.post('/purchase-key')
async def purchase_key(request: Request):
    token = request.headers.get('payment-signature')
    if not token:
        return send_402()

    # max_amount = credits to burn (not cents). PAYG plan with 1 credit
    # per purchase means burning "1" triggers one card charge.
    verification = payments.facilitator.verify_permissions(
        payment_required=payment_required,
        x402_access_token=token,
        max_amount='1',
    )
    if not verification.is_valid:
        return send_402()

    api_key = await provision_or_top_up(request)

    settlement = payments.facilitator.settle_permissions(
        payment_required=payment_required,
        x402_access_token=token,
        max_amount='1',
    )

    # Settlement receipt in the `payment-response` header (per x402 spec §4.3).
    settlement_header = base64.b64encode(
        settlement.model_dump_json(by_alias=True).encode()
    ).decode()
    return JSONResponse(
        content={'apiKey': api_key},
        headers={'payment-response': settlement_header},
    )

The facilitator API is plain HTTP, no SDK required. Pseudo-code below shows the verify/settle calls your handler needs to make.Endpoints (no Authorization header, auth is in the x402 access token):

POST https://api.live.nevermined.app/api/v1/x402/verify
POST https://api.live.nevermined.app/api/v1/x402/settle

Use https://api.sandbox.nevermined.app/api/v1/... for sandbox.Verify request body:

{
  "paymentRequired": {
    "x402Version": 2,
    "resource": { "url": "/purchase-key", "mimeType": "application/json" },
    "accepts": [{
      "scheme": "nvm:card-delegation",
      "network": "stripe",
      "planId": "<your-plan-id>",
      "extra": { "version": "1", "httpVerb": "POST" }
    }],
    "extensions": {}
  },
  "x402AccessToken": "<token from the payment-signature header>",
  "maxAmount": "1"
}

Response: { "isValid": true, ... } or { "isValid": false, "invalidReason": "..." }.Settle uses the same body shape posted to /x402/settle. Response contains creditsRedeemed, remainingBalance, transaction, and (when auto top-up fired) orderTx.Your response headers (per x402 spec §4.3):

On 402: set payment-required: <base64(PaymentRequired)> so buyer-side clients can discover requirements
On 200: set payment-response: <base64(settlement-receipt)> so buyers have a structured settlement receipt

Pseudo-handler (curl-style):

# 0. Pre-build the PaymentRequired JSON for your endpoint (see body shape above)
PAYMENT_REQUIRED='{"x402Version":2,"resource":{"url":"/purchase-key","mimeType":"application/json"},"accepts":[{"scheme":"nvm:card-delegation","network":"stripe","planId":"<your-plan-id>","extra":{"version":"1","httpVerb":"POST"}}],"extensions":{}}'

# 1. On request: read the payment-signature header
TOKEN="$(http_header payment-signature)"

# 2. Verify
curl -s -X POST https://api.live.nevermined.app/api/v1/x402/verify \
  -H 'Content-Type: application/json' \
  -d "$(jq -n --arg pr "$PAYMENT_REQUIRED" --arg t "$TOKEN" '{
        paymentRequired: ($pr | fromjson),
        x402AccessToken: $t,
        maxAmount: "1"
      }')"
# → on isValid=false, return 402 with payment-required header set

# 3. Run business logic (provision/top-up the API key)

# 4. Settle
curl -s -X POST https://api.live.nevermined.app/api/v1/x402/settle \
  -H 'Content-Type: application/json' \
  -d "$(jq -n --arg pr "$PAYMENT_REQUIRED" --arg t "$TOKEN" '{
        paymentRequired: ($pr | fromjson),
        x402AccessToken: $t,
        maxAmount: "1"
      }')"

# 5. Return 200 with the credential

See the Verify and Settle API references for full request/response schemas, and the card-delegation spec §3.2 for the PaymentRequired JSON shape.

The handlers above set the payment-required (on 402) and payment-response (on 200) response headers per the card-delegation spec §4.3. The optional middleware below handles this for you automatically.

Optional: middleware (recommended)

If you’re on Express or FastAPI, the SDK ships a payment middleware that handles the verify/settle dance and the spec-correct response headers for you. One config line gates your endpoint, your handler stays focused on business logic.

TypeScript (Express)
Python (FastAPI)

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

const app = express()
app.use(express.json())

const payments = Payments.getInstance({
  nvmApiKey: process.env.NVM_API_KEY!,
  environment: 'live',
})

// credits: 1 maps to a PAYG plan with 1 credit per purchase, so one
// call to /purchase-key triggers one card charge for the plan price.
app.use(
  paymentMiddleware(payments, {
    'POST /purchase-key': {
      planId: process.env.PLAN_ID!,
      credits: 1,
      scheme: 'nvm:card-delegation',
    },
  }),
)

app.post('/purchase-key', async (req, res) => {
  const apiKey = await provisionOrTopUp(req)
  res.json({ apiKey })
})

import os
from fastapi import FastAPI, Request
from payments_py import Payments, PaymentOptions
from payments_py.x402.fastapi import PaymentMiddleware

app = FastAPI()

payments = Payments.get_instance(
    PaymentOptions(nvm_api_key=os.environ['NVM_API_KEY'], environment='live')
)

# credits=1 maps to a PAYG plan with 1 credit per purchase, so one
# call to /purchase-key triggers one card charge for the plan price.
app.add_middleware(
    PaymentMiddleware,
    payments=payments,
    routes={
        'POST /purchase-key': {
            'plan_id': os.environ['PLAN_ID'],
            'credits': 1,
            'scheme': 'nvm:card-delegation',
        },
    },
)

@app.post('/purchase-key')
async def purchase_key(request: Request):
    api_key = await provision_or_top_up(request)
    return {'apiKey': api_key}

The middleware reads the payment-signature header, calls verifyPermissions, runs your handler, then calls settlePermissions and attaches the payment-response header before sending the response. See the Express and FastAPI integration pages for middleware options (dynamic credits, hooks, custom error handlers).

Two things to remember

Idempotency. Agents retry. Cache token → result so a replayed token returns the same response without re-running your business logic or re-charging the card.

402 on your regular endpoints. When the agent’s credits run dry, return 402 with a top-up hint on the resource endpoints (not just the purchase endpoint). The agent loops back, mints a fresh token, and pays again on the same purchase route.

Vend-the-key vs full metering

Two patterns are supported. Pick whichever matches how you already meter usage.

Vend-the-key

A Nevermined purchase returns a credential (e.g. an API key with $X of credits). You meter ongoing usage internally with your existing infrastructure. Exa works this way. Best when you already have per-key billing.

Full metering

Nevermined settles each underlying API call. Best when you don’t have internal billing infra or prefer per-request settlement. Use the validate-requests and charge-credits patterns directly on your resource endpoints.

Make it agent-discoverable

Agents don’t read your HTML. They read your llms.txt and the .md mirrors next to your docs pages. Two small additions get you listed.

1. Add a line to your `llms.txt`

Drop an entry into your root llms.txt (under an ## Integrations heading or similar):

- [Nevermined](/integrations/nevermined.md): Accept autonomous agent payments via x402 card delegation. Plan ID, endpoint, and SDK usage in the link.

2. Publish an integration `.md` mirror

Put a markdown file at /integrations/nevermined.md (or wherever your integration docs live). Cover the plan ID, the purchase endpoint, the response shapes, and the agent-side snippet. A starter skeleton with placeholders is hosted here:

api-provider-template.md - copy and fill in
Live example: Exa’s /docs/integrations/nevermined.md

Updating your human-facing HTML docs is optional and less agent-native.

Agent-side call (for context)

What the agent runs to mint a token and call your endpoint:

TypeScript
Python

const { accessToken } = await payments.x402.getX402AccessToken(
  YOUR_PLAN_ID,
  undefined,
  {
    scheme: 'nvm:card-delegation',
    delegationConfig: {
      providerPaymentMethodId: 'pm_...',
      spendingLimitCents: 700,
      durationSecs: 3600,
    },
  },
)

const res = await fetch('https://your-api.com/purchase-key', {
  method: 'POST',
  headers: { 'payment-signature': accessToken },
})

token_res = payments.x402.get_x402_access_token(
    YOUR_PLAN_ID,
    None,
    {
        'scheme': 'nvm:card-delegation',
        'delegationConfig': {
            'providerPaymentMethodId': 'pm_...',
            'spendingLimitCents': 700,
            'durationSecs': 3600,
        },
    },
)
access_token = token_res['accessToken']

res = requests.post(
    'https://your-api.com/purchase-key',
    headers={'payment-signature': access_token},
)

Why Nevermined vs DIY

The DIY way

Stripe Checkout needs a browser and a human, useless mid-task
Roll your own x402 means months building card enrollment, delegation lifecycle, KYC, dispute handling, and a buyer-side SDK
You own PCI scope on the buyer side

The Nevermined way

Drop in verifyPermissions and settlePermissions
Card acquisition via Stripe or Visa Intelligent Commerce, payouts via Stripe Connect today (PayPal Braintree coming soon)
PCI scope stays with Nevermined and the PSP
Standard x402 protocol, no proprietary buyer SDK

FAQ

When do I get paid out?

Settled funds are paid out via your connected Stripe Connect account on Stripe’s standard schedule. PayPal Braintree as a second payout rail is coming soon.

Do my existing customers see any change?

No. Your existing API and billing surface stay as-is. Agent-payable signup is a parallel path you opt into with a new endpoint.

Can I keep my current pricing model?

Yes. Per-call, top-ups, and credit bundles map cleanly to Nevermined plans. For subscriptions, talk to us, recurring billing is supported case-by-case.

What card rails are supported?

Stripe (for direct card enrollment) and Visa Intelligent Commerce (VIC). The x402 token your endpoint verifies is the same regardless of rail; Nevermined handles the rail-specific details. See the card-delegation spec for the underlying flow.

Is there a sandbox?

Yes, on the Stripe rail. Integrate, run end-to-end test transactions, and validate your handler before flipping to live. VIC doesn’t have a sandbox today, so VIC delegations are tested with small amounts in live.

What languages and frameworks are supported?

TypeScript and Python SDKs ship today, with framework helpers for Express.js and FastAPI. The facilitator API is plain HTTP, so any language can call verify/settle directly. See the Generic HTTP guide.

Do I need a Stripe account?

Today, yes: you connect a Stripe Connect account as your payout destination. PayPal Braintree as a second payout option is coming soon (see Braintree onboarding for the planned flow). Nevermined handles card acquisition and PCI scope on the buyer side; you just bring your payout destination.

How are chargebacks and refunds handled?

On Stripe destination charges, Nevermined is the merchant of record: Stripe routes disputes and refunds through Nevermined, and we surface the chargeback or charge reference so you can match it to specific agent transactions.

Multi-currency?

Stripe Connect handles currency conversion to your destination account, so non-USD payouts work today. VIC currently supports predominantly US-based issuers.

x402 Card Delegation Spec - full verify/settle protocol with JWT claims, error codes, and the four-phase flow
x402 Facilitator: How it works
- end-to-end walk-through of the facilitator API
Validate Requests and Charge Credits - copy-paste patterns for the verify and settle steps
Manage Plans - set up a pay-as-you-go plan
Nevermined Pay overview - how buyers enroll cards and create delegations

Learn

Build

Nevermined Pay

Solutions

Integrations

Payment Patterns

Components

Specs

FAQ

Featured provider

What you build, in five steps

Server-side handler

Optional: middleware (recommended)

Two things to remember

Vend-the-key vs full metering

Vend-the-key

Full metering

Make it agent-discoverable

1. Add a line to your `llms.txt`

2. Publish an integration `.md` mirror

Agent-side call (for context)

Why Nevermined vs DIY

The DIY way

The Nevermined way

FAQ

Learn

Build

Nevermined Pay

Solutions

Integrations

Payment Patterns

Components

Specs

FAQ

Documentation Index

​Featured provider

​What you build, in five steps

​Server-side handler

​Optional: middleware (recommended)

​Two things to remember

​Vend-the-key vs full metering

Vend-the-key

Full metering

​Make it agent-discoverable

​1. Add a line to your llms.txt

​2. Publish an integration .md mirror

​Agent-side call (for context)

​Why Nevermined vs DIY

The DIY way

The Nevermined way

​FAQ

​Related

Featured provider

What you build, in five steps

Server-side handler

Optional: middleware (recommended)

Two things to remember

Vend-the-key vs full metering

Make it agent-discoverable

1. Add a line to your `llms.txt`

2. Publish an integration `.md` mirror

Agent-side call (for context)

Why Nevermined vs DIY

FAQ

Related