onesource-api-mcp

MCP server for OneSource blockchain data. 73 named tools for balances, NFTs, transactions, events, live chain queries, Deepstate market data, and The Standard Reserve — all paid the same way, via API key, x402, or MPP 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 (73)

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 payment rail + mode: x402-exact / x402-batch (USDC on Base) or mpp-charge / mpp-session (Tempo) | | 1s_refund | Reclaim an open payment channel's unspent deposit on demand — works for whichever rail's channel is active: x402 batch (Base) or MPP session (Tempo) |

Deepstate Market Data (8 tools)

Deepstate is an on-chain order-book protocol on Robinhood Chain (chain ID 4663). These tools read market data — order books, trades, candles, stats, maker analytics, and gas/depth analytics. They're ordinary tools on the same API and take no network parameter — always Robinhood Chain — and are paid like every other tool: API key, x402, or MPP.

| Tool | Description | |------|-------------| | 1s_ds_markets | List the Deepstate markets (order books) this API serves, with each market's slug, token layout, and pool/router addresses | | 1s_ds_book | Order-book snapshot for a market — bids descending, asks ascending, with each price level's resting size | | 1s_ds_trades | Trade tape for a market, newest first — each fill's price, size, side, and block | | 1s_ds_candles | OHLCV candles for a market at a given timeframe | | 1s_ds_stats | Rolling 24h / 7d / 30d volume and price change for a market, plus the latest traded price | | 1s_ds_makers | Per-maker analytics for a market — time at top of book, resting notional, fill count/rate, and DEEP rewards | | 1s_ds_cost_to_quote | Gas spent resting and cancelling orders on a market, bucketed over time | | 1s_ds_depth_history | Depth heatmap for a market — resting order size by price level over time |

Every Deepstate tool except 1s_ds_markets takes a book parameter: the market's canonical uppercase slug (e.g. NVDA-USDG) or its 32-byte book_id. Call 1s_ds_markets first for the full list.

The Standard Reserve (38 tools)

The Standard Reserve is an on-chain central-bank protocol on Robinhood Chain (chain id 4663). These tools read the deployed contracts' state as indexed and served by OneSource, with basis, as_of_block, and serving_state on every response. 1s_std_addresses and 1s_std_genesis_live are free; the four 1s_std_decision_* composites (they bundle several reads into one call) are $0.05 each; every other tool here is $0.02, paid the same way as the rest of this API: API key, x402, or MPP.

supply, vaults, pool, exit_pressure, backing, and policy_current also take an atBlock parameter to read that state as of a historical block instead of the latest one.

