@one-source/api-mcp 4.0.0 → 5.0.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 BlockParty
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 BlockParty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,97 +1,125 @@
-# onesource-api-mcp
-
-MCP server for OneSource blockchain data. 22 named tools for balances, NFTs, transactions, events, and live chain queries via x402 micropayments.
-
-```
-npx onesource-api-mcp
-```
-
-## Install
-
-```sh
-# Claude Code
-claude mcp add onesource-api -- npx onesource-api-mcp
-
-# Claude Desktop / Cursor — add to MCP config:
-{
-  "mcpServers": {
-    "onesource-api": {
-      "command": "npx",
-      "args": ["-y", "onesource-api-mcp"]
-    }
-  }
-}
-```
-
-## Tools (22)
-
-
-### Live Chain Data (12 tools)
-
-| Tool | Description |
-|------|-------------|
-| `1s_allowance_live` | ERC20 allowance check |
-| `1s_contract_info_live` | Contract type detection via ERC165 |
-| `1s_erc1155_balance_live` | ERC1155 balance via RPC |
-| `1s_erc20_balance_live` | ERC20 balance via balanceOf |
-| `1s_erc20_transfers_live` | ERC20 Transfer logs via eth_getLogs |
-| `1s_erc721_tokens_live` | ERC721 token enumeration |
-| `1s_events_live` | Event logs via eth_getLogs |
-| `1s_multi_balance_live` | ETH + multiple ERC20 balances |
-| `1s_nft_metadata_live` | NFT metadata via tokenURI |
-| `1s_nft_owner_live` | NFT owner via ownerOf |
-| `1s_total_supply_live` | Token total supply |
-| `1s_tx_details_live` | Transaction + receipt via RPC |
-
-
-### Chain Utilities (10 tools)
-
-| Tool | Description |
-|------|-------------|
-| `1s_contract_code` | Contract bytecode |
-| `1s_ens_resolve` | ENS name/address resolution |
-| `1s_estimate_gas` | Gas estimation |
-| `1s_network_info` | Chain ID, block number, gas price |
-| `1s_nonce` | Transaction count |
-| `1s_pending_block` | Pending block from mempool |
-| `1s_proxy_detect` | Proxy contract detection |
-| `1s_simulate_call` | Simulate eth_call |
-| `1s_storage_read` | Read storage slot |
-| `1s_tx_receipt` | Transaction receipt |
-
-
-## Networks
-
-All tools accept an optional `network` parameter:
-
-| Network | Description |
-|---------|-------------|
-| `ethereum` | Ethereum mainnet (default) |
-| `sepolia` | Ethereum Sepolia testnet |
-| `avax` | Avalanche C-Chain |
-
-
-## Payment (x402)
-
-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.
-
-**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.
-
-```sh
-X402_PRIVATE_KEY=0x... npx onesource-api-mcp
-```
-
-Without this key, 402 responses are returned as tool errors with a descriptive message.
-
-
-## Configuration
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `ONESOURCE_BASE_URL` | `https://skills.onesource.io` | Skills API endpoint |
-| `X402_PRIVATE_KEY` | — | EVM private key (0x-prefixed hex) for automatic x402 USDC payments on Base |
-
-
-## License
-
-MIT
+# onesource-api-mcp
+
+MCP server for OneSource blockchain data. 22 named tools for balances, NFTs, transactions, events, and live chain queries via API key or x402 micropayments.
+
+```
+npx onesource-api-mcp
+```
+
+## Install
+
+```sh
+# Claude Code
+claude mcp add onesource-api -- npx onesource-api-mcp
+
+# Claude Desktop / Cursor — add to MCP config:
+{
+  "mcpServers": {
+    "onesource-api": {
+      "command": "npx",
+      "args": ["-y", "onesource-api-mcp"]
+    }
+  }
+}
+```
+
+## Tools (22)
+
+
+### Live Chain Data (12 tools)
+
+| Tool | Description |
+|------|-------------|
+| `1s_allowance_live` | ERC20 allowance check |
+| `1s_contract_info_live` | Contract type detection via ERC165 |
+| `1s_erc1155_balance_live` | ERC1155 balance via RPC |
+| `1s_erc20_balance_live` | ERC20 balance via balanceOf |
+| `1s_erc20_transfers_live` | ERC20 Transfer logs via eth_getLogs |
+| `1s_erc721_tokens_live` | ERC721 token enumeration |
+| `1s_events_live` | Event logs via eth_getLogs |
+| `1s_multi_balance_live` | ETH + multiple ERC20 balances |
+| `1s_nft_metadata_live` | NFT metadata via tokenURI |
+| `1s_nft_owner_live` | NFT owner via ownerOf |
+| `1s_total_supply_live` | Token total supply |
+| `1s_tx_details_live` | Transaction + receipt via RPC |
+
+
+### Chain Utilities (10 tools)
+
+| Tool | Description |
+|------|-------------|
+| `1s_contract_code` | Contract bytecode |
+| `1s_ens_resolve` | ENS name/address resolution |
+| `1s_estimate_gas` | Gas estimation |
+| `1s_network_info` | Chain ID, block number, gas price |
+| `1s_nonce` | Transaction count |
+| `1s_pending_block` | Pending block from mempool |
+| `1s_proxy_detect` | Proxy contract detection |
+| `1s_simulate_call` | Simulate eth_call |
+| `1s_storage_read` | Read storage slot |
+| `1s_tx_receipt` | Transaction receipt |
+
+
+## Networks
+
+All tools accept an optional `network` parameter:
+
+| Network | Description |
+|---------|-------------|
+| `ethereum` | Ethereum mainnet (default) |
+| `sepolia` | Ethereum Sepolia testnet |
+| `avax` | Avalanche C-Chain |
+
+
+## Authentication
+
+Two auth methods are supported. **API key takes priority** when both are configured.
+
+### API Key (recommended)
+
+Set `ONESOURCE_API_KEY` to your OneSource API key. The server sends it as a Bearer token on every request.
+
+```sh
+ONESOURCE_API_KEY=your-key-here npx onesource-api-mcp
+```
+
+Or in your MCP config:
+```json
+{
+  "mcpServers": {
+    "onesource-api": {
+      "command": "npx",
+      "args": ["-y", "onesource-api-mcp"],
+      "env": {
+        "ONESOURCE_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+### x402 Micropayments
+
+Set `X402_PRIVATE_KEY` to a funded EVM wallet key. The server automatically signs and settles USDC payments on Base via [x402](https://github.com/coinbase/x402).
+
+```sh
+X402_PRIVATE_KEY=your-private-key-hex npx onesource-api-mcp
+```
+
+### No auth
+
+Without either variable, tools work for free endpoints. Paid endpoints return 402 errors with a descriptive message.
+
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ONESOURCE_API_KEY` | — | OneSource API key. Sent as `Authorization: Bearer <key>`. Takes priority over x402. |
+| `ONESOURCE_BASE_URL` | `https://skills.onesource.io` | Skills API endpoint |
+| `X402_PRIVATE_KEY` | — | EVM private key (hex, with or without 0x prefix) for automatic x402 USDC payments on Base |
+
+
+## License
+
+MIT

