x402 Documentation

# Install Solana CLI (if not installed)
$ sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"

# Create a new keypair
$ solana-keygen new -o ~/akca-wallet.json

# View your public address
$ solana address -k ~/akca-wallet.json
FgTmb5SQnSyG16jFVwEnPZHDPZjgoTnsdmbCAAGCoCSL

# Get USDC on Solana mainnet via:

Option A: DEX
  Swap SOL → USDC on Jupiter (jup.ag) or Raydium

Option B: CEX
  Buy USDC on Coinbase/Binance, withdraw to Solana address

Option C: Bridge
  Bridge USDC from Ethereum/Polygon via Wormhole or Allbridge

# USDC contract on Solana:
EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

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

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

// Or from base58 private key string
import bs58 from 'bs58';
const wallet2 = Keypair.fromSecretKey(
  bs58.decode(process.env.SOLANA_PRIVATE_KEY)
);

$ npm install @akcanetwork/x402 @solana/web3.js @solana/spl-token

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,
  // baseUrl: 'https://api.akca.network' (default)
  // rpcUrl: 'https://api.mainnet-beta.solana.com' (default)
});

// Route a request through German exit node
const result = await akca.fetch(
  'https://api.example.com/data',
  { country: 'DE', method: 'GET' }
);

// SDK flow: request → 402 → auto-pay USDC → retry → 200
console.log(result.status); // 200
console.log(result.body); // response body

// Create 24h session — pay once, unlimited requests
await akca.createProxySession({ country: 'US' });

// All subsequent requests use the session cookie (no re-payment)
const r1 = await akca.fetch('https://site1.com'); // free
const r2 = await akca.fetch('https://site2.com'); // free
const r3 = await akca.fetch('https://site3.com'); // free

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

// Auto-install WireGuard + auto-pay + bring up tunnel
const vpn = await quickVpn({
  wallet,
  country: 'US',
  duration: '24h', // '24h' | '7d' | '30d'
});

// All system traffic now goes through VPN
// ...

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

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

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

// 1. Auto-install AmneziaWG/WireGuard if missing
await mgr.ensureInstalled();

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

// 3. Connect (auto-pays USDC)
const vpn = await akca.connectVpn({
  serverId: servers[0].id,
  duration: '24h'
});

// 4. vpn.config = full WireGuard config text
await mgr.up(vpn.config); // writes config + wg-quick up

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

{
  "mcpServers": {
    "akca": {
      "command": "npx",
      "args": ["-y", "@akcanetwork/mcp-server"],
      "env": {
        "SOLANA_KEYPAIR_PATH": "~/akca-wallet.json"
      }
    }
  }
}

akca_proxy_fetch
  Proxy any URL through Akca exit nodes
  Input: { url, method?, headers?, country? }
  Cost: 0.001 USDC/request (auto-paid)

akca_vpn_connect
  Start a VPN session, returns WireGuard config
  Input: { serverId, duration? }
  Cost: 0.50 USDC/24h (auto-paid)

akca_list_servers
  List available proxy/VPN exit countries
  Input: {}
  Cost: Free

# Step 1: Send request (will get 402)
$ curl -s -X POST https://api.akca.network/x402/proxy/fetch \
  -H "Content-Type: application/json" \
  -H "X-402-Client: true" \
  -d '{"url":"https://example.com"}'

# Response: 402 Payment Required
# { "accepts": [{ "payTo": "ATA...", "maxAmountRequired": "0.001", ... }] }

# Step 2: Send USDC transfer on Solana (your code)
# Transfer 0.001 USDC to the "payTo" ATA address
# Get the transaction signature

# Step 3: Retry with payment proof
$ curl -s -X POST https://api.akca.network/x402/proxy/fetch \
  -H "Content-Type: application/json" \
  -H "X-402-Client: true" \
  -H "X-PAYMENT: 5yNx3...txSignature" \
  -d '{"url":"https://example.com"}'

# Response: 200 OK + Set-Cookie: x402_session=...

async function smartBatch(urls, country) {
  if (urls.length < 500) {
    // Proxy: pay per request
    return Promise.all(
      urls.map(u => akca.fetch(u, { country }))
    );
  }

  // VPN: flat rate, use native fetch
  const vpn = await quickVpn({ wallet, country });
  const results = await Promise.all(
    urls.map(u => fetch(u)) // native fetch through tunnel
  );
  await vpn.disconnect();
  return results;
}