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

# 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 | Reclaim an open payment channel's unspent deposit on demand — works for whichever rail's channel is active: x402 batch (Base) or MPP session (Tempo) |

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.

ONESOURCE_API_KEY=your-key-here npx onesource-api-mcp

Or in your MCP config:

{
  "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.

X402_PRIVATE_KEY=your-private-key-hex npx onesource-api-mcp

Payments default to the x402-exact scheme (one USDC payment per call). For a burst of calls you can switch to x402-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": "x402-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 wallet key. The server automatically signs and settles Tempo payments (USDC.e / pathUSD) via the mppx SDK.

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; reclaim the unspent deposit any time with 1s_refund, or it settles 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