VX SDK — Documentation

Overview

VX SDK (@nk4dev/vx / vx3) is a TypeScript CLI tool and SDK designed to accelerate Web3 application (dApp) development. It provides smart contract integration, wallet management, multi-chain RPC connectivity, and a cryptocurrency payment API.

🔗 RPC Connectivity

Manage HTTP/WS RPC connections to Ethereum-compatible chains via config file

💸 Payment API

Built-in ETH transfer and Payment component for React/Vue

⛏️ Hardhat Integration

Scaffold a full Hardhat development environment with a single command

📦 IPFS

Fetch IPFS content directly from the CLI

GitHub (vx) · GitHub (vx3 parent) · npm: @nk4dev/vx

Installation

Install via npm, pnpm, yarn, or Bun.

npm

npm install -g @nk4dev/vx

pnpm

pnpm add -g @nk4dev/vx

Bun

bun add -g @nk4dev/vx

Add as a local project dependency

npm install @nk4dev/vx

After installation, verify the version:

vx3 --version

Quick Start

1. Create a new project:

vx3 create my-dapp

2. Navigate into the directory and set up Hardhat (optional):

cd my-dapp
vx3 setup hardhat

3. Use the SDK programmatically:

import vx from '@nk4dev/vx';

const blockNumber = await vx.getBlockNumber('https://eth.llamarpc.com');
console.log('Block:', blockNumber);

vx.config.json

Place a vx.config.json in your project root to manage RPC endpoints and IPFS settings. Define multiple endpoints using array format.

[
  {
    "host": "127.0.0.1",
    "port": 8545,
    "protocol": "http",
    "type": "rpc"
  },
  {
    "host": "eth.llamarpc.com",
    "port": 443,
    "protocol": "https",
    "type": "rpc"
  }
]

Field	Type	Description
`host`	string	RPC hostname or IP address
`port`	number	Port number
`protocol`	string	`http` \| `https` \| `ws` \| `wss`
`type`	string	`rpc` \| `ipfs`

CLI Reference

vx3 create <name>

Create a new VX project from a template. Omitting name enters interactive mode.

vx3 create my-dapp
# または対話モード
vx3 create

Alias: vx3 init

vx3 setup hardhat

Scaffold a Hardhat development environment into the current project (hardhat.config.ts, sample contracts, deploy scripts, etc.).

vx3 setup hardhat

vx3 rpc

Subcommands for managing RPC configuration.

vx3 rpc list                        # List all configurations
vx3 rpc create                      # Create a new configuration
vx3 rpc add                         # Add an endpoint
vx3 rpc save --host <h> --port <p> --protocol <p>
vx3 rpc load                        # Load configuration
vx3 rpc help                        # Show help

vx3 gas

Fetches and displays the current gas fees from an RPC endpoint.

# Uses the first entry from vx.config.json
vx3 gas

# Specify RPC directly
vx3 gas --rpc https://eth.llamarpc.com

# Specify config file path
vx3 gas --path ./vx.config.json

Output: baseFeePerGas, maxPriorityFeePerGas, maxFeePerGas, gasPrice (legacy) displayed in gwei

vx3 pay <to> <amount>

Send ETH to a specified address. The private key is read from the PRIVATE_KEY environment variable.

# Basic usage (RPC loaded from vx.config.json)
vx3 pay 0xRecipientAddress 0.01

# Specify RPC and private key directly
vx3 pay 0xRecipient 0.01 --rpc https://eth.llamarpc.com --key 0xYourPrivateKey

# Short flags
vx3 pay 0xRecipient 0.05 -r http://localhost:8545 -k 0xPrivateKey

⚠️ Security: It is strongly recommended to manage your private key via the PRIVATE_KEY environment variable or a .env file rather than the --key flag.

vx3 ipfs fetch <cid>

Fetch content by IPFS CID. A custom gateway URL can also be specified.

# Use default gateway
vx3 ipfs fetch QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

# Specify a custom gateway
vx3 ipfs fetch <cid> https://cloudflare-ipfs.com/ipfs/

vx3 serve

Start a local development server.

vx3 serve

vx3 info / --version

Check the SDK version and project information.

vx3 --version   # Local version
vx3 -v
vx3 info        # Fetch version info from remote API

SDK API Reference

Import @nk4dev/vx to use it programmatically. Both ESM and CJS are supported.

// ESM default import
import vx from '@nk4dev/vx';

// Named imports
import { payment } from '@nk4dev/vx';

// CJS
const vx = require('@nk4dev/vx');

vx.getBlockNumber(provider)

Gets the latest block number from the specified RPC provider.

