@one-source/api-mcp 3.0.0 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +42 -14
  2. package/README.npm.md +42 -14
  3. package/README.repo.md +42 -17
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -8,21 +8,35 @@ npx onesource-api-mcp
8
8
 
9
9
  ## Install
10
10
 
11
- ```sh
12
- # Claude Code
11
+ ### Claude Code
12
+
13
+ ```bash
13
14
  claude mcp add onesource-api -- npx onesource-api-mcp
14
15
 
15
- # Claude Desktop / Cursor — add to MCP config:
16
+ # With x402 payments
17
+ claude mcp add onesource-api -e X402_PRIVATE_KEY=0x... -- npx onesource-api-mcp
18
+ ```
19
+
20
+ ### Claude Desktop / Cursor
21
+
22
+ Add to your MCP config (`claude_desktop_config.json` or Cursor settings):
23
+
24
+ ```json
16
25
  {
17
26
  "mcpServers": {
18
27
  "onesource-api": {
19
28
  "command": "npx",
20
- "args": ["-y", "onesource-api-mcp"]
29
+ "args": ["-y", "onesource-api-mcp"],
30
+ "env": {
31
+ "X402_PRIVATE_KEY": "0x..."
32
+ }
21
33
  }
22
34
  }
23
35
  }
24
36
  ```
25
37
 
38
+ Remove the `env` block to run without payments.
39
+
26
40
  ## Tools (22)
27
41
 
28
42
 
@@ -73,23 +87,37 @@ All tools accept an optional `network` parameter:
73
87
 
74
88
  ## Payment (x402)
75
89
 
76
- Endpoints are priced in USDC on Base via [x402](https://github.com/coinbase/x402). When the backend has payments enabled, tool calls return a 402 with payment details.
90
+ Endpoints are priced in USDC on Base via [x402](https://github.com/coinbase/x402). When `X402_PRIVATE_KEY` is set, the server automatically signs and settles USDC payments for each tool call. Without it, paid endpoints return 402 errors with a descriptive message.
77
91
 
78
- **Automatic payments:** Set `X402_PRIVATE_KEY` to a funded EVM wallet key. The server will automatically sign and settle USDC payments for each tool call.
92
+ ### Getting a Private Key
79
93
 
80
- ```sh
81
- X402_PRIVATE_KEY=0x... npx onesource-api-mcp
94
+ `X402_PRIVATE_KEY` is an EVM wallet private key — the same kind used by MetaMask, Foundry, or any Ethereum wallet. It must be a hex string starting with `0x`.
95
+
96
+ **Option A — Export from MetaMask:**
97
+ 1. Open MetaMask → click the three dots → Account details → Show private key
98
+ 2. Copy the key (it starts with `0x`)
99
+
100
+ **Option B — Generate a new wallet:**
101
+ ```bash
102
+ # Using Foundry (cast)
103
+ cast wallet new
104
+
105
+ # Using OpenSSL
106
+ openssl rand -hex 32 | sed 's/^/0x/'
82
107
  ```
83
108
 
84
- Without this key, 402 responses are returned as tool errors with a descriptive message.
109
+ ### Funding the Wallet
85
110
 
111
+ The wallet needs **USDC on Base** to pay for tool calls. Send USDC to your wallet address on the Base network. Typical tool calls cost fractions of a cent.
86
112
 
87
- ## Configuration
113
+ ### Running with Payments
114
+
115
+ ```bash
116
+ # Inline
117
+ X402_PRIVATE_KEY=0x... npx onesource-api-mcp
118
+ ```
88
119
 
89
- | Variable | Default | Description |
90
- |----------|---------|-------------|
91
- | `ONESOURCE_BASE_URL` | `https://skills.onesource.io` | Skills API endpoint |
92
- | `X402_PRIVATE_KEY` | — | EVM private key (0x-prefixed hex) for automatic x402 USDC payments on Base |
120
+ Or configure the key in your MCP client's `env` block (see [Install](#install) above).
93
121
 
94
122
 
95
123
  ## License
package/README.npm.md CHANGED
@@ -8,21 +8,35 @@ npx onesource-api-mcp
8
8
 
9
9
  ## Install
10
10
 
