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

# Initializing the Library

> Initialize and configure the Payments class for Python

This guide explains how to import, configure, and initialize the Nevermined Payments Python SDK.

## Get the NVM API Key

Before using the SDK, you need a Nevermined API Key:

1. Go to the [Nevermined App](https://nevermined.app)
2. Sign in or create an account
3. Navigate to **Settings** > **API Keys**
4. Generate a new API key
5. Copy the key (format: `nvm:xxxxxxxx...`)

<Warning title="Keep your API key secure">
  Never commit your API key to version control. Use environment variables or a secrets manager.
</Warning>

## Import and Initialize

### Basic Initialization

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

# Initialize with API key and environment
payments = Payments.get_instance(
    PaymentOptions(
        nvm_api_key="nvm:your-api-key-here",
        environment="sandbox"
    )
)

# Verify initialization
print(f"Connected to: {payments.environment.backend}")
print(f"Account: {payments.account_address}")
```

### Using Environment Variables

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

payments = Payments.get_instance(
    PaymentOptions(
        nvm_api_key=os.getenv("NVM_API_KEY"),
        environment=os.getenv("NVM_ENVIRONMENT", "sandbox")
    )
)
```

## Configuration Options

The `PaymentOptions` class accepts the following parameters:

| Parameter     | Type   | Required | Description                                                                                                               |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `nvm_api_key` | `str`  | Yes      | Your Nevermined API key                                                                                                   |
| `environment` | `str`  | Yes      | Environment name (see below)                                                                                              |
| `app_id`      | `str`  | No       | Application identifier                                                                                                    |
| `version`     | `str`  | No       | Application version                                                                                                       |
| `api_version` | `str`  | No       | Backend API version sent as the `Nevermined-Version` header. Defaults to the version this SDK release targets (see below) |
| `headers`     | `dict` | No       | Additional HTTP headers                                                                                                   |
| `return_url`  | `str`  | No       | Return URL (browser mode only)                                                                                            |

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

payments = Payments.get_instance(
    PaymentOptions(
        nvm_api_key="nvm:your-api-key",
        environment="sandbox",
        app_id="my-app",
        version="1.0.0",
        headers={"X-Custom-Header": "value"}
    )
)
```

### API Version Pinning

Every request the SDK sends to the Nevermined backend carries a
`Nevermined-Version` header declaring which backend API version
(`MAJOR.MINOR`) the SDK was built and tested against. You normally don't
need to touch this — the SDK pins the right version for you. To target a
different backend contract explicitly:

```python theme={null}
payments = Payments.get_instance(
    PaymentOptions(
        nvm_api_key="nvm:your-api-key",
        environment="sandbox",
        api_version="1.1",  # override the pinned backend API version
    )
)
```

See the [API versioning reference](https://docs.nevermined.app/api-reference/versioning)
for the list of versions and the changes between them.

## Environments

### Sandbox Environment (Testing)

Use `sandbox` for development and testing:

```python theme={null}
payments = Payments.get_instance(
    PaymentOptions(
        nvm_api_key="nvm:your-api-key",
        environment="sandbox"
    )
)
```

* Backend: `https://api.sandbox.nevermined.app`
* Proxy: `https://proxy.sandbox.nevermined.app`
* Uses test tokens and test networks

### Live Environment (Production)

Use `live` for production:

```python theme={null}
payments = Payments.get_instance(
    PaymentOptions(
        nvm_api_key="nvm:your-api-key",
        environment="live"
    )
)
```

* Backend: `https://api.live.nevermined.app`
* Proxy: `https://proxy.live.nevermined.app`
* Uses real tokens and mainnet networks

### Custom Environment

For self-hosted or development setups:

```python theme={null}
import os

# Set environment variables first
os.environ["NVM_BACKEND_URL"] = "http://localhost:3001"
os.environ["NVM_PROXY_URL"] = "http://localhost:443"

payments = Payments.get_instance(
    PaymentOptions(
        nvm_api_key="nvm:your-api-key",
        environment="custom"
    )
)
```

### Available Environments

| Environment | Description                           |
| ----------- | ------------------------------------- |
| `sandbox`   | Production sandbox (testing)          |
| `live`      | Production mainnet                    |
| `custom`    | Custom URLs via environment variables |

## Accessing Sub-APIs

The initialized `Payments` object provides access to specialized APIs:

```python theme={null}
# Plans API - manage payment plans
payments.plans.register_credits_plan(...)
payments.plans.get_plan(plan_id)
payments.plans.get_plan_balance(plan_id)

# Agents API - manage AI agents
payments.agents.register_agent(...)
payments.agents.get_agent(agent_id)

# Facilitator API - x402 verification/settlement
payments.facilitator.verify_permissions(...)
payments.facilitator.settle_permissions(...)

# X402 Token API - generate access tokens
payments.x402.get_x402_access_token(plan_id, agent_id)

# MCP Integration
payments.mcp.register_tool(...)
await payments.mcp.start(config)

# A2A Integration
payments.a2a["start"](agent_card=card, executor=executor)
```

## Error Handling

The SDK raises `PaymentsError` for API errors:

```python theme={null}
from payments_py.common.payments_error import PaymentsError

try:
    result = payments.plans.get_plan("invalid-id")
except PaymentsError as e:
    print(f"Error: {e.message}")
    print(f"Code: {e.code}")
```

## Next Steps

Now that you have initialized the SDK, proceed to:

* [Payment Plans](/docs/api-reference/python/plans-module) - Create payment plans
* [Agents](/docs/api-reference/python/agents-module) - Register AI agents