Skip to content

Commit b8f7d45

Browse files
tenequmtenequm
committed
chore(release): bump to 0.4.2, add skills and changelog to npm package
- Fix twitter endpoint URLs from /user/ to /users/ to match spec change - Include CHANGELOG.md and skills/ (SKILL.md + library reference) in npm package - Symlink skills/x402-proxy at repo root to packages/x402-proxy/skills/ - Add SKILL.md to release checklist in CLAUDE.md
1 parent 9a1b669 commit b8f7d45

7 files changed

Lines changed: 247 additions & 4 deletions

File tree

‎.claude/CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ pnpm build # clean + tsdown --publint (via Turbo)
7070
- [ ] `CHANGELOG.md` updated: new `## [<version>] - YYYY-MM-DD` section with all changes since last release
7171
- [ ] `CHANGELOG.md` comparison links updated at bottom of file
7272
- [ ] README.md reflects any command/feature changes
73+
- [ ] `skills/x402-proxy/SKILL.md` reflects any command/feature/URL changes (symlinked into npm package)
7374
- [ ] No stale version strings anywhere in source (grep for old version number)
7475

7576
### Release steps

‎packages/x402-proxy/CHANGELOG.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
## [0.4.2] - 2026-03-16
11+
12+
### Fixed
13+
- Twitter endpoint URLs updated from `/user/` to `/users/` to match spec change
14+
15+
### Added
16+
- CHANGELOG.md included in npm package metadata
17+
- `skills/` directory with SKILL.md and library reference included in npm package
18+
1019
## [0.4.1] - 2026-03-13
1120

1221
### Changed
@@ -120,7 +129,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
120129
- `appendHistory` / `readHistory` / `calcSpend` - JSONL transaction history
121130
- Re-exports from `@x402/fetch`, `@x402/svm`, `@x402/evm`
122131

123-
[Unreleased]: https://github.com/cascade-protocol/x402-proxy/compare/v0.4.1...HEAD
132+
[Unreleased]: https://github.com/cascade-protocol/x402-proxy/compare/v0.4.2...HEAD
133+
[0.4.2]: https://github.com/cascade-protocol/x402-proxy/compare/v0.4.1...v0.4.2
124134
[0.4.1]: https://github.com/cascade-protocol/x402-proxy/compare/v0.4.0...v0.4.1
125135
[0.4.0]: https://github.com/cascade-protocol/x402-proxy/compare/v0.3.2...v0.4.0
126136
[0.3.2]: https://github.com/cascade-protocol/x402-proxy/compare/v0.3.1...v0.3.2

‎packages/x402-proxy/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
## Quick Start
66

77
```bash
8-
npx x402-proxy https://twitter.surf.cascade.fyi/user/cascade_fyi
8+
npx x402-proxy https://twitter.surf.cascade.fyi/users/cascade_fyi
99
```
1010

1111
That's it. The endpoint returns 402, x402-proxy pays and streams the response.
@@ -38,7 +38,7 @@ Works like curl. Response body streams to stdout, payment info goes to stderr.
3838

