MCP tool reference
@one-source/mcp exposes 30 tools, all prefixed with 1s_ so they sort together in your client. Live-chain tools end in _live; chain utilities don't. Every tool maps 1:1 to a OneSource REST API endpoint and inherits its pricing; see the API Reference for full parameter and response schemas.
Live chain data (12)
| Tool | Endpoint | What it returns |
|---|---|---|
1s_multi_balance_live | /api/chain/live-balance | ETH + multiple ERC20 balances in one batched call |
1s_erc20_balance_live | /api/chain/erc20-balance | Single ERC20 balance with name/symbol/decimals |
1s_erc1155_balance_live | /api/chain/erc1155-balance | ERC1155 token balance for an account |
1s_nft_owner_live | /api/chain/nft-owner | NFT owner via ownerOf |
1s_nft_metadata_live | /api/chain/nft-metadata | NFT metadata with IPFS / Arweave / data: URI resolution |
1s_erc721_tokens_live | /api/chain/erc721-tokens | Token metadata batch for an ERC721 contract |
1s_erc20_transfers_live | /api/chain/erc20-transfers | ERC20 Transfer logs |
1s_events_live | /api/chain/events | Event logs via eth_getLogs |
1s_total_supply_live | /api/chain/total-supply | ERC20 total supply |
1s_allowance_live | /api/chain/allowance | ERC20 allowance check |
1s_tx_details_live | /api/chain/tx/{hash} | Transaction + receipt |
1s_contract_info_live | /api/chain/contract/{address} | Name/symbol/decimals + ERC-standard detection (ERC-165) |
Chain utilities (13)
| Tool | Endpoint | What it returns |
|---|---|---|
1s_network_info | /api/chain/network-info | Chain ID, latest block, gas price (batched) |
1s_chain_id | /api/chain/chain-id | EIP-155 chain ID |
1s_block_number | /api/chain/block-number | Latest block number |
1s_block_by_number | /api/chain/block/{number} | Block header + transaction hashes |
1s_pending_block | /api/chain/pending | Pending block from the mempool |
1s_contract_code | /api/chain/code/{address} | Contract bytecode |
1s_nonce | /api/chain/nonce/{address} | Transaction count for an address |
1s_storage_read | /api/chain/storage | Read an arbitrary storage slot |
1s_tx_receipt | /api/chain/receipt/{hash} | Transaction receipt |
1s_simulate_call | /api/chain/call | Simulate eth_call (read-only contract call) |
1s_estimate_gas | /api/chain/estimate-gas | Gas estimate for a transaction |
1s_ens_resolve | /api/chain/ens/{input} | Forward ENS resolution |
1s_proxy_detect | /api/chain/proxy/{address} | Upgradeable-proxy implementation detection (EIP-1967, UUPS, Transparent) |
Payments (2)
These two tools only do something in wallet-paid mode (X402_PRIVATE_KEY or MPP_PRIVATE_KEY set). With an API key, calls are covered by your plan, so they report that there is nothing to switch or refund.
| Tool | Purpose |
|---|---|
1s_payment_mode | View or switch the rail + scheme the session pays with: x402-exact / x402-batch (x402 on Base, USDC) or mpp-charge / mpp-session (MPP on Tempo, USDC.e / pathUSD). *-exact / *-charge settle per call; *-batch / *-session open a channel where one deposit funds many calls. Call with no arguments to see the current mode. |
1s_refund | Reclaim the unused channel deposit back to your wallet, on demand. Rail-neutral: it settles and returns the full remaining escrow of an open x402 batch channel (on Base) or an mpp-session voucher channel (on Tempo). For x402 this beats waiting for the gateway's automatic idle refund; for MPP it's the manual reclaim path alongside the automatic settle on clean shutdown. |
Setup and ops (3)
These tools need no authentication, so they work before you've configured a key.
| Tool | Purpose |
|---|---|
1s_setup_check | Interactive setup and health check. Call this first in any session: it asks whether you want to just review your current config or set up / change it, then for a change it walks you through choosing an auth method (API key) or payment rail (x402 on Base / MPP on Tempo) and every related option one decision at a time. It applies what it can live (via 1s_payment_mode / 1s_batch_config) and hands you a single ready-to-run command for anything needing a restart (such as a wallet key), never asking you to paste a secret into the chat or hand-edit config files. It also confirms the credential is being read, the service is reachable, the server version (with an update hint if a newer one is published), and, in a wallet-paid mode, the wallet address and current x402 batch or MPP session state. |
1s_batch_config | View or change the payment preferences (autonomy, "burst" threshold, x402 deposit multiplier, MPP session deposit cap, default rail + mode) from your assistant and persist them across restarts. No config-file editing or env vars required. See Configuration → Configure batch behavior from your assistant. |
1s_report_bug | File a bug report from inside your assistant. Captures recent tool calls and the request context. |
Example prompts
The assistant picks the right tool automatically:
- "What's the USDC balance of vitalik.eth?" →
1s_ens_resolve+1s_erc20_balance_live - "Show the last 10 ERC20 transfers out of 0xabc…" →
1s_erc20_transfers_live - "Resolve the metadata for Bored Ape #4521." →
1s_nft_metadata_live - "Decode the receipt for transaction 0xdef… and tell me which events fired." →
1s_tx_receipt - "Is 0x123… a proxy contract? If so, what's the implementation address?" →
1s_proxy_detect
Network
Ethereum mainnet (default) and the Sepolia testnet. Every chain tool takes an optional network parameter; it defaults to ethereum. Pass network: "sepolia" to target Sepolia. See Configuration → Networks for details.
Pricing
Per-call cost is published in the response meta.cost_usdc field and on each operation's API Reference page under x-payment-info. Bearer-key subscribers pay nothing per call (your monthly quota covers it); wallet-paid users (x402 or MPP) pay $0.001 – $0.010 per call.