MCP tool reference
@one-source/mcp exposes 99 tools (51 of them 1s_std_*, including 1s_std_decision_plan, 1s_std_decision_stake, 1s_std_decision_hold, 1s_std_decision_sbill, and 1s_std_decision_bid), 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, and the 1s_std_* tools against The Standard Reserve.
Running the server over HTTP exposes 95 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 maker rewards earned (token varies by market; see 1s_ds_markets) |
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 |
The Standard Reserve (48)
The Standard Reserve ("STANDARD") is an on-chain central-bank protocol on Robinhood Chain. These tools read its charters, branches, auctions, epochs, exit economics, backing, and participants; none take a network parameter, since Standard Reserve data is always Robinhood Chain. See The Standard Reserve for the full protocol writeup, pricing, and How to read a TSR response for what basis, serving_state, and _raw mean below. 1s_std_addresses is free; every other tool here is paid the same way as the matching REST route.
Eight of these, 1s_std_decision_branch, 1s_std_decision_exit, 1s_std_decision_charter, 1s_std_decision_plan, 1s_std_decision_stake, 1s_std_decision_hold, 1s_std_decision_sbill, and 1s_std_decision_bid, are composite tools that bundle several of the individual routes below into one call. Deciding with the data maps common questions (exit, branch cost, policy, staking, holding, one S-Bill, a license bid, backing, participants) to the tool you actually want.
| Tool | Endpoint | What it returns |
|---|---|---|
1s_std_addresses | /v1/addresses | The verified address registry: check this before trusting or paying any other Standard Reserve contract (free) |
1s_std_charter | /v1/charters/{id} | One charter: holder, branch count, status, its stimulus (claimable amount, deadline, what a full exit forfeits) and its charter_drops shares |
1s_std_exit_quote | /v1/charters/{id}/exit-quote | Pro-rata exit quote for n of a charter's open branches, with realizable_eth and an at_block what-if |
1s_std_exit_fee_curve | /v1/exit/fee-curve | How the exit fee would move at larger or smaller withdrawal sizes than the current one |
1s_std_exit_fee_forecast | /v1/exit/fee-forecast | Current-pace projection of the system-wide exit fee assuming no further exits |
1s_std_exit_pressure | /v1/exit-pressure/current | Current exit-pressure snapshot and resolution-fee rate |
1s_std_branches_summary | /v1/branches/summary | Branch count, yield per branch/day, license price in branch-days |
1s_std_branches_doi | /v1/branches/doi | Days of Issuance: what the license price buys in issuance terms |
1s_std_license_cost | /v1/branches/license-cost | Today's license price converted to an estimated ETH cost, compared against the charter auction |
1s_std_license_headroom | /v1/charters/{id}/license-headroom | How many more licenses this charter can still buy today, with a live quote for each |
1s_std_branch_auction_live | (live) | Raw, head-fresh state of the Branch license auction |
1s_std_auctions_current | /v1/auctions/current | Current Dutch-auction quotes for both the license and charter auctions, with phase/sold-out/units fields |
1s_std_auction_days | /v1/auctions/days | Per-day auction history: open, floor, close, sold vs. offered, sellout time |
1s_std_license_bids | /v1/auctions/license/bids | The open-bid book for the license auction, read at one block: bidder, count, max unit price, the contract's fillable answer, a blocking list per bid, stale or prunable flags, and a derived effective crossing price. Optional charter_id, bidder, fillable_only, sort |
1s_std_auction_sales | /v1/auctions/sales | Recent individual auction sales |
1s_std_epochs | /v1/epochs | Epoch history: net flow, signal, regime, multiplier, issuance |
1s_std_policy_current | /v1/policy/current | The latest epoch, live-estimated before it settles |
1s_std_policy_outlook | /v1/policy/outlook | Current-sign-holds projection of the multiplier and issuance rate |
1s_std_issuance_runway | /v1/issuance/runway | Cumulative issuance vs. budget and a same-rate projected end date |
1s_std_governance_changes | /v1/governance/changes | Param-change history, queued changes, switches, guardian pause state |
1s_std_protocol_flows | /v1/flows/protocol | Protocol money movements, newest first: migrations, forwarded taxes, recycled fees, team claims, POL buybacks, fees and pairings, incentive sends, and outflows from the reserve vault Safe. Rows carry a to_label for known counterparties. Filter with kind, page with cursor |
1s_std_backing | /v1/backing/current, /history | Vault ETH, the vault's Uniswap v4 positions and reserve holdings, valued per circulating STANDARD, with an including_reserve_assets ratio at current pool prices |
1s_std_buyback_readiness | /v1/buybacks/readiness | Whether a buyback tick could fire right now: capacity, cooldown, TWAP deviation |
1s_std_tax_schedule | /v1/tax/schedule | Current launch buy/sell tax bps and the decay schedule |
1s_std_supply | /v1/supply/current | STANDARD supply ledger: circulating, minted, burned, and unclaimed charter stimulus |
1s_std_vaults | /v1/vaults/current | Expansion and Contraction vault balances |
1s_std_pool | /v1/pool | Latest ETH/STANDARD Uniswap v4 pool state |
1s_std_candles | /v1/pool/candles | OHLC price candles for the ETH/STANDARD pool |
1s_std_flow_hourly | /v1/flow/hourly | Hourly ETH flow into and out of the pool |
1s_std_flow_charters | /v1/flow/charters | Pool buys and sells grouped by wallets that held a Charter at each swap's exact block/log position; ambiguous transactions are excluded |
1s_std_holders_concentration | /v1/holders/concentration | Branch-per-charter distribution, top owners, HHI concentration score, cohort split |
1s_std_wallet | /v1/wallets/{address} | One wallet's full position: charters, pending owed, dormancy, license headroom, unclaimed stimulus, launchpad charter drops |
1s_std_launchpad_token | /v1/launchpad/tokens/{address} | One launchpad v2 token's URC-5 venue policy: mode, official pools, creator's launch choice, and every Uniswap v4 pool holding it |
1s_std_launchpad_venues | /v1/launchpad/venues | Chain-wide URC-5 counts, off-list pools their token's policy does not allow, and a pool_id lookup |
1s_std_dormancy | /v1/dormancy | Wallets past their reportable dormancy window |
1s_std_dormancy_bounties | /v1/dormancy/bounties | Same, ranked by estimated bounty |
1s_std_decision_branch | /v1/decisions/branch | Everything for "should I buy a branch or license right now," bundled, plus past launchpad charter-drop history (parts.charter_drops_history) |
1s_std_decision_exit | /v1/decisions/exit | Everything for "should I exit this charter's branches right now," bundled, plus what the net STANDARD would earn staked as an S-Bill for one term (parts.sbills_alternative), what a full exit would forfeit in stimulus (parts.stimulus), and what it releases from launchpad charter drops (parts.charter_drops) |
1s_std_decision_charter | /v1/decisions/charter | Everything for "should I buy into a new charter right now," bundled, including the charter auction's price path for the rest of the day (charter.expected_prices) and past launchpad charter-drop history (parts.charter_drops_history) |
1s_std_decision_plan | /v1/decisions/plan | Simulates keep/selective/aggressive Branch-expansion strategies over a horizon you choose, seeded from live license price, pool price, issuance rate, and branch counts. Each strategy also prices staking its released STANDARD as an S-Bill instead of selling it (stake_instead_of_sale) |
1s_std_decision_stake | /v1/decisions/stake | The inputs for staking STANDARD into an S-Bill, in one call: the live quote for amount, current S-Bills state, optional wallet cap headroom, and a derived 1h/6h/24h rate projection that assumes no other deposits |
1s_std_decision_sbill | /v1/decisions/sbill | The figures for one S-Bill by bill_id. Active bill: the exit payout now (measured), the premium an early exit gives up, and a derived exit fee for each coming day. Matured bill: the redeem payout (measured) and what rolling would lock (derived; only the bill's owner can roll, and nothing rolls automatically) |
1s_std_decision_hold | /v1/decisions/hold | The inputs for holding STANDARD, in one call: policy outlook, issuance runway, pending governance changes, tax schedule, buyback readiness, and the reportable dormancy count. Takes no arguments |
1s_std_decision_bid | /v1/decisions/bid | The inputs for a standing license bid at a max price, in one call: when the price reaches it (derived), the bids and licenses ahead and the supply left (derived), with charter_id that charter's pending, caps, and any bid a new one would replace (measured), and the measured fill history. A price crossing is not a fill, since fill() is a separate transaction anyone may send. Requires max_unit_price |
1s_std_genesis_live | (live) | Head-fresh stats on the genesis Dutch mint |
1s_std_events | /v1/events | Raw decoded protocol events, newest first |
1s_std_sbills_current | /v1/sbills/current | Current S-Bills staking terms: rate per term and simple APR at the live term length, drift state, principal locked, caps, pause/close flags, and the early-exit fee window inputs. The contract has no automatic roll; the owner must call roll after maturity |
1s_std_sbills_rate_history | /v1/sbills/rate-history | How the S-Bill rate has moved, with the term length in force at each point |
1s_std_sbills_quote | /v1/sbills/quote | Live quote for staking a given amount of STANDARD into an S-Bill: rate locked, premium, rate after, and which caps would block it. Optional wallet adds that wallet's open principal and cap headroom |
1s_std_sbills_bills | /v1/sbills/bills, /v1/sbills/bills/{id} | One S-Bill or a filtered list; the single-bill form adds live exit and redeem quotes. The contract has no automatic roll; the owner must call roll after maturity |
1s_std_sbills_events | /v1/sbills/events | Decoded S-Bills activity feed: deposits, early exits, redemptions, rolls, settlements, rate changes |
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.
The 1s_std_* Standard Reserve tools are priced flat at $0.02 per call, except 1s_std_addresses (free) and the eight 1s_std_decision_* tools (branch, exit, charter, plan, stake, hold, sbill, and bid), which are $0.05 to reflect the several routes each one bundles or the simulation each one runs. The OpenAPI spec is the source of truth for exact current pricing; it can't drift out of sync with what's actually charged the way a hardcoded number on this page could.