Skip to main content
This guide covers two different agent setup paths that should not be conflated:
  • MCP flow: your host already runs the Lava MCP server, and the agent should authenticate the current MCP session with lava_login
  • SDK flow: you are writing Node.js agent code and want to call Lava.login() directly
Choose one path and follow only that path.

​
Prerequisites

  • Node.js 18+
  • A terminal

​
MCP flow

Use this when the agent is running inside Claude Code, Claude Desktop, Cursor, or another MCP-capable host with the Lava MCP server configured.

​
1. Install the MCP server

claude mcp add lava -- npx -y @lavapayments/mcp
No pre-provisioned keys are needed — you’ll authenticate in the next step.

​
2. Authenticate the MCP session

Ask the agent to call:
  • lava_login to launch the existing Lava browser auth flow
  • lava_generate_forward_token when you need proxy auth for /v1/forward or /v1/rewrite
  • lava_chat_completions, lava_messages, lava_forward, or lava_rewrite to route live traffic through Lava
lava_login loads the active secret key, creating one if needed. It also returns a usable wallet key if one is already available or creates the first wallet key if none exists.
Use the MCP flow if your goal is to operate Lava from an agent host. Do not import the SDK just to get credentials when the MCP is already available.

​
SDK flow

Use this when you are writing application or CLI code yourself and want to authenticate from Node.js.

​
1. Install the SDK

npm install @lavapayments/nodejs

​
2. Authenticate

Lava.login() opens your browser, lets you sign up or log in, and returns your API credentials automatically. 
import { Lava } from '@lavapayments/nodejs';

const credentials = await Lava.login();

console.log(credentials);
// {
//   secret_key: 'lava_sk_...',
//   secret_key_id: 'sk_...',
//   wallet_key: 'lava_wk_...' | null,
//   wallet_key_id: 'wk_...' | null,
//   merchant_id: 'mer_...',
//   wallet_id: 'wa_...'
// }
If you don’t have an account yet, Lava.login() will take you through sign-up first. No separate registration step needed.

​
3. What happens under the hood

  1. A local HTTP server starts on a random port
  2. Your browser opens to Lava’s authorization page
  3. You sign up or log in and click “Authorize”
  4. Credentials flow back to your terminal
  5. The local server shuts down
The entire flow takes about 10 seconds.

​
Initialize the SDK

Use the secret key as your primary SDK credential. Lava.login() also returns a usable wallet key if one is already available or creates the first wallet key if none exists: 
// Primary credential: meters, plans, checkout, customers, usage
const lava = new Lava(credentials.secret_key);

// Wallet-scoped operations
const wallet = credentials.wallet_key
  ? new Lava(credentials.wallet_key)
  : null;
Store your credentials in environment variables or a secrets manager. You only need to run Lava.login() once.
# Save to your environment
export LAVA_SECRET_KEY="lava_sk_..."
# Optional during the transition period
export LAVA_WALLET_KEY="lava_wk_..."
Then initialize without hardcoding: 
// Reads LAVA_SECRET_KEY from environment automatically
const lava = new Lava();

// Optional legacy wallet credential if you have one
const wallet = process.env.LAVA_WALLET_KEY
  ? new Lava(process.env.LAVA_WALLET_KEY)
  : null;

​
Alternative: Exchange an Auth Code Directly

If you’re building a custom auth flow (for example, handling the browser callback yourself), use Lava.exchangeAuthCode() instead: 
const credentials = await Lava.exchangeAuthCode({
  code: 'your_one_time_auth_code'
});
Auth codes expire after 60 seconds and can only be used once.

​
What’s Next?

Route Traffic

Route live traffic after choosing MCP or SDK flow

Bill Your Customers

Set up usage-based pricing and checkout

Manage AI Spend

Create scoped API keys with spend limits

SDK Reference

Full Node.js SDK documentation