@one-source/api-mcp

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

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 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

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
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.
X402_CHANNEL_SALT	zero	Batch mode: 32-byte hex salt to derive the starting channel id. The client auto-rotates to the next salt when a channel is exhausted or refunded.

License

MIT