> ## 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.

# Getting Started

> Initialize the Payments SDK in Node.js and browser environments with your API key

# Initializing the Library

This guide shows how to initialize the Nevermined Payments Library in your application. The library supports both server-side (Node.js) and browser environments with different initialization methods.

## Get Your NVM API Key

Before initializing the library, you need a Nevermined API key:

1. Visit [nevermined.app](https://nevermined.app)
2. Sign in or create a free account
3. Navigate to your profile settings
4. Generate an API key

**Important**: There are two types of API keys:

* **Builder Key**: For AI builders who register agents and payment plans
* **Subscriber Key**: For users who purchase access and query agents

Most applications will use a builder key for server-side operations.

## Server-Side Initialization

For Node.js applications, use the `getInstance` method:

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

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

The environment is derived automatically from your API key — see [Environment derivation](#environment-derivation) below.

### Configuration Options

The `getInstance` method accepts a `PaymentOptions` object:

```typescript theme={null}
interface PaymentOptions {
  nvmApiKey: string           // Your Nevermined API key (required)
  environment?: EnvironmentName  // @deprecated — derived from the API key (optional)
  returnUrl?: string          // OAuth callback URL (optional, for browser)
  appId?: string              // Your application ID (optional)
  version?: string            // Backend API version pin, MAJOR.MINOR (optional)
}
```

### Environment derivation

NVM API keys are prefixed with the environment they belong to
(`<prefix>:<jwt>`), so the SDK resolves the target environment from the key —
you no longer need to pass `environment`.

The `environment` option is **deprecated** but still accepted:

* When the key prefix maps to a known environment, the **key always wins** and
  the `environment` option is ignored (a one-time deprecation warning is logged).
* When the key has no recognized prefix (for example a local/custom build), the
  SDK falls back to the `environment` option, and finally to `custom`. This
  keeps local and custom-backend workflows working unchanged.

### Complete Server-Side Example

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

// Initialize with environment variables
const payments = Payments.getInstance({
  nvmApiKey: process.env.NVM_API_KEY!,
  environment: process.env.NVM_ENVIRONMENT as EnvironmentName,
})

// Verify connection
const accountAddress = payments.getAccountAddress()
console.log(`Connected as: ${accountAddress}`)
```

## Browser Initialization

For browser-based applications, use the `getBrowserInstance` method:

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

const payments = Payments.getBrowserInstance({
  returnUrl: 'https://myapp.example/callback',
  environment: 'sandbox',
  appId: 'my-app',
  // Optional: pin the backend API version (MAJOR.MINOR). Defaults to the
  // version this SDK release targets — omit unless you must pin an older one.
  version: '1.1',
})
```

### Browser Authentication Flow

The browser instance supports OAuth-style authentication:

```typescript theme={null}
// Check if user is logged in
if (!payments.isLoggedIn) {
  // Redirect to Nevermined login
  payments.connect()
}

// After login, use the payments instance
const balance = await payments.plans.getPlanBalance(planId)

// Logout when needed
payments.logout()
```

## Environments

The Nevermined protocol supports multiple environments:

### Production Environments

| Environment | Description                    | Usage                                        |
| ----------- | ------------------------------ | -------------------------------------------- |
| `sandbox`   | Production testing environment | Development and testing with real blockchain |
| `live`      | Production environment         | Live agents and real payments                |

### Choosing an Environment

```typescript theme={null}
// Development and testing
const payments = Payments.getInstance({
  nvmApiKey: process.env.NVM_API_KEY!,
  environment: 'sandbox',
})

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

**Important**: Agents and plans registered in one environment cannot be accessed from another. Always use the same environment throughout your application.

## Environment Configuration Details

Each environment has specific API endpoints:

```typescript theme={null}
// Example environment structure
interface EnvironmentInfo {
  frontend: string   // Nevermined App URL
  backend: string    // API URL
  proxy: string      // Proxy service URL
  heliconeUrl: string // Observability service URL
}
```

The library automatically configures these endpoints based on your chosen environment.

## Verify Connection

After initialization, verify the connection is working:

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

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

// Get account address from API key
const accountAddress = payments.getAccountAddress()
console.log(`Initialized for account: ${accountAddress}`)

// For browser instances
if (payments.isLoggedIn) {
  console.log('User authenticated successfully')
}
```

## Best Practices

1. **Environment Variables**: Always store API keys in environment variables, never hardcode them
2. **Singleton Pattern**: Create one Payments instance per application
3. **Environment Consistency**: Use the same environment for all operations in a session
4. **Error Handling**: Wrap initialization in try-catch blocks for production apps

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

let payments: Payments

try {
  payments = Payments.getInstance({
    nvmApiKey: process.env.NVM_API_KEY!,
    environment: process.env.NVM_ENVIRONMENT as EnvironmentName,
  })
  console.log('✓ Nevermined Payments initialized')
} catch (error) {
  console.error('Failed to initialize Payments:', error)
  process.exit(1)
}
```

## Related Documentation

* [Payment Plans](./payment-plans)
* [Agents](./agents)

***

**Source References**:

* `src/payments.ts` (getInstance, getBrowserInstance methods)
* `src/environments.ts` (environment configurations)
* `tests/e2e/fixtures.ts` (createPaymentsBuilder, createPaymentsSubscriber)