| Tool | Description | |------|-------------| | 1s_std_addresses | Verified registry of TSR contracts and pool, with a verification status per entry. Free, no payment required. | | 1s_std_auction_days | Per-day history for the license or charter auction: open/floor/close price, offered vs. sold, and time to sell out. Requires kind, page with before/limit | | 1s_std_auction_sales | Recent sales for the license or charter auction, newest first: buyer, unit price, count, and block. Filter by kind, page with before/limit | | 1s_std_auctions_current | Current state of the daily license auction and charter auction: price, floor, sold/remaining today, last sale, and when the next auction day starts | | 1s_std_backing | Reserve backing: vault ETH balances, discovered reserve-asset holdings, and ETH backing per STANDARD (excluding vs. including protocol-owned liquidity, and excluding ETH held by the tax hook or fee splitter awaiting forwarding). Supports history_hours and atBlock | | 1s_std_branch_auction_live | Raw head-fresh state of the Branch license auction: phase, price, today's sold/remaining counts, recent sale velocity, and when the next auction day starts | | 1s_std_branches_doi | Days of Issuance for the Branch license auction, plus a buy-now-vs-wait table and when the next auction day starts | | 1s_std_branches_summary | Summary across TSR's active Branches: count, issuance per Branch per day, and license price in days of issuance | | 1s_std_buyback_readiness | Contraction-vault buyback-tick readiness: this tick's ETH capacity, cooldown remaining, pool tick vs. TWAP, whether ticks are open to the public (measured from the address registry, with executor/guardian addresses), ETH sitting in the tax hook and fee splitter awaiting forwarding, and recent executed ticks | | 1s_std_candles | OHLC price candles for the ETH/STANDARD pool in ETH per STANDARD, with swap counts and volume. Set tf for candle width (1m to 1d), from/to for the window, and quote=usd to add a USD leg from the Chainlink ETH/USD feed | | 1s_std_charter | One charter by id, or charters filtered by owner: holder, branch count, mint kind, owed production, and branch history | | 1s_std_decision_branch | Composite: should I buy a Branch or license right now. Bundles Days of Issuance, license cost via pool vs. charter auction, auction day history, policy outlook, pending governance changes, and when the next auction day starts. $0.05 | | 1s_std_decision_charter | Composite: should I buy into a new charter right now. Bundles charter-auction state, the cheapest-path license cost, Days of Issuance, ETH backing, holder concentration, and pending governance changes. $0.05 | | 1s_std_decision_exit | Composite: should I exit this charter's branches right now. Bundles the exit quote, fee curve, fee forecast, tax schedule, live pool state, and policy outlook. Requires charterId. $0.05 | | 1s_std_decision_plan | Composite: simulate keep/selective/aggressive Branch-buying strategies over a horizon, with license funding, exit fee, and terminal sale modeled from the live curves. Requires budget_eth_raw. $0.05 | | 1s_std_dormancy_bounties | Wallets past their reportable dormancy window, ranked by estimated bounty descending | | 1s_std_dormancy | Wallets past their reportable dormancy window, or the full tracked wallet list | | 1s_std_epochs | TSR epoch history: net flow, signal, regime, multiplier, and issuance per epoch. Page with before/limit | | 1s_std_events | Raw decoded protocol events, optionally filtered by contract_label, event_name, addresses, token_id, epoch, or block/log cursor, and paginated with before/limit | | 1s_std_exit_fee_curve | How the exit fee changes with withdrawal size: current system-wide rate plus a ladder at 1/5/10/25/50/100% of a gross amount, checked against a live contract preview | | 1s_std_exit_fee_forecast | Projects how the system-wide exit fee would move if no more withdrawals happened, including days_until_min_fee | | 1s_std_exit_pressure | Exit-pressure reading and the resulting resolution fee rate, current or (with history_hours) history. Supports atBlock | | 1s_std_exit_quote | Pro-rata exit quote for retiring a charter's open Branches: gross, fee, net STANDARD, and realizable_eth. Requires charterId and branches | | 1s_std_flow_hourly | Hourly ETH flow into and out of the ETH/STANDARD pool, with swap counts. Set hours for how far back to look | | 1s_std_flow_charters | ETH/STANDARD pool buys and sells grouped by wallets that held a Charter when each swap occurred. Set hours and limit for the result window | | 1s_std_genesis_live | Head-fresh stats for the genesis Dutch mint: phase, minted, remaining, price, and sale velocity. Free. | | 1s_std_governance_changes | Governance history across TSR's 12 contracts: param changes, what's queued but not applied, each contract's guardian pause state, and the address registry's own state (execution_permissionless, the per-key locked map, and the executor/guardian/net_flow_source/owner addresses) | | 1s_std_holders_concentration | How concentrated Charter/Branch ownership is: distribution, top owners, an HHI concentration score, and a genesis-vs-auction cohort split | | 1s_std_issuance_runway | Cumulative STANDARD issued against the Central Bank's issuance budget, current stream rate, budget remaining, and a same-state projection of when it runs out | | 1s_std_license_cost | What a Branch license costs in ETH right now — including the pool's own LP fee — and whether the charter auction is a cheaper path to the same outcome | | 1s_std_license_headroom | How many more Branch licenses a charter can still buy today, with a live quote(n) ladder. Requires charterId | | 1s_std_policy_current | Current epoch's monetary policy: regime, multiplier, net flow, and the two-epoch signal. Supports atBlock | | 1s_std_policy_outlook | Current-sign-holds outlook: what the policy multiplier and issuance rate would be if the current epoch's net flow sign holds to close | | 1s_std_pool | Latest ETH/STANDARD Uniswap v4 pool state: price, tick, liquidity, reserves, remaining launch tax, the pool's own LP fee, and a USD leg from the Chainlink ETH/USD feed. Supports atBlock | | 1s_std_supply | STANDARD supply ledger: circulating, cumulative minted, cumulative burned by path (and split into the permanent burned_forever vs. re-mintable deposited subsets, plus ledger_retired), and max supply. Current, or (with history_hours) history. Supports atBlock | | 1s_std_tax_schedule | Launch tax-hook schedule: current buy/sell tax in basis points, decay configuration, a floor_reached_at projection, and a freshness marker so a post-floor rate still reads as fresh | | 1s_std_vaults | Expansion and Contraction vault balances: WETH and STANDARD held, protocol-owned liquidity, and buyback capacity. Current, or (with history_hours) history. Supports atBlock | | 1s_std_wallet | One wallet's full TSR position: every Charter held, pending owed STANDARD, a summary exit quote, dormancy record, and each Charter's license-purchase headroom |

