Skip to main content
The @lavapayments/nodejs SDK provides a typed client for the Lava AI Gateway: routing requests, tracking your usage, managing secret keys and spend keys, and generating forward tokens.

Installation

Requirements: Node.js 18.0.0 or higher

Initialize

The client reads your secret key from the LAVA_SECRET_KEY environment variable automatically. You can also pass it explicitly: new Lava('aks_live_...'). Never commit API keys to version control.

Resources

Plus utility methods:
  • gateway() — Make requests through the gateway in a single call
  • generateForwardToken() — Create authentication tokens for manual requests
  • Lava.login() — Browser-based CLI authentication (static). Deprecated: create a secret key in the dashboard instead
  • Lava.exchangeAuthCode() — Exchange auth code for credentials (static). Deprecated with Lava.login()
  • providers.* — Pre-configured URLs for 27 AI providers

Gateway Requests

The gateway() method makes a request through Lava’s gateway in a single call. It handles forward token generation, URL construction, and body serialization automatically.

Parameters

With Format Translation (Rewrite)

Use format to send requests in one LLM format and have Lava translate to the provider’s native format automatically. The provider format is auto-detected from the target URL.
Supported formats: openai, anthropic, google, bedrock. See Rewrite Proxy for details on format translation.

With Custom Headers

Some providers require additional headers. Pass them via options.headers — the Authorization header is always set to the forward token automatically.
Pass the raw provider URL to gateway() (e.g., https://api.openai.com/v1/chat/completions), not lava.providers.* URLs. The method constructs the forwarding URL internally.
The gateway() method returns parsed JSON. For streaming responses, use generateForwardToken() with manual fetch() instead.

Authentication

Using Your Secret Key (Simplest)

The simplest way to authenticate is to pass your secret key directly, with no forward token. Costs are charged to your Lava wallet:
Or use the gateway() method, which handles this automatically.

Generating Forward Tokens

A forward token is a base64-encoded JSON that bundles your secret key with optional request settings. Pass it in the Authorization header in place of your secret key. Gateway authentication: equivalent to sending your secret key directly. Costs are charged to your Lava wallet:
Unmanaged (bring your own key) authentication: use your own provider API key with Lava for usage tracking only:
Unmanaged mode (bring your own key) lets you use Lava’s proxy for usage tracking and analytics without setting up wallet billing. You supply your own provider API key; the AI provider charges your account directly. Lava may still charge a service fee for metering.

CLI Authentication (Deprecated)

Lava.login() and Lava.exchangeAuthCode() are deprecated. Pass a secret key to new Lava(secretKey) or set LAVA_SECRET_KEY, as shown in Using Your Secret Key. Keys live in the dashboard under Secrets; while new key creation is paused, they are enabled on request, as described in Get a secret key from the dashboard. Both methods keep working for existing scripts until a future major version removes them.
Lava.login() authenticates from a script by opening the browser, waiting for the user to authorize, and returning credentials:
Lava.login() loads an existing active Secret Key. New developer Secret Key creation is temporarily paused for all accounts. If no key exists, login returns a FORBIDDEN error instead of creating one. Existing keys continue to work. If you already have an authorization code (from a custom callback flow), exchange it directly:
Lava.login() requires a Node.js environment. It starts a local HTTP server and opens the system browser. It is not intended for use in production web applications.

Key Management

Spend Keys

Spend keys give scoped access to your wallet for AI requests:

Model Discovery

List available AI models in OpenAI-compatible format. When authenticated with a spend key, results are filtered by the key’s allowed models and providers:

Usage

List Requests

Every request routed through the gateway is recorded with its provider, model, token counts, and cost:

Get Usage Statistics

Common Patterns

Pagination

All list methods support cursor-based pagination:

Error Handling

Gateway Flow Example

A minimal integration for developers using Lava as an AI proxy:
The SDK automatically detects test vs production mode based on your secret key prefix:
  • aks_test_* routes to sandbox (sandbox-api.lava.so)
  • Other prefixes route to production (api.lava.so)

Next Steps

API Reference

Complete API documentation with all parameters and response types

Forward Proxy

Route AI requests through Lava’s proxy