Naven CLI
Create and customize an x402 paid server from the official Naven template.
The Naven CLI scaffolds a standalone Bun and Hono server that accepts x402 v2 payments through the Naven facilitator. The server template is bundled with the CLI, so one command creates a complete project without cloning this repository.
The CLI currently supports the server template.
Requirements
- Bun 1.2 or later
- An EVM address that will receive payments
Create a server
Run the latest CLI without installing it globally:
bunx naven-cli@latest create server my-server
cd my-serverThe CLI copies the server template, creates .env from .env.example, assigns a package name based on the directory, and runs bun install.
Set your payment recipient and start the server:
# .env
X402_PAY_TO=0xYourEvmAddressbun run devRequest http://localhost:4021/weather. An unpaid request should return 402 Payment Required with a PAYMENT-REQUIRED header.
Install the command globally
If you use the CLI regularly, install the naven command:
bun add --global naven-cli@latest
naven --version
naven create server my-serverRun the same install command again to update to the latest release.
Command reference
naven create server [directory] [options]| Argument or option | Behavior |
|---|---|
directory | Destination directory. Defaults to my-server. |
--no-install | Copy the template without running bun install. |
-h, --help | Show help for the CLI or command. |
-v, --version | Show the installed CLI version. |
The destination can be new or an existing empty directory. The CLI refuses to overwrite a non-empty directory.
To inspect the files before installing dependencies:
bunx naven-cli@latest create server my-server --no-install
cd my-server
bun installWhat the server template includes
my-server/
├── .env # local configuration; do not commit
├── .env.example # safe configuration template
├── Dockerfile
├── README.md
├── package.json
├── scripts/
│ └── test-challenge.ts
└── src/
├── app.ts # Hono routes and x402 middleware
├── config.ts # network, asset, price, and environment validation
└── index.ts # Bun server entry pointThe generated server provides:
GET /health, a free health endpointGET /weather, a paid example endpoint- x402 v2 verification and settlement through the Naven facilitator
- Robinhood Chain USDG defaults
- CORS headers for x402 payment requests and responses
- TypeScript checking, a challenge smoke test, and Docker support
The template is a starting point, not a runtime dependency on the CLI. After generation, the new project is independent and you can change any file.
Generated scripts
| Command | Purpose |
|---|---|
bun run dev | Start the server with hot reload. |
bun run start | Start the server without hot reload. |
bun run typecheck | Check the TypeScript project. |
bun run test:challenge | Verify the paid route returns a valid x402 challenge without spending funds. |
bun run check | Run the typecheck and challenge test. |
Configure the template
The CLI creates .env automatically. These variables control deployment-specific behavior:
| Variable | Required | Default | Purpose |
|---|---|---|---|
X402_PAY_TO | Yes | None | EVM address that receives payments. |
PUBLIC_URL | No | http://localhost:4021 | Public HTTP(S) origin buyers use to reach the server. |
PORT | No | 4021 | Local listening port. |
FACILITATOR_URL | No | https://facilitator.naven.network | Facilitator used to verify and settle payments. |
CORS_ORIGIN | No | * | Browser origin allowed to call the server. |
Payment terms are defined in src/config.ts. Route metadata and handlers are defined in src/app.ts. When you rename a paid endpoint, update both the paymentMiddleware key and the matching Hono route.
For a complete customization and deployment walkthrough, continue to the Seller/Server Guide.
Troubleshooting
The target directory is not empty
Choose a new directory or move the existing files. The CLI intentionally does not merge with or overwrite a non-empty project.
Bun could not install dependencies
Confirm bun --version reports Bun 1.2 or later. You can also create with --no-install, enter the generated directory, and run bun install yourself.
X402_PAY_TO is invalid
Use a complete EVM address beginning with 0x. The server validates and checksum-normalizes the address at startup.
The paid endpoint returns 402
That is the expected response for a request without a payment signature. Run bun run test:challenge to validate the challenge, or use an x402 client to complete a paid request.
The challenge contains the wrong resource URL
Set PUBLIC_URL to the exact public HTTPS origin of the deployed server, without a path, query, or fragment.