@akcanetwork/x402

Pay-per-use anonymous proxy and VPN SDK with Solana USDC. Built on the x402 protocol (HTTP 402 + on-chain payments).

Installation

npm install @akcanetwork/x402

Peer dependencies: @solana/web3.js and @solana/spl-token

Prerequisites

Option A: Automatic payment (wallet keypair)

You need a Solana wallet with USDC on mainnet. The SDK automatically signs a USDC transfer when it receives a 402 response.

# Create a keypair (or use an existing one)
solana-keygen new -o ~/akca-wallet.json

# Get the address, then fund it with USDC on Solana mainnet
solana address -k ~/akca-wallet.json

Minimum balance: 0.01 USDC + ~0.005 SOL for transaction fees.

Loading a Keypair

import { Keypair } from '@solana/web3.js';
import { readFileSync } from 'fs';

// From a Solana CLI keypair file
const secret = JSON.parse(readFileSync('~/akca-wallet.json', 'utf8'));
const wallet = Keypair.fromSecretKey(new Uint8Array(secret));

// Or from a base58 private key
import bs58 from 'bs58';
const wallet2 = Keypair.fromSecretKey(bs58.decode('your-base58-private-key'));

Option B: External wallet (Phantom MCP, etc.)

No keypair needed. Initialize without wallet — the SDK returns payment details on 402 instead of throwing. Complete the payment externally (e.g. via Phantom MCP transfer) and pass back the paymentSignature.

const akca = new AkcaX402Client(); // no wallet

const result = await akca.connectVpn({ serverId: 'awg-de-frankfurt-1' });
// result.payment_required === true
// result.amount_usdc === 0.50
// result.pay_to === "RECIPIENT_ATA_ADDRESS"

// ... pay via Phantom MCP or any Solana wallet ...

const vpn = await akca.connectVpn({
  serverId: 'awg-de-frankfurt-1',
  paymentSignature: '5xYz...', // tx signature from your wallet
});
// vpn.config === WireGuard config

Quick Start

import { AkcaX402Client } from '@akcanetwork/x402';
import { Keypair } from '@solana/web3.js';
import { readFileSync } from 'fs';

const secret = JSON.parse(readFileSync('~/akca-wallet.json', 'utf8'));
const wallet = Keypair.fromSecretKey(new Uint8Array(secret));
const akca = new AkcaX402Client({ wallet });

// Proxy a request through a German exit node
const result = await akca.fetch('https://api.example.com/data', {
  country: 'DE',
});
// 402 -> auto-pay USDC -> 200 OK
console.log(result.body);

API

new AkcaX402Client({ baseUrl?, wallet?, rpcUrl? })

| Parameter | Type | Default | |-----------|------|---------| | baseUrl | string | https://api.akca.network | | wallet | Keypair | undefined (optional — enables automatic payment when set) | | rpcUrl | string | Solana mainnet |

When wallet is not provided, 402 responses return a payment_required object instead of auto-paying. Use paymentSignature in subsequent calls to complete the payment.

Proxy

// Single request (0.001 USDC)
await akca.fetch(url, { method, headers, body, country });

// With an external payment signature
await akca.fetch(url, { country: 'DE', paymentSignature: 'tx_sig...' });

// 24-hour session (1.00 USDC)
await akca.createProxySession({ country: 'DE' });

VPN (Manual)

// List servers (free)
const servers = await akca.getVpnServers();

// Get pricing (free)
const pricing = await akca.getVpnPricing();

// Connect (0.50 USDC / 24 hours)
const vpn = await akca.connectVpn({
  serverId: servers[0].id,
  duration: '24h', // '24h' | '7d' | '30d'
});
console.log(vpn.config); // WireGuard config

// Connect with external payment
const vpn2 = await akca.connectVpn({
  serverId: servers[0].id,
  paymentSignature: 'tx_sig...',
});

// Disconnect
await akca.disconnectVpn(vpn.session.id);

VPN Auto-Setup + Tunnel

import { quickVpn } from '@akcanetwork/x402';

// One-liner: auto-install WireGuard + pay USDC + bring up tunnel
const vpn = await quickVpn({
  wallet,
  country: 'US',
  duration: '24h',
});
// All system traffic is now routed through the VPN

await vpn.disconnect(); // tear down tunnel + remove peer

VPN Manager (Advanced)

import { AkcaX402Client, AkcaVpnManager } from '@akcanetwork/x402';

const akca = new AkcaX402Client({ wallet });
const mgr = new AkcaVpnManager();

// Auto-install AmneziaWG/WireGuard if missing
const info = await mgr.ensureInstalled();
// { installed: true, binary: 'awg-quick', type: 'amneziawg' }

// Connect and get config
const vpn = await akca.connectVpn({ serverId: 'us-virginia-1' });

// Bring up tunnel (write config + wg-quick up)
await mgr.up(vpn.config);

// Check status
const status = await mgr.status();

// Tear down tunnel
await mgr.down();
await akca.disconnectVpn(vpn.session.id);

Supported platforms: Ubuntu/Debian (apt), Fedora/RHEL (dnf), Arch (pacman), macOS (brew). Prefers AmneziaWG (DPI bypass), falls back to standard WireGuard.

How x402 Works

With wallet (automatic)

1. SDK sends request to Akca API
2. API returns 402 Payment Required with USDC amount
3. SDK creates and signs a Solana USDC transfer
4. SDK retries with X-PAYMENT: <tx-signature> header
5. API verifies on-chain, returns response + session cookie
6. Subsequent requests use the session cookie (no re-payment)

Without wallet (Phantom MCP / external)

1. SDK sends request to Akca API
2. API returns 402 Payment Required
3. SDK returns { payment_required: true, amount_usdc, pay_to, ... }
4. Caller pays via external wallet (Phantom MCP, CLI, etc.)
5. Caller retries with paymentSignature — SDK sends X-PAYMENT header
6. API verifies on-chain, returns response

Proxy vs VPN

| Requests | Proxy Cost | VPN Cost | Best Choice | |----------|-----------|----------|-------------| | 10 | $0.01 | $0.50 | Proxy | | 100 | $0.10 | $0.50 | Proxy | | 500 | $0.50 | $0.50 | Either | | 1,000+ | $1.00+ | $0.50 | VPN |

Rule of thumb: < 500 requests -> Proxy. 500+ requests -> VPN.

Pricing

| Product | Tier | Price | |---------|------|-------| | Proxy | Per request | 0.001 USDC | | Proxy | 24-hour session | 1.00 USDC | | VPN | 24 hours | 0.50 USDC | | VPN | 7 days | 2.00 USDC | | VPN | 30 days | 6.00 USDC |

License

MIT - Akca Network