Parameter	Type	Description
`provider`	string	RPC endpoint URL

Returns: Promise<number>

const block = await vx.getBlockNumber('https://eth.llamarpc.com');
console.log('Latest block:', block);

vx.getBalance(provider, address)

Gets the ETH balance of the specified address (returned as a number in ETH units).

Parameter	Type	Description
`provider`	string	RPC endpoint URL
`address`	string	Ethereum address (0x...)

Returns: Promise<number> (in ETH units)

const balance = await vx.getBalance(
  'https://eth.llamarpc.com',
  '0xYourAddress'
);
console.log(`Balance: ${balance} ETH`);

vx.getGasFees(provider)

Fetches EIP-1559 gas fee information. Falls back to legacy gasPrice for unsupported networks.

Parameter	Type	Description
`provider`	string	RPC endpoint URL

Returns: Promise<GasFees>

type GasFees = {
  unit: 'gwei' | 'wei';
  gasPriceGwei?: string;
  maxFeePerGasGwei?: string;
  maxPriorityFeePerGasGwei?: string;
  baseFeePerGasGwei?: string;
  raw: {
    gasPrice?: bigint | null;
    maxFeePerGas?: bigint | null;
    maxPriorityFeePerGas?: bigint | null;
    baseFeePerGas?: bigint | null;
  };
};

const fees = await vx.getGasFees('https://eth.llamarpc.com');
console.log('baseFee:', fees.baseFeePerGasGwei, 'gwei');
console.log('maxFee :', fees.maxFeePerGasGwei, 'gwei');

vx.payment.sendPayment(opts)

Builds a transaction and sends ETH to the specified address. Waits for confirmation and returns the receipt.

Option	Type	Required	Description
`rpcUrl`	string	✓	RPC endpoint URL
`privateKey`	string	✓	Sender's private key (hex)
`to`	string	✓	Recipient address
`amountEth`	string	✓	Amount to send (ETH units, e.g. "0.01")
`maxFeePerGas`	string	-	Max gas fee (gwei string)
`maxPriorityFeePerGas`	string	-	Priority fee (gwei string)
`gasLimit`	number	-	Gas limit

Returns: Promise<{ txHash: string; receipt?: any }>

import vx from '@nk4dev/vx';
import 'dotenv/config';

const result = await vx.payment.sendPayment({
  rpcUrl: 'https://eth.llamarpc.com',
  privateKey: process.env.PRIVATE_KEY!,
  to: '0xRecipientAddress',
  amountEth: '0.01',
});

console.log('TX Hash:', result.txHash);
console.log('Block:', result.receipt?.blockNumber);

vx.getRpcUrl()

Reads vx.config.json and builds an RPC URL string from the first entry.

Returns: string

import vx from '@nk4dev/vx';

const url = vx.getRpcUrl();
// => "https://eth.llamarpc.com:443"

React Components

<Payment />

A React component for one-click ETH payments.

import { Payment } from '@nk4dev/vx';

export default function App() {
  return (
    <Payment
      to="0x1234567890abcdef1234567890abcdef12345678"
      amount="0.01"
      currency="ETH"
      onSuccess={() => alert('Payment successful!')}
      onError={(err) => alert('Failed: ' + err.message)}
    />
  );
}

Props	Type	Description
`to`	string	Recipient Ethereum address
`amount`	string	Amount to send (ETH units)
`currency`	string	Currency (e.g. `"ETH"`)
`onSuccess`	() => void	Callback on payment success
`onError`	(err: Error) => void	Callback on error

React Hooks

Use hooks for more granular control.

import { usePayment, usePaymentStatus, usePaymentDialog } from '@nk4dev/vx';

export default function DonateButton() {
  const initiatePayment = usePayment();

  const handleDonate = async () => {
    try {
      await initiatePayment({
        to: '0xRecipientAddress',
        amount: '0.005',
        currency: 'ETH',
      });
    } catch (err) {
      console.error(err);
    }
  };

  return <button onClick={handleDonate}>Donate ETH</button>;
}

Hardhat Integration

Running vx3 setup hardhat automatically generates the following files:

packages/hardhat/hardhat.config.ts
packages/hardhat/contract/ — sample contracts
packages/hardhat/scripts/deploy.ts — deploy script
packages/hardhat/typechain-types/ — type definitions

Hardhat Commands

# Compile
npm run hh:compile

# Start local node
npm run hh:node

# Deploy (localhost)
npm run hh:deploy

# Run tests
npm run hh:test

Fix ethers type errors in Bun environment

bun add ethers

License

Repository: github.com/nk4dev/vx