11
- ```sh
12
- # Claude Code
11
+ ### Claude Code
12
+
13
+ ```bash
13
14
  claude mcp add onesource-api -- npx onesource-api-mcp
14
15
 
15
- # Claude Desktop / Cursor — add to MCP config:
16
+ # With x402 payments
17
+ claude mcp add onesource-api -e X402_PRIVATE_KEY=0x... -- npx onesource-api-mcp
18
+ ```
19
+
20
+ ### Claude Desktop / Cursor
21
+
22
+ Add to your MCP config (`claude_desktop_config.json` or Cursor settings):
23
+
24
+ ```json
16
25
  {
17
26
  "mcpServers": {
18
27
  "onesource-api": {
19
28
  "command": "npx",
20
- "args": ["-y", "onesource-api-mcp"]
29
+ "args": ["-y", "onesource-api-mcp"],
30
+ "env": {
31
+ "X402_PRIVATE_KEY": "0x..."
32
+ }
21
33
  }
22
34
  }
23
35
  }
24
36
  ```
25
37
 
38
+ Remove the `env` block to run without payments.
39
+
26
40
  ## Tools (22)
27
41
 
28
42
 
@@ -73,23 +87,37 @@ All tools accept an optional `network` parameter:
73
87
 
74
88
  ## Payment (x402)
75
89
 
76
- Endpoints are priced in USDC on Base via [x402](https://github.com/coinbase/x402). When the backend has payments enabled, tool calls return a 402 with payment details.
90
+ Endpoints are priced in USDC on Base via [x402](https://github.com/coinbase/x402). When `X402_PRIVATE_KEY` is set, the server automatically signs and settles USDC payments for each tool call. Without it, paid endpoints return 402 errors with a descriptive message.
77
91
 
78
- **Automatic payments:** Set `X402_PRIVATE_KEY` to a funded EVM wallet key. The server will automatically sign and settle USDC payments for each tool call.
92
+ ### Getting a Private Key
79
93
 
80
- ```sh
81
- X402_PRIVATE_KEY=0x... npx onesource-api-mcp
94
+ `X402_PRIVATE_KEY` is an EVM wallet private key — the same kind used by MetaMask, Foundry, or any Ethereum wallet. It must be a hex string starting with `0x`.
95
+
96
+ **Option A — Export from MetaMask:**
97
+ 1. Open MetaMask → click the three dots → Account details → Show private key
98
+ 2. Copy the key (it starts with `0x`)
99
+
100
+ **Option B — Generate a new wallet:**
101
+ ```bash
102
+ # Using Foundry (cast)
103
+ cast wallet new
104
+
105
+ # Using OpenSSL
106
+ openssl rand -hex 32 | sed 's/^/0x/'
82
107
  ```
83
108
 
84
- Without this key, 402 responses are returned as tool errors with a descriptive message.
109
+ ### Funding the Wallet
85
110
 
111
+ The wallet needs **USDC on Base** to pay for tool calls. Send USDC to your wallet address on the Base network. Typical tool calls cost fractions of a cent.
86
112
 
87
- ## Configuration
113
+ ### Running with Payments
114
+
115
+ ```bash
116
+ # Inline
117
+ X402_PRIVATE_KEY=0x... npx onesource-api-mcp
118
+ ```
88
119
 
89
- | Variable | Default | Description |
90
- |----------|---------|-------------|
91
- | `ONESOURCE_BASE_URL` | `https://skills.onesource.io` | Skills API endpoint |
92
- | `X402_PRIVATE_KEY` | — | EVM private key (0x-prefixed hex) for automatic x402 USDC payments on Base |
120
+ Or configure the key in your MCP client's `env` block (see [Install](#install) above).
93
121
 
94
122
 
95
123
  ## License
package/README.repo.md CHANGED
@@ -8,21 +8,35 @@ npx onesource-api-mcp
8
8
 
9
9
  ## Install
10
10
 
11
- ```sh
12
- # Claude Code
11
+ ### Claude Code
12
+
13
+ ```bash
13
14
  claude mcp add onesource-api -- npx onesource-api-mcp
14
15
 