package/README.npm.md

@@ -1,97 +1,125 @@
-# onesource-api-mcp
-
-MCP server for OneSource blockchain data. 22 named tools for balances, NFTs, transactions, events, and live chain queries via x402 micropayments.
-
-```
-npx onesource-api-mcp
-```
-
-## Install
-
-```sh
-# Claude Code
-claude mcp add onesource-api -- npx onesource-api-mcp
-
-# Claude Desktop / Cursor — add to MCP config:
-{
-  "mcpServers": {
-    "onesource-api": {
-      "command": "npx",
-      "args": ["-y", "onesource-api-mcp"]
-    }
-  }
-}
-```
-
-## Tools (22)
-
-
-### Live Chain Data (12 tools)
-
-| Tool | Description |
-|------|-------------|
-| `1s_allowance_live` | ERC20 allowance check |
-| `1s_contract_info_live` | Contract type detection via ERC165 |
-| `1s_erc1155_balance_live` | ERC1155 balance via RPC |
-| `1s_erc20_balance_live` | ERC20 balance via balanceOf |
-| `1s_erc20_transfers_live` | ERC20 Transfer logs via eth_getLogs |
-| `1s_erc721_tokens_live` | ERC721 token enumeration |
-| `1s_events_live` | Event logs via eth_getLogs |
-| `1s_multi_balance_live` | ETH + multiple ERC20 balances |
-| `1s_nft_metadata_live` | NFT metadata via tokenURI |
-| `1s_nft_owner_live` | NFT owner via ownerOf |
-| `1s_total_supply_live` | Token total supply |
-| `1s_tx_details_live` | Transaction + receipt via RPC |
-
-
-### Chain Utilities (10 tools)
-
-| Tool | Description |
-|------|-------------|
-| `1s_contract_code` | Contract bytecode |
-| `1s_ens_resolve` | ENS name/address resolution |
-| `1s_estimate_gas` | Gas estimation |
-| `1s_network_info` | Chain ID, block number, gas price |
-| `1s_nonce` | Transaction count |
-| `1s_pending_block` | Pending block from mempool |
-| `1s_proxy_detect` | Proxy contract detection |
-| `1s_simulate_call` | Simulate eth_call |
-| `1s_storage_read` | Read storage slot |
-| `1s_tx_receipt` | Transaction receipt |
-
-
-## Networks
-
-All tools accept an optional `network` parameter:
-
-| Network | Description |
-|---------|-------------|
-| `ethereum` | Ethereum mainnet (default) |
-| `sepolia` | Ethereum Sepolia testnet |
-| `avax` | Avalanche C-Chain |
-
-
-## Payment (x402)
-
-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.
-
-**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.
-
-```sh
-X402_PRIVATE_KEY=0x... npx onesource-api-mcp
-```
-
-Without this key, 402 responses are returned as tool errors with a descriptive message.
-
-
-## Configuration
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `ONESOURCE_BASE_URL` | `https://skills.onesource.io` | Skills API endpoint |
-| `X402_PRIVATE_KEY` | — | EVM private key (0x-prefixed hex) for automatic x402 USDC payments on Base |
-
-
-## License
-
-MIT
+# onesource-api-mcp
+
+MCP server for OneSource blockchain data. 22 named tools for balances, NFTs, transactions, events, and live chain queries via API key or x402 micropayments.
+
+```
+npx onesource-api-mcp
+```
+
+## Install
+
+```sh
+# Claude Code
+claude mcp add onesource-api -- npx onesource-api-mcp
+
+# Claude Desktop / Cursor — add to MCP config:
+{
+  "mcpServers": {
+    "onesource-api": {
+      "command": "npx",
+      "args": ["-y", "onesource-api-mcp"]
+    }
+  }
+}
+```
+
+## Tools (22)
+
+
+### Live Chain Data (12 tools)
+
+| Tool | Description |
+|------|-------------|
+| `1s_allowance_live` | ERC20 allowance check |
+| `1s_contract_info_live` | Contract type detection via ERC165 |
+| `1s_erc1155_balance_live` | ERC1155 balance via RPC |
+| `1s_erc20_balance_live` | ERC20 balance via balanceOf |
+| `1s_erc20_transfers_live` | ERC20 Transfer logs via eth_getLogs |
+| `1s_erc721_tokens_live` | ERC721 token enumeration |
+| `1s_events_live` | Event logs via eth_getLogs |
+| `1s_multi_balance_live` | ETH + multiple ERC20 balances |
+| `1s_nft_metadata_live` | NFT metadata via tokenURI |
+| `1s_nft_owner_live` | NFT owner via ownerOf |
+| `1s_total_supply_live` | Token total supply |
+| `1s_tx_details_live` | Transaction + receipt via RPC |
+
+
+### Chain Utilities (10 tools)
+
+| Tool | Description |
+|------|-------------|
+| `1s_contract_code` | Contract bytecode |
+| `1s_ens_resolve` | ENS name/address resolution |
+| `1s_estimate_gas` | Gas estimation |
+| `1s_network_info` | Chain ID, block number, gas price |
+| `1s_nonce` | Transaction count |
+| `1s_pending_block` | Pending block from mempool |
+| `1s_proxy_detect` | Proxy contract detection |
+| `1s_simulate_call` | Simulate eth_call |
+| `1s_storage_read` | Read storage slot |
+| `1s_tx_receipt` | Transaction receipt |
+
+
+## Networks
+
+All tools accept an optional `network` parameter:
+
+| Network | Description |
+|---------|-------------|
+| `ethereum` | Ethereum mainnet (default) |
+| `sepolia` | Ethereum Sepolia testnet |
+| `avax` | Avalanche C-Chain |
+
+
+## Authentication
+
+Two auth methods are supported. **API key takes priority** when both are configured.
+
+### API Key (recommended)
+
+Set `ONESOURCE_API_KEY` to your OneSource API key. The server sends it as a Bearer token on every request.
+
+```sh
+ONESOURCE_API_KEY=your-key-here npx onesource-api-mcp
+```
+
+Or in your MCP config:
+```json
+{
+  "mcpServers": {
+    "onesource-api": {
+      "command": "npx",
+      "args": ["-y", "onesource-api-mcp"],
+      "env": {
+        "ONESOURCE_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+### x402 Micropayments
+
+Set `X402_PRIVATE_KEY` to a funded EVM wallet key. The server automatically signs and settles USDC payments on Base via [x402](https://github.com/coinbase/x402).
+
+```sh
+X402_PRIVATE_KEY=your-private-key-hex npx onesource-api-mcp
+```
+
+### No auth
+
+Without either variable, tools work for free endpoints. Paid endpoints return 402 errors with a descriptive message.
+
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ONESOURCE_API_KEY` | — | OneSource API key. Sent as `Authorization: Bearer <key>`. Takes priority over x402. |
+| `ONESOURCE_BASE_URL` | `https://skills.onesource.io` | Skills API endpoint |
+| `X402_PRIVATE_KEY` | — | EVM private key (hex, with or without 0x prefix) for automatic x402 USDC payments on Base |
+
+
+## License
+
+MIT