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';
// 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)
});
// 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: 'v2ray',
// sessionId: '39269345', nodeAddress: 'sentnode1...' }
// Disconnect also uses fee grant — 0 tokens needed
await disconnect();
Step 3 — macOS & Linux: connect via native CLI
// Payment (Steps 0-2 above) is identical. macOS & Linux skip the JS connect()
// and use Sentinel's native CLI instead. Unlike Windows, the CLI does NOT bundle a tunnel:
// it shells out to wg-quick, so install wireguard-tools first (apt/brew/pacman). Four commands.
// 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
}
● Autonomous Flow — Live Now
Install — Autonomous flow (agent manages P2P + gas)
npm install blue-js-sdk
Connect to VPN — agent pays the node directly
import { connect, disconnect, getBalance } from 'blue-js-sdk/ai-path';
// Agent already holds P2P (bought on MEXC by API — see Autonomous Path above).
// getBalance → { address, udvpn, p2p, sufficient }
const bal = await getBalance(process.env.SENTINEL_MNEMONIC);
// Pick any Sentinel node and pay it directly in P2P. No x402, no operator.
// protocol: 'v2ray' = zero admin on Windows; the binary auto-downloads (~70% of nodes).
// Omit country to let the SDK pick the best node anywhere; pass nodeAddress to pin one.
const vpn = await connect({
mnemonic: process.env.SENTINEL_MNEMONIC, // agent holds its own keys
country: 'US', // optional — or { nodeAddress: 'sentnode1...' }
protocol: 'v2ray', // 'v2ray' (zero admin) or 'wireguard' (full route, admin once)
gigabytes: 1, // default 1 — pay per-GB; or { preferHourly: true, hours: 24 }
});
// vpn → {
// sessionId: '45433200', // on-chain session, paid by the agent
// protocol: 'v2ray',
// nodeAddress: 'sentnode1qjy6h...',
// ip: '104.252.19.187', // exit IP, verified THROUGH the tunnel by the SDK
// socksPort: 1080, // V2Ray: route traffic through this SOCKS5 port
// }
// ...do work over the tunnel...
await disconnect(); // soft: session preserved on-chain, unused GB stays available
⚠️ V2Ray routes through a SOCKS5 proxy, not the whole system
WireGuard captures all system traffic, so your public IP changes the moment it connects. V2Ray is a userspace SOCKS5 proxy — only traffic you point at vpn.socksPort goes through the node. A plain fetch() on the OS default route still shows your real IP, and that is expected, not a failure. The SDK already proves routing for you in vpn.ip (checked through the tunnel). Use vpn.socksPort with a SOCKS agent, or pick protocol: 'wireguard' for transparent system-wide routing.
Autonomous flow — what the agent manages
// The agent controls the full lifecycle — no x402, no operator:
//
// 1. Wallet: Agent creates & holds its Sentinel keys (mnemonic)
// 2. Tokens: Agent holds P2P (bought on MEXC by API — step zero above)
// 3. Gas: Agent pays its own Sentinel gas (bundled into the session TX)
// 4. Node: Agent queries nodes, picks by country / speed / price
// 5. Session: Agent starts & ends sessions, paying the node at its
// posted per-GB or per-hour rate — ~40 P2P buys 1 GB
// at the live median (cheapest nodes ~2 P2P/GB)
// 6. Tunnel: Agent handshakes directly with the node (WireGuard / V2Ray)
//
// connect() registers cleanup handlers automatically — on crash or exit it
// tears the tunnel down so a dropped process never strands your connection.
//
// Zero middlemen. Zero trust required. Full autonomy. 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
