@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

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

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://skills.onesource.io	Skills 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