Integration
Two integration paths
Let the x402 server handle everything with @x402/fetch, or go fully autonomous with blue-js-sdk — both live now. Both give you private internet access through the same Sentinel network.
● 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';
// Fresh machine? setup() auto-downloads V2Ray (no admin) + checks WireGuard
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: Connect to VPN — use provisioned credentials
// 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
});
// All traffic now routes through encrypted P2P tunnel
console.log(`VPN active: ${vpn.ip} via ${vpn.protocol}`);
// { connected: true, ip: '104.234.x.x', protocol: 'wireguard',
// sessionId: '39269345', nodeAddress: 'sentnode1...' }
// Disconnect also uses fee grant — 0 tokens needed
await disconnect();
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
}
● Autonomous Flow — Live Now
Install — Autonomous flow (agent manages P2P + gas)
npm install blue-js-sdk
Connect to VPN — agent pays node directly
import { createWallet, connectDirect } from 'blue-js-sdk';
// Agent already holds P2P tokens (bought on MEXC by API — see Autonomous Path above)
const { wallet } = await createWallet(process.env.SENTINEL_MNEMONIC);
// Pick any Sentinel node — pay directly in P2P, full autonomy
const vpn = await connectDirect({
wallet,
country: 'US',
protocol: 'wireguard',
});
// {
// connected: true,
// ip: '185.xxx.xxx.xxx',
// country: 'US',
// node: 'sentnode1...',
// sessionId: '12345678',
// protocol: 'wireguard'
// }
Autonomous flow — what the agent manages
// The agent controls the full lifecycle:
//
// 1. Wallet: Agent creates & holds Sentinel keys (mnemonic)
// 2. Tokens: Agent holds P2P tokens (bought on MEXC by API)
// 3. Gas: Agent pays Sentinel gas (~0.01 P2P per transaction)
// 4. Node selection: Agent queries Sentinel nodes, picks by country/speed/price
// 5. Session: Agent starts/ends sessions, pays node at its per-GB / per-hour rate
// 6. Tunnel: Agent handshakes directly with VPN node (WireGuard/V2Ray)
//
// Zero middlemen. Zero trust required. Full autonomy. No x402 involved.
// All of this ships in blue-js-sdk today.
Both Flows
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