Networks

All tools above the Deepstate section accept an optional network parameter (Deepstate tools always target Robinhood Chain and take no network parameter):

| Network | Description | |---------|-------------| | ethereum | Ethereum mainnet (default) | | sepolia | Ethereum Sepolia testnet | | robinhood | Robinhood Chain (chain ID 4663) — Arbitrum Orbit L2 settling to Ethereum. ~100ms blocks, no ENS, no public mempool, live-RPC only (indexed endpoints unavailable) |

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 x402-exact scheme (one USDC payment per call). For a burst of calls you can switch to x402-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": "x402-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.

MPP Micropayments (Tempo)

Set MPP_PRIVATE_KEY to a funded Tempo wallet key. The server automatically signs and settles Tempo payments (USDC.e / pathUSD) via the mppx SDK.

MPP_PRIVATE_KEY=your-private-key-hex npx onesource-api-mcp

MPP has two modes, switched with 1s_payment_mode: mpp-charge (default — one payment per call) and mpp-session (a voucher channel — one on-chain deposit, capped by MPP_MAX_DEPOSIT, funds many off-chain calls; reclaim the unspent deposit any time with 1s_refund, or it settles automatically on clean shutdown). x402 and MPP are separate rails with separate wallets; if both keys are set, x402 is the initial rail and you switch between all four modes in-session.

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 a payment wallet. | | X402_PRIVATE_KEY | — | EVM private key (hex, with or without 0x prefix) for automatic x402 USDC payments on Base. | | MPP_PRIVATE_KEY | — | EVM private key (hex, with or without 0x prefix) for automatic MPP payments on Tempo (USDC.e / pathUSD). |

Optional / Advanced

All have sensible defaults — set these only to override an endpoint or tune how channel modes behave. 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://api.onesource.io | API endpoint. Also serves the 8 Deepstate (1s_ds_*) routes and the 38 Standard Reserve (1s_std_*) routes — one front door for every tool. | | ONESOURCE_PAYMENT_MODE | rail default | Initial rail+mode: x402-exact, x402-batch, mpp-charge, or mpp-session. Falls back to the enabled rail's own default. | | 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. | | MPP_PAYMENT_MODE | charge | Initial MPP mode: charge (per-call) or session (voucher channel). Switch in-session with the 1s_payment_mode tool. | | MPP_MAX_DEPOSIT | 1 | mpp-session: max tokens reserved in the on-chain channel deposit. Bounds the worst-case locked balance on an unclean shutdown. | | MPP_RPC_URL | Tempo default | Tempo RPC endpoint used to open/settle the session channel (mpp-session only). |

License

MIT