@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

Includes @solana/kit for on-chain payments. No peer dependencies needed.

Three Ways to Use

1. Subscriber (no wallet needed)

VPN subscribers and NFT holders get proxy access included. Use your account token from the Akca dashboard.

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

const akca = createSubscriberClient({
  accountToken: 'eyJ...your-account-token',
});

// No payment — included in subscription
const result = await akca.fetch('https://api.example.com/data', {
  country: 'DE',
});
console.log(result.body);

2. Wallet keypair (automatic payment)

The SDK automatically signs a USDC transfer when it receives a 402 response.

import { AkcaX402Client } from '@akcanetwork/x402';
import { createKeyPairSignerFromBytes } from '@solana/kit';
import { readFileSync } from 'fs';

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

const akca = new AkcaX402Client({ wallet });

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

From a base58 private key:

import { createKeyPairSignerFromBytes, getBase58Encoder } from '@solana/kit';

const bytes = getBase58Encoder().encode('your-base58-private-key');
const wallet = await createKeyPairSignerFromBytes(bytes);
const akca = new AkcaX402Client({ wallet });

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

3. External wallet (Phantom MCP, etc.)

No keypair needed. The SDK returns payment details on 402 — pay externally and pass back the signature.

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 transfer 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

API

new AkcaX402Client(options?)

| Parameter | Type | Default | |-----------|------|---------| | baseUrl | string | https://api.akca.network | | wallet | KeyPairSigner | undefined (enables automatic payment) | | rpcUrl | string | Solana mainnet | | accountToken | string | undefined (enables subscriber access) |

createSubscriberClient({ accountToken, baseUrl? })

Shorthand for creating a client with subscriber access. Throws if accountToken is missing.

Proxy

akca.fetch(url, options?)

Proxy a single HTTP request. Headers (User-Agent) are auto-rotated for bot detection avoidance.

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

// With IP rotation — each request uses a different exit node
await akca.fetch(url, { rotate: true, country: 'DE' });

// With smart extract — parse HTML into structured data
await akca.fetch(url, { extract: 'text' });      // body text only
await akca.fetch(url, { extract: 'markdown' });  // clean markdown (best for AI)
await akca.fetch(url, { extract: 'links' });     // all links
await akca.fetch(url, { extract: 'metadata' });  // title, description, OG tags
await akca.fetch(url, { extract: 'tables' });    // table data
await akca.fetch(url, { extract: 'json' });      // JSON-LD structured data

// With cookie jar — persist cookies across requests
await akca.fetch(loginUrl, { method: 'POST', body: creds, cookie_jar: 'sess1' });
await akca.fetch(dashboardUrl, { cookie_jar: 'sess1' }); // sends login cookies

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

| Option | Type | Description | |--------|------|-------------| | method | string | HTTP method (default: GET) | | headers | object | Request headers (User-Agent auto-rotated if not set) | | body | string\|object | Request body | | country | string | Exit country code (DE, US, JP...) | | server_id | string | Specific exit server ID | | rotate | boolean | Enable IP rotation (round-robin across exit nodes) | | extract | string | Smart extract mode: text, markdown, links, metadata, tables, json | | cookie_jar | string | Cookie jar ID — persist cookies across requests (30 min TTL) | | paymentSignature | string | Pre-made payment tx signature |

akca.batchFetch(urls, options?)

Fetch multiple URLs in parallel. Up to 50 URLs per batch with configurable concurrency.

// Simple — array of URL strings
const result = await akca.batchFetch([
  'https://example.com/page1',
  'https://example.com/page2',
  'https://example.com/page3',
]);
console.log(result.count);   // 3
console.log(result.results);  // [{url, status, body, proxy}, ...]

// Advanced — per-URL method/headers
const result = await akca.batchFetch([
  { url: 'https://api.example.com/users', method: 'GET' },
  { url: 'https://api.example.com/posts', method: 'GET' },
  { url: 'https://api.example.com/submit', method: 'POST', body: '{"data":1}' },
], {
  country: 'US',
  rotate: true,
  extract: 'text',
  concurrency: 10,
});

| Option | Type | Description | |--------|------|-------------| | method | string | Default HTTP method for all URLs | | headers | object | Default headers for all URLs | | country | string | Exit country code | | rotate | boolean | IP rotation across batch requests | | extract | string | Smart extract mode | | concurrency | number | Max parallel requests (default 5, max 10) | | cookie_jar | string | Cookie jar ID for session persistence | | paymentSignature | string | Pre-made payment tx signature |

akca.search(query, options?)

Search the web anonymously through proxy. Returns structured results (title, URL, snippet).

const result = await akca.search('solana x402 protocol', {
  engine: 'duckduckgo', // or 'google'
  country: 'US',
  num_results: 10,
});
console.log(result.results); // [{title, url, snippet}, ...]

| Option | Type | Description | |--------|------|-------------| | engine | string | Search engine: duckduckgo (default) or google | | country | string | Exit country code (affects search locality) | | rotate | boolean | Enable IP rotation | | num_results | number | Max results (default 10, max 20) | | paymentSignature | string | Pre-made payment tx signature |

akca.render(url, options?)

Render a page via headless browser through proxy and capture a screenshot. Returns a base64-encoded image. Includes free stealth mode for Cloudflare/bot bypass.

const result = await akca.render('https://example.com', {
  country: 'DE',
  viewport: { width: 1920, height: 1080 },
  full_page: true,
  format: 'png',
  stealth: true, // bypass Cloudflare (free)
  wait_for_selector: '#content', // wait for element before screenshot
});
console.log(result.title);       // page title
console.log(result.screenshot);  // data:image/png;base64,...
console.log(result.html_length); // rendered HTML size

| Option | Type | Description | |--------|------|-------------| | country | string | Exit country code | | server_id | string | Specific proxy server ID | | viewport | {width, height} | Viewport dimensions (default: 1280x720) | | full_page | boolean | Capture full scrollable page (default: false) | | format | string | Image format: png (default) or jpeg | | stealth | boolean | Stealth mode — bypass Cloudflare/bot detection (free) | | wait_for_selector | string | CSS selector to wait for before screenshot | | paymentSignature | string | Pre-made payment tx signature |

akca.crawl(url, options?)

Crawl a website by discovering pages via sitemap.xml or link extraction, then fetch them all through proxy.

const result = await akca.crawl('https://example.com', {
  max_pages: 20,
  extract: 'text',
  rotate: true,
});
console.log(result.pages_found);   // 20
console.log(result.pages_fetched); // 20
console.log(result.results);       // [{url, status, body, extracted}, ...]

| Option | Type | Description | |--------|------|-------------| | max_pages | number | Max pages to fetch (default 10, max 100) | | extract | string | Smart extract mode for all pages | | country | string | Exit country code | | rotate | boolean | IP rotation across crawl requests | | cookie_jar | string | Cookie jar ID for session persistence | | paymentSignature | string | Pre-made payment tx signature |

akca.createProxySession(options?)

Create a 24-hour unlimited proxy session (1.00 USDC).

await akca.createProxySession({ country: 'DE' });
// All subsequent fetch/batch/crawl calls use the session — no per-request payment

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 subscriber token

1. SDK sends request with Authorization: Bearer <accountToken>
2. API verifies subscription → returns response directly
3. No payment needed

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

Pricing

| Product | Tier | Price | |---------|------|-------| | Proxy | Single fetch | 0.001 USDC | | Proxy | Web search | 0.001 USDC | | Proxy | Batch fetch (up to 50 URLs) | 0.001 USDC | | Proxy | Page render / screenshot (stealth included) | 0.005 USDC | | Proxy | Sitemap crawl | 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