> ## Documentation Index
> Fetch the complete documentation index at: https://nevermined.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Nevermined payments

# Nevermined Payments SDK

You are building an application that integrates Nevermined payments. Follow these patterns.

## SDK Packages

* **TypeScript**: `@nevermined-io/payments` (npm)
* **Python**: `payments-py` (PyPI)

## Environment Variables

Always use these env vars (never hardcode):

* `NVM_API_KEY` — Nevermined API key (`sandbox:...` for sandbox, `live:...` for production)
* `NVM_ENVIRONMENT` — `sandbox` or `live`
* `NVM_PLAN_ID` — payment plan ID
* `NVM_AGENT_ID` — agent ID (when plans have multiple agents)

## TypeScript Initialization

```typescript theme={null}
import { Payments } from '@nevermined-io/payments'

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

## Python Initialization

```python theme={null}
from payments_py import Payments, PaymentOptions

payments = Payments.get_instance(
    PaymentOptions(nvm_api_key=os.environ["NVM_API_KEY"], environment="sandbox")
)
```

## Express.js Middleware (TypeScript)

```typescript theme={null}
import { paymentMiddleware } from '@nevermined-io/payments/express'

app.use(paymentMiddleware(payments, {
  'POST /ask': { planId: process.env.NVM_PLAN_ID!, credits: 1 }
}))
```

## FastAPI Middleware (Python)

```python theme={null}
from payments_py.x402.fastapi import PaymentMiddleware

app.add_middleware(
    PaymentMiddleware,
    payments=payments,
    routes={"POST /ask": {"plan_id": os.environ["NVM_PLAN_ID"], "credits": 1}}
)
```

## Strands Agent Decorator (Python)

```python theme={null}
from payments_py.x402.strands import requires_payment

@tool(context=True)
@requires_payment(payments=payments, plan_id=PLAN_ID, credits=1)
def my_tool(query: str, tool_context=None) -> dict:
    ...
```

## MCP Server (TypeScript)

```typescript theme={null}
payments.mcp.registerTool(name, config, handler, { credits: 5n })
const { info, stop } = await payments.mcp.start({ port: 3000, agentId, serverName })
```

## Google A2A (TypeScript / Python)

```typescript theme={null}
const agentCard = payments.a2a.buildPaymentAgentCard(baseCard, { paymentType: "dynamic", credits: 1, planId, agentId })
await payments.a2a.start({ port: 3005, basePath: '/a2a/', agentCard, executor })
```

## x402 Headers

* `payment-signature`: Client sends x402 access token
* `payment-required`: Server sends payment requirements (402 response, base64-encoded)
* `payment-response`: Server sends settlement receipt (200 response, base64-encoded)

## Key Rules

* Use `verifyPermissions` / `settlePermissions` for manual x402 (not deprecated `isValidRequest`)
* Use `buildPaymentRequired()` (TS) or `build_payment_required()` (Python) to generate 402 responses
* Credits are `BigInt` in TypeScript (`1n`), `int` or `str` in Python
* Always settle after processing — middleware does this automatically

## Autonomous Operations (REST, no SDK)

When an agent must act on its own behalf at runtime (buy a plan, enroll a card, check credits/revenue), call the REST API directly with `Authorization: Bearer $NVM_API_KEY` against `https://api.sandbox.nevermined.app` (sandbox) or `https://api.live.nevermined.app` (live). Buy in two calls — `POST /api/v1/x402/permissions` (→ `accessToken`) then `POST /api/v1/x402/settle` (→ `creditsRedeemed`, `remainingBalance`). Crypto uses `scheme: "nvm:erc4337"` / `network: "eip155:84532"`; cards use `scheme: "nvm:card-delegation"` / `network: "stripe"`. A human is needed only for one-time setup — the first API key, plus card enrollment if paying by card (the stablecoin path needs neither). Full runbook: `skills/nevermined-payments/references/autonomous-operations.md`.

## Full Skill Reference

See `skills/nevermined-payments/SKILL.md` (Track A = operate autonomously via REST; Track B = add payments to your code via SDK).


## Related topics

- [AI Coding Skill](/docs/development-guide/build-using-nvm-skill.md)
- [Nevermined x402](/docs/development-guide/nevermined-x402.md)
- [Payments](/docs/products/payments/overview.md)
- [Nevermined App Overview](/docs/products/nevermined-app/overview.md)
- [Fiat Payments](/docs/integrate/patterns/fiat-payments.md)