15
- # Claude Desktop / Cursor — add to MCP config:
16
+ # With x402 payments
17
+ claude mcp add onesource-api -e X402_PRIVATE_KEY=0x... -- npx onesource-api-mcp
18
+ ```
19
+
20
+ ### Claude Desktop / Cursor
21
+
22
+ Add to your MCP config (`claude_desktop_config.json` or Cursor settings):
23
+
24
+ ```json
16
25
  {
17
26
  "mcpServers": {
18
27
  "onesource-api": {
19
28
  "command": "npx",
20
- "args": ["-y", "onesource-api-mcp"]
29
+ "args": ["-y", "onesource-api-mcp"],
30
+ "env": {
31
+ "X402_PRIVATE_KEY": "0x..."
32
+ }
21
33
  }
22
34
  }
23
35
  }
24
36
  ```
25
37
 
38
+ Remove the `env` block to run without payments.
39
+
26
40
  ## Tools (22)
27
41
 
28
42
 
@@ -73,26 +87,37 @@ All tools accept an optional `network` parameter:
73
87
 
74
88
  ## Payment (x402)
75
89
 
76
- Endpoints are priced in USDC on Base via [x402](https://github.com/coinbase/x402). When the backend has payments enabled, tool calls return a 402 with payment details.
90
+ Endpoints are priced in USDC on Base via [x402](https://github.com/coinbase/x402). When `X402_PRIVATE_KEY` is set, the server automatically signs and settles USDC payments for each tool call. Without it, paid endpoints return 402 errors with a descriptive message.
77
91
 
78
- **Automatic payments:** Set `X402_PRIVATE_KEY` to a funded EVM wallet key. The server will automatically sign and settle USDC payments for each tool call.
92
+ ### Getting a Private Key
79
93
 
80
- ```sh
81
- X402_PRIVATE_KEY=0x... npx onesource-api-mcp
94
+ `X402_PRIVATE_KEY` is an EVM wallet private key — the same kind used by MetaMask, Foundry, or any Ethereum wallet. It must be a hex string starting with `0x`.
95
+
96
+ **Option A — Export from MetaMask:**
97
+ 1. Open MetaMask → click the three dots → Account details → Show private key
98
+ 2. Copy the key (it starts with `0x`)
99
+
100
+ **Option B — Generate a new wallet:**
101
+ ```bash
102
+ # Using Foundry (cast)
103
+ cast wallet new
104
+
105
+ # Using OpenSSL
106
+ openssl rand -hex 32 | sed 's/^/0x/'
82
107
  ```
83
108
 
84
- Without this key, 402 responses are returned as tool errors with a descriptive message.
109
+ ### Funding the Wallet
85
110
 
111
+ The wallet needs **USDC on Base** to pay for tool calls. Send USDC to your wallet address on the Base network. Typical tool calls cost fractions of a cent.
86
112
 
87
- ## Configuration
113
+ ### Running with Payments
114
+
115
+ ```bash
116
+ # Inline
117
+ X402_PRIVATE_KEY=0x... npx onesource-api-mcp
118
+ ```
88
119
 
89
- | Variable | Default | Description |
90
- |----------|---------|-------------|
91
- | `ONESOURCE_BASE_URL` | `https://skills.onesource.io` | Skills API endpoint |
92
- | `X402_PRIVATE_KEY` | — | EVM private key (0x-prefixed hex) for automatic x402 USDC payments on Base |
93
- | `ONESOURCE_ANALYTICS` | `true` | Set `false` to disable all analytics |
94
- | `ONESOURCE_ANALYTICS_URL` | `https://1s-analytics.vercel.app` | Dashboard endpoint for event ingestion (baked in by default) |
95
- | `X402_ANALYTICS_KEY` | `onesource-api-mcp` | Bearer token for the analytics dashboard (baked in by default) |
120
+ Or configure the key in your MCP client's `env` block (see [Install](#install) above).
96
121
 
97
122
  ## Transport Modes
98
123
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@one-source/api-mcp",
3
- "version": "3.0.0",
3
+ "version": "3.1.0",
4
4
  "type": "module",
5
5
  "description": "MCP server for OneSource blockchain data — 22 named tools for balances, NFTs, transactions, events, and live chain queries via x402",
6
6
  "bin": {