Integrate the x402 managed flow
Let the x402 server handle everything with @x402/fetch — the agent pays USDC on Base and connects with one call, no P2P and no gas. Prefer the fully self-funded path where the agent pays nodes directly? That lives at autonomous.sentinel.co.
● x402 Managed Plan Flow — Live Now
Install — Managed plan (x402 handles everything)
npm install @x402/fetch @x402/evm blue-js-sdk viem
Step 0: Prerequisites — fund an EVM key with USDC on Base
// You need ONE thing: an EVM private key with >= $1.00 USDC on Base (chainId 8453).
// No ETH needed — EIP-3009 is gasless from the agent side (facilitator pays Base gas).
// No P2P needed — the operator fee-grants Sentinel gas after provisioning.
//
// How to fund a fresh EVM key with USDC on Base:
// * Coinbase / any CEX with Base withdrawals: withdraw USDC, pick "Base" as network.
// * Canonical bridge: bridge.base.org (ETH L1 → Base, ~10 min).
// * Third-party bridges: Across, Stargate (faster, small fee).
// * Already on Base? Swap ETH → USDC on Uniswap or Aerodrome.
//
// USDC contract on Base: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (6 decimals, native).
// Verify balance:
const bal = await fetch(`https://api.basescan.org/api?module=account&action=tokenbalance&contractaddress=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&address=${addr}`);
Step 1: Create Sentinel wallet + set up x402 payment client
import { x402Client, wrapFetchWithPayment } from '@x402/fetch';
import { ExactEvmScheme } from '@x402/evm/exact/client';
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';
import { setup, createWallet, connect, disconnect, rpcQueryNodesForPlan, createRpcQueryClientWithFallback } from 'blue-js-sdk/ai-path';
// Optional: pre-fetch V2Ray (no admin). connect({ protocol: 'v2ray' }) auto-fetches it anyway.
await setup();
// Create a Sentinel wallet (one-time — save the mnemonic!)
const wallet = await createWallet();
// wallet.address = 'sent1...' wallet.mnemonic = '12 words'
// Set up x402 payment client with your EVM key
const account = privateKeyToAccount(process.env.EVM_KEY);
const viemClient = createWalletClient({
account, chain: base, transport: http('https://mainnet.base.org'),
});
const scheme = new ExactEvmScheme({
address: account.address,
signTypedData: (msg) => viemClient.signTypedData(msg),
});
const client = new x402Client();
client.register('eip155:8453', scheme);
const paidFetch = wrapFetchWithPayment(fetch, client);
Step 2: Buy 30 days of VPN — Base mainnet
// Request VPN access — 402 → auto-sign → facilitator settles → provisioned
const res = await paidFetch('https://x402.sentinel.co/vpn/connect/30days', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ sentinelAddr: wallet.address, country: 'DE' }), // country optional — validated BEFORE payment
});
const provision = await res.json();
// {
// provisioned: true,
// subscriptionId: 1192288,
// planId: 42,
// feeGranter: 'sent12e03w...', ← operator pays all gas
// nodeAddress: 'sentnode1...', ← node matching country — or choose from nodes[]
// nodeCountry: 'Germany', ← verified location of nodeAddress
// nodes: ['sentnode1a...', ...], ← full list of plan nodes
// sentinelTxHash: 'F1FE3C...',
// expiresAt: '2026-05-14T...',
// }
Step 3 — Windows: connect via blue-js-sdk (JS tunnel)
// connect(), createWallet(), rpcQueryNodesForPlan(), createRpcQueryClientWithFallback()
// already imported above from 'blue-js-sdk/ai-path'
// Resolve node — server returns one, but fall back to a live plan query if empty
let nodeAddress = provision.nodeAddress;
if (!nodeAddress) {
const rpc = await createRpcQueryClientWithFallback();
const { items } = await rpcQueryNodesForPlan(rpc, provision.planId, { status: 1, limit: 50 });
nodeAddress = items[0]?.address;
}
// Connect using the provisioned subscription + fee grant
// Agent has 0 P2P tokens — operator covers all gas
const vpn = await connect({
mnemonic: wallet.mnemonic, // from Step 1
nodeAddress, // from provision or fallback query
subscriptionId: String(provision.subscriptionId), // from Step 2
feeGranter: provision.feeGranter, // operator pays gas
protocol: 'v2ray', // zero admin, zero manual install (Windows)
});
// vpn.ip is the exit IP verified THROUGH the tunnel by the SDK
console.log(`VPN active: ${vpn.ip} via ${vpn.protocol}`);
// { connected: true, ip: '104.234.x.x', protocol: 'v2ray',
// sessionId: '39269345', nodeAddress: 'sentnode1...',
// socksPort: 11375 } ← v2ray: route your traffic through THIS port (dynamic — never hardcode)
// Disconnect also uses fee grant — 0 tokens needed
await disconnect();
V2Ray routing — choose your scope
protocol: 'v2ray' runs a SOCKS5 proxy on vpn.socksPort. It can encrypt the entire device or only the requests you choose. Pick one:
- Whole device. Pass
systemProxy: true to connect(). The SDK sets the system proxy (Windows registry / macOS networksetup / Linux gsettings) and all traffic routes through the node. The original proxy is restored on disconnect().
- Per-request (split tunnel). Omit
systemProxy and send only the requests you choose through vpn.socksPort. Other traffic (chain, RPC, npm) stays direct and fast. Use socks5h:// (not socks5://) so DNS resolves at the exit node, preventing a DNS leak.
- WireGuard. Pass
protocol: 'wireguard' for a kernel-level full tunnel (admin once on Windows).
Two facts that catch agents: (1) For per-request routing, Node's native fetch() ignores SOCKS5 agents and exits on the real IP — use axios with SocksProxyAgent and adapter: 'http'. (2) socksPort is dynamic — read it from the connect() result, never hardcode it. vpn.ip is the exit IP, already verified through the tunnel by the SDK.
// Whole device — all traffic routes through the node, restored on disconnect():
const vpn = await connect({ mnemonic, nodeAddress, subscriptionId, feeGranter, protocol: 'v2ray', systemProxy: true });
// Per-request — route one call through the proxy. Use axios; native fetch() ignores SOCKS5.
import { SocksProxyAgent } from 'socks-proxy-agent';
import axios from 'axios';
const proxy = new SocksProxyAgent(`socks5h://127.0.0.1:${vpn.socksPort}`);
const res = await axios.get('https://api.ipify.org', {
httpAgent: proxy, httpsAgent: proxy, adapter: 'http',
}); // res.data === vpn.ip
Verified live (Windows). Split tunnel was tested end-to-end on a US V2Ray node (session 45984926): the axios+SocksProxyAgent request returned the exit IP 45.38.249.7 while a plain fetch() on the same machine still returned the host IP 67.169.16.153 — only the routed request changed IP, and the native fetch() footgun is real.
Step 3 — macOS & Linux: WireGuard via native CLI (optional)
// V2Ray works the SAME on macOS & Linux: the JS connect({ protocol: 'v2ray' }) above runs
// as-is (the binary auto-downloads for darwin/linux too). Use this CLI only for WireGuard
// nodes or Node-less environments. Payment (Steps 0-2) is identical. The CLI does NOT bundle
// a tunnel: it shells out to wg-quick, so install wireguard-tools first (apt/brew/pacman).
// CLI: https://github.com/sentinel-official/sentinel-dvpncli
// Install once (Go 1.24+):
// go install github.com/sentinel-official/sentinel-dvpncli@latest
// 1. Import the SAME wallet whose sentinelAddr (sent1...) you sent to x402.
// keys add is interactive: prompt 1 = mnemonic, prompt 2 = BIP-39 passphrase.
// printf feeds both (mnemonic line + blank line = default empty passphrase).
printf '%s\n\n' "$AGENT_MNEMONIC" | sentinel-dvpncli keys add agent --keyring.backend test
// 2. Start the session against the subscription x402 shared with you.
// --tx.fee-granter-addr = provision.feeGranter → operator pays the P2P gas (you pay 0).
sentinel-dvpncli tx session-start "$NODE_ADDRESS" \
--subscription-id "$SUBSCRIPTION_ID" \
--tx.fee-granter-addr "$FEE_GRANTER" \
--tx.from-name agent --keyring.backend test \
--rpc.chain-id sentinelhub-2 --output-format json
// 3. Get the session id you just created (session-start does not print it cleanly).
// AGENT_ADDR = the same sent1... you sent to x402. Newest entry is your session.
SESSION_ID=$(sentinel-dvpncli query sessions \
--account-addr "$AGENT_ADDR" --subscription-id "$SUBSCRIPTION_ID" \
--output-format json | jq '.result[-1].id // .response[-1].id')
// 4. Bring the tunnel up (takes the SESSION id, not the subscription id).
// WireGuard may need sudo to create the interface, same as any wg client.
sentinel-dvpncli connect "$SESSION_ID"
// → tunnel up. Tear down with: sentinel-dvpncli tx session-cancel "$SESSION_ID"
//
// Defaults: --rpc.addrs https://rpc.sentinel.co:443, --rpc.chain-id sentinelhub-2.
// Only exception across all platforms: Fedora (SELinux blocks VPN interfaces).
Under the hood — what x402 does for you
// 1. Agent sends POST /vpn/connect/30days
// → Server returns HTTP 402 + PAYMENT-REQUIRED header
//
// 2. @x402/fetch reads the 402 response:
// { scheme: 'exact', network: 'eip155:8453',
// amount: '1000000', asset: '0x8335...USDC',
// payTo: '0x605C...85B' }
//
// 3. Signs EIP-3009 transferWithAuthorization
// (USDC native, no approve needed)
//
// 4. Resends request with PAYMENT-SIGNATURE header
// → Facilitator verifies + settles USDC on Base
// → Server provisions agent on Sentinel chain
// → Returns { subscriptionId, feeGranter, expiresAt }
//
// 5. Agent calls connect({ mnemonic, nodeAddress: provision.nodeAddress, subscriptionId, feeGranter })
// → SDK validates fee grant on-chain (RPC, ~250ms)
// → Broadcasts MsgStartSession via broadcastWithFeeGrant
// → Handshakes with VPN node (WireGuard/V2Ray)
// → Tunnel established, IP changed
Error handling — fee grant pre-check errors
try {
const vpn = await connect({
mnemonic, nodeAddress, subscriptionId, feeGranter,
});
} catch (err) {
if (err.code === 'FEE_GRANT_NOT_FOUND') {
// No grant on-chain — request provisioning from x402 server
} else if (err.code === 'FEE_GRANT_EXPIRED') {
// Grant expired — re-purchase via /vpn/connect/*
} else if (err.code === 'FEE_GRANT_EXHAUSTED') {
// spend_limit too low (<20k udvpn) — re-provision
}
// err.nextAction tells the agent what to do programmatically
// err.details has { granter, grantee, ... } for debugging
}
Pricing & Discovery
Check pricing (free, no payment)
const res = await fetch('https://x402.sentinel.co/pricing');
const pricing = await res.json();
// {
// protocol: 'x402', network: 'eip155:8453', asset: 'USDC',
// payTo: '0xCC689D...',
// tiers: {
// '1day': { price: '$0.033', endpoint: '/vpn/connect/1day' },
// '7days': { price: '$0.233', endpoint: '/vpn/connect/7days' },
// '30days':{ price: '$1.00', endpoint: '/vpn/connect/30days' }
// },
// sentinelNetwork: 'sentinel', countries: '70+',
// protocols: ['wireguard', 'v2ray']
// }
// Minimum USDC needed: $0.033 for 1 day tier
Live on Base Mainnet