You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+5-3Lines changed: 5 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,6 +2,8 @@
2
2
3
3
**AI agents pay USDC on Base for private internet access through Sentinel's decentralized VPN network.**
4
4
5
+
Live at **[x402.sentinel.co](https://x402.sentinel.co)**.
6
+
5
7
One HTTP request. No KYC. No accounts. No P2P tokens. No custom contract to deploy. The agent signs an EIP-3009 USDC transfer, our facilitator settles it on Base, the server provisions a Sentinel subscription with a gas fee grant, and the agent connects to the VPN — paying zero gas.
6
8
7
9
```typescript
@@ -16,7 +18,7 @@ const client = new x402Client();
└── fresh-test/ — End-to-end tests against a live server
78
80
```
79
81
80
-
> **Note — `contracts/` and `api/`:** Earlier iterations of this project included a custom Solidity payment contract (`BlueVpnPayment.sol`) plus an event-watcher relayer in `api/`. That flow is **deprecated** in favor of the HTTP 402 + EIP-3009 design. The contract directory and `api/`watcher remain in the repo as historical reference only — do not deploy or run them. All current development happens in`server/`.
82
+
The `api/`, `contracts/`, and `sdk/` directories contain an earlier event-watcher design (custom payment contract + agentId registration + polling). The HTTP 402 + EIP-3009 flow in `server/`is the canonical implementation — it needs no contract, no event watcher, and no database, and auto-creates Sentinel subscriptions on demand. The live deployment at [x402.sentinel.co](https://x402.sentinel.co) runs`server/`.
> **This directory is deprecated and no longer used.**
4
-
>
5
-
> Earlier iterations of x402 used a custom Solidity payment contract (`contracts/base/BlueVpnPayment.sol`) plus this event-watcher relayer to bridge on-chain payments to Sentinel allocations. That design has been replaced by the HTTP 402 + EIP-3009 flow in `server/`, which uses native USDC `transferWithAuthorization` (no custom contract, no event watcher, no SQLite database).
6
-
>
7
-
> **Live implementation:**`server/` — see `server/README.md`.
8
-
>
9
-
> The contents below are kept only as historical reference. Do not run, deploy, or build against this code.
3
+
Event-watcher relayer that bridges on-chain Base payments to Sentinel allocations. Agents register off-chain to get an `agentId`, then call `BlueVpnPayment.pay(agentId, numDays)` on a custom contract; this service watches for the resulting `VpnPayment` event and provisions Sentinel access.
10
4
11
-
---
5
+
The canonical x402 implementation is `server/` — it uses HTTP 402 + EIP-3009 `transferWithAuthorization` instead, which needs no custom contract, no event watcher, no SQLite, and auto-creates Sentinel subscriptions on demand. The live deployment at [x402.sentinel.co](https://x402.sentinel.co) runs `server/`. This directory is an alternative implementation kept for the on-chain-event design.
12
6
13
-
## Historical Reference
7
+
## What it does
14
8
15
-
What this service used to do:
9
+
1.**Registers agents** — maps `agentId` to a Sentinel address
10
+
2.**Watches Base** — listens for `VpnPayment` events from `contracts/base/BlueVpnPayment.sol`
11
+
3.**Watches Solana** — listens for USDC transfers with x402 memo via Helius webhooks
12
+
4.**Provisions on Sentinel** — `MsgShareSubscription` + `MsgGrantAllowance` in one atomic TX
13
+
5.**Manages a subscription pool** — 8 allocations per subscription; operator pre-creates pool entries (no auto-create)
The current `server/` implementation does steps 4–6 directly from the HTTP 402 payment handler, with no event watching, no agentId registration, no SQLite, and no payment contract.
18
+
- Deployed `BlueVpnPayment` on Base (see `contracts/base/`)
19
+
-`PAYMENT_CONTRACT_ADDRESS`, `OPERATOR_EVM_ADDRESS`, `SENTINEL_OPERATOR_MNEMONIC`, `SENTINEL_PLAN_ID` in env
20
+
- Pre-populated subscription pool (call `db.insertSubscription(subId, planId)` after creating subs on-chain)
21
+
22
+
## Why `server/` instead
23
+
24
+
The on-chain-event design has more moving parts: a contract to deploy + maintain, an event watcher that must stay connected to a Base WS endpoint, an operator-managed subscription pool, and a SQLite store for payment state. The EIP-3009 design in `server/` collapses all of that into a single HTTP handler — the payment, settlement, and provisioning happen in one request/response cycle, with subscription auto-creation when the pool runs dry.
<spanclass="kw">const</span> res <spanclass="op">=</span><spanclass="kw">await</span><spanclass="fn">paidFetch</span>(<spanclass="str">'https://x402.blue/vpn/connect/30days'</span><spanclass="op">,</span> {
1407
+
<spanclass="kw">const</span> res <spanclass="op">=</span><spanclass="kw">await</span><spanclass="fn">paidFetch</span>(<spanclass="str">'https://x402.sentinel.co/vpn/connect/30days'</span><spanclass="op">,</span> {
<divclass="label">Check pricing (free, no payment)</div>
1508
1508
</div>
1509
-
<pre><code><spanclass="kw">const</span> res <spanclass="op">=</span><spanclass="kw">await</span><spanclass="fn">fetch</span>(<spanclass="str">'https://x402.blue/pricing'</span>)<spanclass="op">;</span>
1509
+
<pre><code><spanclass="kw">const</span> res <spanclass="op">=</span><spanclass="kw">await</span><spanclass="fn">fetch</span>(<spanclass="str">'https://x402.sentinel.co/pricing'</span>)<spanclass="op">;</span>
<spanclass="cm">// ── Step 3: Pay USDC on Base via x402 ──</span>
1701
-
<spanclass="kw">const</span> res <spanclass="op">=</span><spanclass="kw">await</span><spanclass="fn">paidFetch</span>(<spanclass="str">'https://x402.blue/vpn/connect/30days'</span><spanclass="op">,</span> {
1701
+
<spanclass="kw">const</span> res <spanclass="op">=</span><spanclass="kw">await</span><spanclass="fn">paidFetch</span>(<spanclass="str">'https://x402.sentinel.co/vpn/connect/30days'</span><spanclass="op">,</span> {
> **This package is deprecated and was never published.**
4
-
>
5
-
> The agent-facing flow it described (custom payment contract + agentId registration + polling API for allocation) has been replaced by the HTTP 402 + EIP-3009 flow.
6
-
>
7
-
> **Use these instead:**
8
-
>
9
-
> -**`@x402/fetch`** — wraps `fetch` to auto-sign EIP-3009 USDC transfers when a server returns HTTP 402
10
-
> -**`blue-agent-connect`** — establishes the actual Sentinel VPN tunnel (WireGuard / V2Ray) once the server has provisioned the subscription + fee grant
11
-
>
12
-
> See the root `README.md` for the current agent example, and `server/README.md` for the server side.
13
-
>
14
-
> The contents of this directory remain only as historical reference. Do not install, build, or publish.
3
+
Earlier sketch of an all-in-one agent client — a single `connect()` call that bundled payment, provisioning, and tunnel setup.
15
4
16
-
---
5
+
The live agent flow uses two composed packages instead:
17
6
18
-
## What replaced it
7
+
-**`@x402/fetch`** — wraps `fetch` to auto-sign EIP-3009 USDC transfers when a server returns HTTP 402
8
+
-**`blue-agent-connect`** — establishes the Sentinel VPN tunnel (WireGuard / V2Ray) once the server has provisioned the subscription + fee grant
19
9
20
-
Old (this directory):
10
+
See the root `README.md` for the current agent example, and `server/README.md` for the server side.
No payment contract. No agentId. No polling. The server settles the EIP-3009 USDC transfer, provisions Sentinel atomically, and returns the credentials in the HTTP 200 response.
45
+
No payment contract. No `agentId`. No polling. The server settles the EIP-3009 USDC transfer, provisions Sentinel atomically, and returns the credentials in the HTTP 200 response.
0 commit comments