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

# Environments

The SDK supports two built-in environments and an optional custom URL override.

```typescript theme={null}
import { createOakClient } from '@oaknetwork/payments-sdk';

const client = createOakClient({
  environment: 'sandbox', // or 'production'
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
});
```

## Environment URLs

| Environment  | Type           | API Base URL                              | Test operations |
| ------------ | -------------- | ----------------------------------------- | --------------- |
| `sandbox`    | `"sandbox"`    | `https://sandbox-payments.oaknetwork.org` | Allowed         |
| `production` | `"production"` | `https://payments.oaknetwork.org`         | Blocked         |

## Custom URL

Override the built-in URL by passing `customUrl`. This is useful for local development or self-hosted API instances:

```typescript theme={null}
const client = createOakClient({
  environment: 'sandbox',
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
  customUrl: 'http://localhost:3000',
});
```

When `customUrl` is set, it takes priority over the environment's default URL. The `environment` field is still required — it controls sandbox-only behavior regardless of the URL.

## Environment utilities

The SDK exports helper functions for environment checks:

```typescript theme={null}
import { getEnvironmentConfig, isTestEnvironment } from '@oaknetwork/payments-sdk';

const config = getEnvironmentConfig('sandbox');
console.log(config.apiUrl);              // "https://sandbox-payments.oaknetwork.org"
console.log(config.allowsTestOperations); // true

console.log(isTestEnvironment('sandbox'));    // true
console.log(isTestEnvironment('production')); // false
```

## Sandbox-only restrictions

Some SDK operations are restricted to the sandbox environment using the `@SandboxOnly` decorator. If you call a sandbox-only method with `environment: 'production'`, the SDK returns an `EnvironmentViolationError` in the `Result` without making a network request.

```typescript theme={null}
import { EnvironmentViolationError } from '@oaknetwork/payments-sdk';

const result = await someService.sandboxOnlyMethod();

if (!result.ok && result.error instanceof EnvironmentViolationError) {
  console.error(result.error.message);
  // → 'Method "sandboxOnlyMethod" is only available in sandbox environment.
  //    Current environment: production.
  //    This method cannot be called in production to prevent accidental data corruption.'
}
```

### How it works

The `@SandboxOnly` decorator (and its function equivalent `sandboxOnlyFn`) checks the `environment` field on the client config before executing the method:

* If `environment === 'sandbox'` — the method runs normally
* If `environment === 'production'` — an `EnvironmentViolationError` is returned (for async methods) or thrown (for sync methods)

This prevents test operations from accidentally running against production data.

> For the full error type reference, see [Error Handling](/sdk/error-handling).