Node.js SDK

Beta

The Orvion Node.js SDK provides seamless integration with Express for creating payment-protected API endpoints using the x402 protocol.

Quick Start

1. Install the SDK

npm install @orvion/sdk

2. Initialize Orvion

3. Protect Endpoints

Pre-built Payment Router (NEW in v0.2)

Eliminate boilerplate by using the pre-built payment router:

orvionInit

Initialize the Orvion SDK with your API key and configuration.

Configuration

Field	Type	Required	Description	Example
apiKey	`string`	Optional	Your Orvion API key (required)	—
baseUrl	`string?`	Optional	Custom API base URL (default: https://api.orvion.sh)	—
cacheTtlSeconds	`number`	Optional	Route cache TTL in seconds (default: 60)	—
transactionHeader	`string`	Optional	Header for transaction ID (default: 'X-Transaction-Id')	—
customerHeader	`string`	Optional	Header for customer ID (default: 'X-Customer-Id')	—

requirePayment Middleware

Protect Express routes with payment requirements.

Parameters

Field	Type	Required	Description	Example
amount	`string?`	Optional	Price per request (e.g., '0.10')	—
currency	`string`	Optional	Currency code (default: 'USD')	—
allowAnonymous	`boolean?`	Optional	Allow requests without customer ID (default: true)	—
customerResolver	`Function?`	Optional	Function to extract customer ID from request	—
hostedCheckout	`boolean`	Optional	Enable hosted checkout mode - redirects to pay.orvion.sh (default: false)	—
returnUrl	`string?`	Optional	Return URL for hosted checkout. Auto-derived using convention: /api/foo → /foo	—

Examples

New Client Methods (v0.2)

The SDK now includes powerful client methods for payment operations:

Accessing Payment Info

After successful payment verification, payment details are available on req.payment:

Complete Example

TypeScript Types

Hosted Checkout Mode

For web applications where users interact via browser, use hosted checkout mode:

Automatic URL Convention

The SDK uses a convention-based approach for seamless UX:

API at /api/premium → Frontend at /premium
The /api prefix is automatically stripped
Users are redirected to the frontend page after payment (not the API)

No returnUrl configuration needed! Just add hostedCheckout: true and follow the convention.

Before using hosted checkout, configure allowed domains in Settings → Domains to enable return URL validation.

See the Hosted Checkout Guide for complete documentation.