3939
```bash
4040
# GET request
41-
$ npx x402-proxy https://twitter.surf.cascade.fyi/user/cascade_fyi
41+
$ npx x402-proxy https://twitter.surf.cascade.fyi/users/cascade_fyi
4242

4343
# POST with body and headers
4444
$ npx x402-proxy --method POST \

‎packages/x402-proxy/package.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "x402-proxy",
3-
"version": "0.4.1",
3+
"version": "0.4.2",
44
"description": "curl for x402 paid APIs. Auto-pays any endpoint on Base and Solana.",
55
"type": "module",
66
"sideEffects": false,
@@ -55,6 +55,8 @@
5555
"files": [
5656
"dist/**",
5757
"README.md",
58+
"CHANGELOG.md",
59+
"skills/**",
5860
"LICENSE"
5961
],
6062
"keywords": [

‎packages/x402-proxy/skills/SKILL.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
name: x402-proxy
3+
description: Use x402-proxy CLI for consuming and debugging x402 paid APIs. Use this skill when testing x402 endpoints, configuring MCP payment proxies for AI agents, managing x402 wallets, or scripting paid HTTP requests. Triggers on x402-proxy, npx x402-proxy, x402 endpoint testing, paid API debugging, MCP payment proxy, x402 wallet management, or any mention of auto-paying HTTP 402 responses.
4+
---
5+
6+
# x402-proxy
7+
8+
`curl` for x402 paid APIs. Auto-pays HTTP 402 responses with USDC on Base and Solana.
9+
10+
## Quick start
11+
12+
```bash
13+
npx x402-proxy https://twitter.surf.cascade.fyi/users/cascade_fyi
14+
```
15+
16+
First run auto-creates a wallet. No setup needed.
17+
18+
## HTTP requests
19+
20+
```bash
21+
# GET - body to stdout, payment info to stderr
22+
npx x402-proxy https://api.example.com/resource
23+
24+
# POST with body and headers
25+
npx x402-proxy --method POST \
26+
--header "Content-Type: application/json" \
27+
--body '{"query":"example"}' \
28+
https://api.example.com/search
29+
30+
# Force a specific chain
31+
npx x402-proxy --network solana https://api.example.com/data
32+
33+
# Pipe-safe - only response body on stdout
34+
npx x402-proxy https://api.example.com/data | jq '.results'
35+
36+
# Save response to file
37+
npx x402-proxy https://api.example.com/data > response.json
38+
```
39+
40+
## Commands
41+
42+
```
43+
x402-proxy <url> # paid HTTP request (default)
44+
x402-proxy mcp <url> # MCP stdio proxy for AI agents
45+
x402-proxy setup # wallet onboarding wizard
46+
x402-proxy setup --force # re-run setup (overwrite existing wallet)
47+
x402-proxy status # config + wallet + daily spend summary
48+
x402-proxy wallet # show addresses and USDC balances
49+
x402-proxy wallet history # payment log
50+
x402-proxy wallet history --limit 5 # last 5 payments
51+
x402-proxy wallet history --json # machine-readable output
52+
x402-proxy wallet export-key evm # bare EVM private key to stdout
53+
x402-proxy wallet export-key solana # bare Solana private key to stdout
54+
x402-proxy wallet export-key mnemonic # bare mnemonic to stdout
55+
```
56+
57+
## Fetch flags
58+
59+
```
60+
--method, -X <METHOD> HTTP method (default: GET)
61+
--header, -H <KEY:VALUE> Add request header (repeatable)
62+
--body, -d <DATA> Request body (string or @file)
63+
--network <base|solana> Force payment on this chain
64+
```
65+
66+
## MCP proxy for AI agents
67+
68+
Drop into Claude, Cursor, or any MCP client config:
69+
70+
```json
71+
{
72+
"mcpServers": {
73+
"paid-service": {
74+
"command": "npx",
75+
"args": ["x402-proxy", "mcp", "https://mcp.example.com/sse"],
76+
"env": {
77+
"X402_PROXY_WALLET_MNEMONIC": "your 24 words here"
78+
}
79+
}
80+
}
81+
}
82+
```
83+
84+
The proxy intercepts 402 responses, pays automatically, forwards the result. Supports StreamableHTTP and SSE.
85+
86+
## Wallet & env vars
87+
88+
One BIP-39 mnemonic derives both Solana and EVM keypairs. Auto-detects which chain based on USDC balance.
89+
90+
```
91+
X402_PROXY_WALLET_MNEMONIC # BIP-39 mnemonic (derives both chains)
92+
X402_PROXY_WALLET_EVM_KEY # EVM private key (hex, 0x optional)
93+
X402_PROXY_WALLET_SOLANA_KEY # Solana private key (base58 or JSON array)
94+
```
95+
96+
Resolution: flags > env vars > mnemonic env > `~/.config/x402-proxy/wallet.json`
97+
98+
Pipe-safe export for scripting:
99+
100+
```bash
101+
MY_KEY=$(npx x402-proxy wallet export-key evm)
102+
MY_MNEMONIC=$(npx x402-proxy wallet export-key mnemonic)
103+
```
104+
105+
## Config
106+
107+
Lives at `~/.config/x402-proxy/` (or `$XDG_CONFIG_HOME/x402-proxy/`):
108+
109+
```yaml
110+
# config.yaml
111+
defaultNetwork: base # or "solana"
112+
spendLimitDaily: 10 # USDC daily cap
113+
spendLimitPerTx: 1 # USDC per-request cap
114+
```
115+
116+
Also supports JSONC and JSON config files. Wallet stored in `wallet.json` (mode 0600), payments logged to `history.jsonl`.
117+
118+
## Testing & debugging x402 services
119+
120+
```bash
121+
# Smoke test an endpoint
122+
npx x402-proxy https://your-service.com/paid-route
123+
124+
# Test both chains
125+
npx x402-proxy --network base https://your-service.com/route
126+
npx x402-proxy --network solana https://your-service.com/route
127+
128+
# Batch test
129+
for route in /users/test /tweets/search /v1/crawl; do
130+
echo "--- $route ---"
131+
npx x402-proxy "https://your-service.com$route" 2>/dev/null | head -c 200
132+
echo
133+
done
134+
135+
# Check what you spent
136+
npx x402-proxy wallet history --limit 5
137+
npx x402-proxy status
138+
```
139+
140+
stdout = response body, stderr = payment info. Pipes, redirects, and `jq` all work cleanly.
141+
142+
## Library API
143+
144+
For programmatic use in Node.js apps, read `references/library.md`.

‎packages/x402-proxy/skills/references/library.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# x402-proxy Library API
2+
3+
```bash
4+
npm install x402-proxy
5+
```
6+
7+
## Exports
8+
9+
```typescript
10+
// Core
11+
import { createX402ProxyHandler, extractTxSignature } from "x402-proxy";
12+
import { x402Client } from "x402-proxy";
13+
14+
// Chain schemes
15+
import { ExactEvmScheme, toClientEvmSigner } from "x402-proxy";
16+
import { ExactSvmScheme } from "x402-proxy";
17+
18+
// Wallet loaders
19+
import { loadEvmWallet, loadSvmWallet } from "x402-proxy";
20+
21+
// History
22+
import { appendHistory, readHistory, calcSpend, explorerUrl, formatTxLine } from "x402-proxy";
23+
```
24+
25+
## EVM (Base) setup
26+
27+
```typescript
28+
import { createX402ProxyHandler, x402Client, ExactEvmScheme, toClientEvmSigner } from "x402-proxy";
29+
import { createWalletClient, http } from "viem";
30+
import { privateKeyToAccount } from "viem/accounts";
31+
import { base } from "viem/chains";
32+
33+
const account = privateKeyToAccount(process.env.EVM_KEY as `0x${string}`);
34+
const wallet = createWalletClient({ account, chain: base, transport: http() });
35+
36+
const client = x402Client(fetch)
37+
.register(new ExactEvmScheme(toClientEvmSigner(wallet)));
38+
39+
const { x402Fetch, shiftPayment } = createX402ProxyHandler({ x402Client: client });
40+
41+
const res = await x402Fetch("https://api.example.com/data");
42+
const body = await res.json();
43+
const payment = shiftPayment(); // { network, payTo, amount, asset }
44+
```
45+
46+
## Solana setup
47+
48+
```typescript
49+
import { createX402ProxyHandler, x402Client, ExactSvmScheme, loadSvmWallet } from "x402-proxy";
50+
51+
const signer = loadSvmWallet(process.env.MNEMONIC!);
52+
const client = x402Client(fetch).register(new ExactSvmScheme(signer));
53+
const { x402Fetch } = createX402ProxyHandler({ x402Client: client });
54+
```
55+
56+
## Payment history
57+
58+
```typescript
59+
import { appendHistory, readHistory, calcSpend } from "x402-proxy";
60+
61+
// Read and summarize
62+
const records = await readHistory("./history.jsonl");
63+
const { dailyUsd, totalUsd, txCount } = calcSpend(records);
64+
65+
// Append a record
66+
await appendHistory("./history.jsonl", {
67+
ts: Date.now(),
68+
status: 200,
69+
network: "eip155:8453",
70+
payTo: "0x...",
71+
amount: "0.001",
72+
asset: "USDC",
73+
txId: "0xabc...",
74+
host: "api.example.com",
75+
});
76+
```
77+
78+
## Types
79+
80+
```typescript
81+
type PaymentInfo = { network: string; payTo: string; amount: string; asset: string };
82+
type X402ProxyOptions = { x402Client: ReturnType<typeof x402Client> };
83+
type X402ProxyHandler = { x402Fetch: typeof fetch; shiftPayment: () => PaymentInfo | undefined };
84+
type TxRecord = { ts: number; status: number; network: string; payTo: string; amount: string; asset: string; txId?: string; host: string };
85+
```

‎skills/x402-proxy‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../packages/x402-proxy/skills

0 commit comments

Comments
 (0)