@one-source/api-mcp 5.4.6 → 5.5.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,155 +1,170 @@
-# onesource-api-mcp
-
-MCP server for OneSource blockchain data. 27 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 (27)
-
-
-### 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 (13 tools) - RPC Only
-
-| Tool | Description |
-|------|-------------|
-| `1s_block_by_number` | Block details by number |
-| `1s_block_number` | Latest block number |
-| `1s_chain_id` | EIP-155 chain ID |
-| `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 |
-
-### Payments (2 tools)
-
-| Tool | Description |
-|------|-------------|
-| `1s_payment_mode` | View or switch the x402 payment scheme (`exact` per-call vs `batch` payment channel) |
-| `1s_refund` | Refund unused `batch` channel balance back to your wallet on demand |
-
-
-## Networks
-
-All tools accept an optional `network` parameter:
-
-| Network | Description |
-|---------|-------------|
-| `ethereum` | Ethereum mainnet (default) |
-| `sepolia` | Ethereum Sepolia testnet |
-
-
-## 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
-```
-
-Payments default to the **exact** scheme (one USDC payment per call). For a burst of calls you can switch to **batch** settlement — a payment channel that funds many off-chain calls from a single on-chain deposit, settled with one claim — by calling the `1s_payment_mode` tool with `{ "mode": "batch" }`, or by setting `X402_PAYMENT_MODE=batch`. Both modes use the same wallet.
-
-In batch mode the first paid call deposits `price × X402_DEPOSIT_MULTIPLIER` (default 10) up front, so a session typically over-funds the channel. Reclaim the unused balance whenever you're done with the `1s_refund` tool; idle channels are also auto-refunded by the receiver after a few hours. The deposit residual is always recoverable.
-
-### No auth
-
-Without either variable, tools work for free endpoints. Paid endpoints return 402 errors with a descriptive message.
-
-
-## Configuration
-
-Most users only set one of the two keys below. Everything else has a working default — including batch mode, which runs out of the box with no extra configuration.
-
-### Required
-
-Set one to access paid endpoints. Without either, only free endpoints work. API key takes priority when both are set.
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `ONESOURCE_API_KEY` | — | OneSource API key. Sent as `Authorization: Bearer <key>`. Takes priority over x402. |
-| `X402_PRIVATE_KEY` | — | EVM private key (hex, with or without 0x prefix) for automatic x402 USDC payments on Base. |
-
-### Optional / Advanced
-
-All have sensible defaults — set these only to override an endpoint or tune how `batch` mode behaves. You can switch payment modes at runtime with the `1s_payment_mode` tool instead of setting any of these.
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `ONESOURCE_BASE_URL` | `https://api.onesource.io` | API endpoint. |
-| `X402_PAYMENT_MODE` | `exact` | Initial x402 scheme: `exact` (per-call) or `batch` (payment channel). Switch in-session with the `1s_payment_mode` tool. |
-| `X402_RPC_URL` | Base default | Base RPC endpoint used to submit channel deposits in batch mode. |
-| `X402_CHANNEL_DIR` | — | Directory to persist batch channel state across restarts. Unset = in-memory (channel lost on restart). |
-| `X402_DEPOSIT_MULTIPLIER` | `10` | Batch mode: deposit = price × this multiplier, funding that many calls per channel. Unused balance is reclaimable via `1s_refund`. |
-
-
-## License
-
-MIT
+# onesource-api-mcp
+
+MCP server for OneSource blockchain data. 27 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 (27)
+
+
+### 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 (13 tools) - RPC Only
+
+| Tool | Description |
+|------|-------------|
+| `1s_block_by_number` | Block details by number |
+| `1s_block_number` | Latest block number |
+| `1s_chain_id` | EIP-155 chain ID |
+| `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 |
+
+### Payments (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `1s_payment_mode` | View or switch the payment rail + mode: `x402-exact` / `x402-batch` (USDC on Base) or `mpp-charge` / `mpp-session` (Tempo) |
+| `1s_refund` | Refund unused x402 `batch` channel balance back to your wallet on demand |
+
+
+## Networks
+
+All tools accept an optional `network` parameter:
+
+| Network | Description |
+|---------|-------------|
+| `ethereum` | Ethereum mainnet (default) |
+| `sepolia` | Ethereum Sepolia testnet |
+
+
+## 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
+```
+
+Payments default to the **exact** scheme (one USDC payment per call). For a burst of calls you can switch to **batch** settlement — a payment channel that funds many off-chain calls from a single on-chain deposit, settled with one claim — by calling the `1s_payment_mode` tool with `{ "mode": "batch" }`, or by setting `X402_PAYMENT_MODE=batch`. Both modes use the same wallet.
+
+In batch mode the first paid call deposits `price × X402_DEPOSIT_MULTIPLIER` (default 10) up front, so a session typically over-funds the channel. Reclaim the unused balance whenever you're done with the `1s_refund` tool; idle channels are also auto-refunded by the receiver after a few hours. The deposit residual is always recoverable.
+
+### MPP Micropayments (Tempo)
+
+Set `MPP_PRIVATE_KEY` to a funded [Tempo](https://mpp.dev) wallet key. The server automatically signs and settles Tempo payments (USDC.e / pathUSD) via the [`mppx`](https://github.com/wevm/mppx) SDK.
+
+```sh
+MPP_PRIVATE_KEY=your-private-key-hex npx onesource-api-mcp
+```
+
+MPP has two modes, switched with `1s_payment_mode`: **`mpp-charge`** (default — one payment per call) and **`mpp-session`** (a voucher channel — one on-chain deposit, capped by `MPP_MAX_DEPOSIT`, funds many off-chain calls; the unspent deposit is reclaimed automatically on clean shutdown). x402 and MPP are separate rails with separate wallets; if both keys are set, x402 is the initial rail and you switch between all four modes in-session.
+
+### No auth
+
+Without either variable, tools work for free endpoints. Paid endpoints return 402 errors with a descriptive message.
+
+
+## Configuration
+
+Most users only set one of the two keys below. Everything else has a working default — including batch mode, which runs out of the box with no extra configuration.
+
+### Required
+
+Set one to access paid endpoints. Without either, only free endpoints work. API key takes priority when both are set.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ONESOURCE_API_KEY` | — | OneSource API key. Sent as `Authorization: Bearer <key>`. Takes priority over a payment wallet. |
+| `X402_PRIVATE_KEY` | — | EVM private key (hex, with or without 0x prefix) for automatic x402 USDC payments on Base. |
+| `MPP_PRIVATE_KEY` | — | EVM private key (hex, with or without 0x prefix) for automatic MPP payments on Tempo (USDC.e / pathUSD). |
+
+### Optional / Advanced
+
+All have sensible defaults — set these only to override an endpoint or tune how channel modes behave. You can switch payment modes at runtime with the `1s_payment_mode` tool instead of setting any of these.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ONESOURCE_BASE_URL` | `https://api.onesource.io` | API endpoint. |
+| `ONESOURCE_PAYMENT_MODE` | rail default | Initial rail+mode: `x402-exact`, `x402-batch`, `mpp-charge`, or `mpp-session`. Falls back to the enabled rail's own default. |
+| `X402_PAYMENT_MODE` | `exact` | Initial x402 scheme: `exact` (per-call) or `batch` (payment channel). Switch in-session with the `1s_payment_mode` tool. |
+| `X402_RPC_URL` | Base default | Base RPC endpoint used to submit channel deposits in batch mode. |
+| `X402_CHANNEL_DIR` | — | Directory to persist batch channel state across restarts. Unset = in-memory (channel lost on restart). |
+| `X402_DEPOSIT_MULTIPLIER` | `10` | Batch mode: deposit = price × this multiplier, funding that many calls per channel. Unused balance is reclaimable via `1s_refund`. |
+| `MPP_PAYMENT_MODE` | `charge` | Initial MPP mode: `charge` (per-call) or `session` (voucher channel). Switch in-session with the `1s_payment_mode` tool. |
+| `MPP_MAX_DEPOSIT` | `1` | `mpp-session`: max tokens reserved in the on-chain channel deposit. Bounds the worst-case locked balance on an unclean shutdown. |
+| `MPP_RPC_URL` | Tempo default | Tempo RPC endpoint used to open/settle the session channel (`mpp-session` only). |
+
+
+## License
+
+MIT