MCP tool reference
@one-source/mcp exposes 46 tools, all prefixed with 1s_ so they sort together in your client. Live-chain tools end in _live; chain utilities don't. Each chain tool maps 1:1 to a OneSource REST API endpoint and inherits its pricing; see the API Reference for full parameter and response schemas. The eight 1s_ds_* tools work the same way against Deepstate Market Data instead.
Running the server over HTTP exposes 44 of them: 1s_payment_mode and 1s_refund change process-level payment state, which is not safe to share between callers, so they are stdio-only.
Live chain data (12)
| Tool | Endpoint | What it returns |
|---|---|---|
1s_multi_balance_live | /api/chain/live-balance | ETH plus up to 20 caller-supplied 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) |
The token list on 1s_multi_balance_live
tokens takes at most 20 ERC20 contract addresses. Past 20 the call is rejected rather than
truncated, so split a longer list across several calls.
The tool reads the contracts you name. It does not discover what a wallet holds and does not
total the balances into a portfolio value, so a token you leave out of tokens is absent from
the response rather than reported as zero. An error on one token comes back against that token,
leaving the rest of the batch intact.
Paging the log tools
1s_erc20_transfers_live and 1s_events_live can exceed the MCP response limit (100,000 characters) in far fewer blocks than you'd expect, especially on a fast chain or a busy contract. When that happens you still get a usable result rather than an error:
| Field | Meaning |
|---|---|
truncated | true when the page was cut short |
returned / total | Entries in this page, and entries the call actually found |
next_from_block | First block not included; pass it back as from_block to continue |
Pages are cut on block boundaries, so walking next_from_block skips nothing and repeats nothing. Do that rather than retrying the same window with a smaller range: the first call already fetched and billed for the full result, so an overlapping retry pays twice for data you were already given.
One case can't be resumed: a single block whose logs exceed the limit on their own. You get what fits plus partial_block and deliberately no cursor, because /api/chain/events has no log-index offset to resume from, and a cursor there would promise gapless paging it can't deliver.
This paging is a property of the MCP server. Calling /api/chain/events over REST returns the full result set with no cap of its own, though the upstream node's 20,000-log limit still applies: see Batching and cost optimization.
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) |
Deepstate market data (8)
Deepstate is an on-chain order book protocol on Robinhood Chain. These tools read its order books, trades, candles, stats, and analytics; none take a network parameter, since Deepstate data is always Robinhood Chain. See Deepstate Market Data for pricing, response shape, and full endpoint detail.
| Tool | Endpoint | What it returns |
|---|---|---|
1s_ds_markets | /deepstate/v1/markets | The configured Deepstate markets, with token layout and pool/router addresses |
1s_ds_book | /deepstate/v1/book/{book} | Order-book snapshot: bids descending, asks ascending |
1s_ds_trades | /deepstate/v1/trades/{book} | Trade tape, newest first |
1s_ds_candles | /deepstate/v1/candles/{book} | OHLCV candles |
1s_ds_stats | /deepstate/v1/stats/{book} | Rolling 24h/7d/30d volume and price change |
1s_ds_makers | /deepstate/v1/analytics/makers | Per-maker time-at-top, resting notional, fills, and DEEP rewards earned |
1s_ds_cost_to_quote | /deepstate/v1/analytics/cost-to-quote | Gas spent resting and cancelling orders |
1s_ds_depth_history | /deepstate/v1/analytics/depth-history | Depth heatmap: resting size by price level over time |
Documentation (8)
These read the bundled OneSource documentation corpus. They are free, read-only, and need no credential, so they answer "how do I use this API?" while the chain tools are still waiting on a key or a wallet.
| Tool | Purpose |
|---|---|
1s_search_docs | Keyword search across the OneSource documentation |
1s_get_api_overview | What the REST API covers: operation count, tags, networks, payment protocols |
1s_list_endpoints | Every REST endpoint with method, path, price, and summary (optional tag filter) |
1s_get_endpoint_reference | Full reference for one endpoint: parameters, request body, example response, payment, curl |
1s_search_use_cases | Find endpoints by natural-language description |
1s_list_networks | Networks the API routes, read from the spec |
1s_get_payment_info | x402 / MPP protocols, prices, pay-to addresses, globally or per endpoint |
1s_get_authentication_guide | Bearer / x402 / MPP auth, with code examples and when to use which |
For documentation help without the chain tools, the same eight ship standalone as @one-source/docs-mcp.
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. Wallet-paid mode only: under API-key auth the server tells the assistant not to call it, since there are no payment rails to configure. 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), the Sepolia testnet, and Robinhood Chain. Every chain tool takes an optional network parameter; it defaults to ethereum. Pass network: "sepolia" or network: "robinhood" to target another chain. Robinhood Chain is an Arbitrum Orbit L2 with no ENS registry and no public mempool, so call 1s_network_info before interpreting a result there. See Configuration → Networks for details.
The eight 1s_ds_* Deepstate tools always operate on Robinhood Chain and take no network parameter at all.
Pricing
Per-call cost for the chain tools 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 to $0.02 per call, depending on the tool.
The 1s_ds_* Deepstate tools are priced flat instead: $0.005 per call, except the three analytics tools (1s_ds_makers, 1s_ds_cost_to_quote, 1s_ds_depth_history) at $0.02. See Deepstate Market Data → Pricing.