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 x402 wallet-paid mode (X402_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 how the session pays for x402 calls: exact (one settlement per call) or batch (open a payment channel: one deposit funds many calls, settled with a single claim). Call with no arguments to see the current mode. See batch settlement. |
1s_refund | Reclaim the unused balance of your batch payment channel back to your wallet on Base, on demand, instead of waiting for the gateway's automatic idle refund. Refunds the full remaining escrow. |
Setup and ops (3)
These tools need no authentication, so they work before you've configured a key.
| Tool | Purpose |
|---|---|
1s_setup_check | Auth and health status. Call this first in any session: it 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 x402 mode, the wallet address and current batch-settlement state. |
1s_batch_config | View or change the x402 batch-settlement preferences (autonomy, "burst" threshold, deposit multiplier, default payment 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); x402 wallet-paid users pay $0.001 – $0.010 USDC per call.