Toolhood/Docs/Documentation

Documentation.

Everything you need to connect, call tools and stay inside the limits. Start with the quickstart; the reference below is read from the engine.

StartQuickstart

Add the endpoint to your AI client and ask it something about Robinhood Chain. In Claude Code that is one line; every other client has its steps on Connect your AI.

Terminal
claude mcp add --transport http toolhood https://toolhood.xyz/mcp

Then ask: “What's the latest block on Robinhood Chain, and what's gas right now?” Your client calls chain_status and answers from the live chain.

StartEndpoint

https://toolhood.xyz/mcp
  • MCP over Streamable HTTP: POST JSON-RPC, JSON responses, no session needed. Protocol versions 2025-06-18, 2025-03-26 and 2024-11-05.
  • Methods: initialize, tools/list, tools/call, resources/list, prompts/list, ping.
  • One network: Robinhood Chain, chain id 4663, gas paid in ETH.

StartAccess keys

No key is needed. Without one you are on the free tier, counted per IP address. For higher limits, create a key on Access keys: you sign a one-time message with your wallet (no transaction, no gas) and the key is shown once.

Header
Authorization: Bearer th_live_<32 characters>

Keys can be revoked at any time on the same page. Treat a key like a password: anyone who has it uses your limits.

ReferenceTools

18 tools. Read tools are marked read-only for your client; prepare tools return a signing link and never send anything.

Read

chain_statusChain status

Robinhood Chain (chain id 4663, gas paid in ETH) right now: latest block number and time, gas price and base fee in gwei, and which RPC answered. Use it first to confirm the chain is reachable.

No arguments.

get_balanceWallet balance

ETH and token balances of an address on Robinhood Chain with USD values where a price is known. Uses the block explorer's token list when it is available to the server; otherwise reads balanceOf on-chain for every known token (USDG, WETH, the Robinhood stock tokens and the LI.FI token list, about 400) and says so with complete:false (tokens outside that list, such as small Pons launches, are then not shown). Tokens that copy the symbol of an official token at another address are flagged lookalike and not counted in the USD total.

ArgumentTypeMeaning
addressstringWallet or contract address (0x + 40 hex).
Example arguments
{
  "address": "0x15d24b87794b22c283138149560136fce2e0aca1"
}

get_transactionTransaction

One transaction by hash: status (success, reverted, pending), from, to, ETH value, fee in ETH and USD, the decoded method and arguments (built-in ABIs, then the 4byte directory), token transfers read from the receipt logs, and a one-line plain-words summary.

ArgumentTypeMeaning
hashstringTransaction hash (0x + 64 hex).
Example arguments
{
  "hash": "0x35c2889bd6cd5ecbd2f417f699642a858afc2ea394901ee4c9009c07ab1993ab"
}

get_blockBlock

A block header: number, hash, time, transaction count, gas used and limit, base fee, and the first transactions (hash, from, to, method). Leave number empty for the latest block.

ArgumentTypeMeaning
number optionalstringBlock number (decimal like "116217680" or hex), or "latest". Empty = latest.
Example arguments
{
  "number": "latest"
}

read_contractRead contract

Calls a view function with eth_call and decodes the answer. signature is "name(inputTypes)(outputTypes)", e.g. "balanceOf(address)(uint256)", "getReserves()(uint112,uint112,uint32)" or "symbol()(string)". Supports uint/int (8 to 256), address, bool, bytes1 to bytes32, bytes, string, fixed and dynamic arrays and tuples of these. If the output types are left out, the raw return data is given. Reverts come back decoded (Error(string), Panic codes, custom error selectors).

ArgumentTypeMeaning
addressstringContract address.
signaturestringFunction signature with output types, e.g. "balanceOf(address)(uint256)". Output part optional.
args optionalarrayArguments in order. Numbers as decimal strings, addresses as 0x strings, bools as true/false, arrays/tuples as JSON arrays.
block optionalstringBlock number or "latest" (default).
Example arguments
{
  "address": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
  "signature": "totalSupply()(uint256)",
  "args": []
}

get_activityAddress activity

The latest transactions of an address (newest first) with a one-line summary each: method, counterparty, ETH value, status and age. An address history needs a block-explorer index (a chain node cannot list it): the tool uses the Blockscout API, and when that API is not available to the server it returns an error with the sent-transaction count and the explorer link instead of guessing.

ArgumentTypeMeaning
addressstringWallet or contract address.
limit optionalintegerHow many transactions (1 to 25, default 10).
Example arguments
{
  "address": "0x15d24b87794b22c283138149560136fce2e0aca1",
  "limit": 10
}

Explain & guard

explain_transactionExplain a transaction

Explains a transaction in plain words. Reads and decodes it first (same data as get_transaction), then an AI model writes a short paragraph using ONLY that decoded data. If the AI is unavailable, a deterministic explanation is returned instead (source:"template").

ArgumentTypeMeaning
hashstringTransaction hash.
Example arguments
{
  "hash": "0x35c2889bd6cd5ecbd2f417f699642a858afc2ea394901ee4c9009c07ab1993ab"
}

simulate_transactionSimulate a transaction

Dry-runs a transaction against the latest block (eth_call + eth_estimateGas), nothing is sent. Returns: would it revert and why (Error(string), Panic, custom error), gas and fee in ETH and USD, the decoded intent, balance changes when they can be derived (ETH value, ERC-20 transfer/transferFrom, approve, WETH deposit/withdraw) and risk flags: unlimited approval, setApprovalForAll, Permit2 approval, unverified target, calldata sent to a wallet (EOA), target deployed in the last 24 h, value sent to a contract that rejects it, known lookalike token. Leave "to" empty to simulate a contract deployment.

ArgumentTypeMeaning
fromstringSender address (the wallet that would sign).
to optionalstringTarget address. Empty or null = contract creation.
data optionalstringCalldata as 0x hex (default 0x).
value optionalstringETH to send: wei as 0x hex or a decimal integer string, or ETH with a unit like "0.01 ETH". Default 0.
Example arguments
{
  "from": "0x15d24b87794b22c283138149560136fce2e0aca1",
  "to": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
  "data": "0x095ea7b3000000000000000000000000b477751b76cf82d00a686a1232f5fcd772414af3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
  "value": "0"
}

check_addressCheck an address

What an address is: a wallet (EOA), an EIP-7702 smart wallet (code 0xef0100… = still a wallet) or a contract; verified source and contract name, first-seen age, transaction count, ETH balance, token info if it is a token, Pons launch info if it was launched on Pons, and plain-word flags.

ArgumentTypeMeaning
addressstringAny address.
Example arguments
{
  "address": "0xB477751B76CF82d00a686A1232f5fCD772414Af3"
}

scan_tokenScan a token

Safety scan of an ERC-20 on Robinhood Chain: name, symbol, decimals, supply; Pons launch data when it is a Pons token (deployer, creator tax, whitelist, stage, graduated, creator earnings); top-10 holder concentration and the deployer's holding (Blockscout); price, liquidity and volume (DexScreener); verified source; lookalike check. Score 0 to 100 starts at 100 and subtracts: unverified source -15 (not applied to Pons launches, whose code is the launchpad's), top-10 holders (excluding pools, burn and the curve) over 50% -20 or over 30% -10, deployer holds over 10% -15 or over 5% -8, Pons whitelisted wallets hold over 20% -15 or over 10% -8 (read on-chain), liquidity under $1,000 -20 or under $10,000 -10 (not applied while still on the Pons bonding curve), creator tax over 5% -15 or over 0% -5, whitelist launch -5, token younger than 24 h -10, lookalike of an official symbol -40, top-holder list unavailable (it needs the block explorer API) -5, marked partial. Every deduction is listed in reasons. A score is a summary of these checks, not advice.

ArgumentTypeMeaning
addressstringToken contract address.
Example arguments
{
  "address": "0x51250b135174ca09450ec01c4aff73cf69dbb590"
}

get_approvalsToken approvals

Token approvals an owner has given (who can spend their tokens), with the CURRENT allowance read on-chain, unlimited flags and a risk level. With the block explorer: found from the owner's approve / setApprovalForAll / Permit2 transactions (latest 200), including NFT operators and unknown spenders. Without it: checks the tokens the owner holds (plus USDG and WETH) against the routers seen on Robinhood Chain and Permit2 only, marked partial:true with a note. Approvals made through permit signatures can be missing in both modes. Use prepare_revoke to remove one.

ArgumentTypeMeaning
addressstringOwner wallet address.
Example arguments
{
  "address": "0x15d24b87794b22c283138149560136fce2e0aca1"
}

Markets

pons_launchesPons launches

Token launches on the Pons launchpad on Robinhood Chain: name, symbol, address, stage (curve or graduated), market cap and volume in USD, price, creator tax, whitelist, deployer and age. Sort by newest, market cap or volume; optional search text.

ArgumentTypeMeaning
sort optionalnew | marketCap | volumeOrder (default new).
limit optionalinteger1 to 25 (default 10).
q optionalstringOptional search by name or symbol.
Example arguments
{
  "sort": "marketCap",
  "limit": 10
}

token_priceToken price

USD price of a Robinhood Chain token by address or symbol (ETH, WETH, USDG, stock tokens like AAPL, or any symbol listed on Pons): price, 24h change, liquidity, 24h volume and the main pool (DexScreener), with the LI.FI token list as a fallback. When a symbol matches several tokens, the official one is used and the others are listed.

ArgumentTypeMeaning
tokenstringToken address (0x…) or symbol, e.g. "USDG", "AAPL", "ETH".
Example arguments
{
  "token": "AAPL"
}

perps_marketsLighter perps

Perpetual futures on Lighter's Robinhood Chain venue (public API): last and mark price, 24h change, 24h volume, open interest and the current hourly funding rate. Give a symbol (BTC, ETH, NVDA, TSLA...) for one market, or nothing for all of them.

ArgumentTypeMeaning
symbol optionalstringMarket symbol, e.g. "BTC" or "NVDA". Empty = all markets.
Example arguments
{
  "symbol": "ETH"
}

Prepare (you sign)

prepare_transferPrepare a transfer

Builds a transfer of ETH or an ERC-20 (USDG, a stock token, any token address) as a signing link. Amount is in human units (e.g. "25.5"); decimals are read on-chain. If from is given, the transfer is simulated and the balance checked. Nothing is sent: give the user the link, they open it, check it and sign in their own wallet.

ArgumentTypeMeaning
from optionalstringSender wallet (optional, enables the balance check and simulation).
tostringRecipient address.
amountstringAmount in human units, e.g. "0.01" or "25". "max" is not supported.
token optionalstring"ETH" (default), a token symbol (USDG, AAPL...) or a token address.
Example arguments
{
  "from": "0x15d24b87794b22c283138149560136fce2e0aca1",
  "to": "0x000000000000000000000000000000000000dEaD",
  "amount": "1",
  "token": "USDG"
}

prepare_swapPrepare a swap

Gets a live LI.FI quote for a swap on Robinhood Chain (same chain, e.g. ETH to USDG or USDG to a stock token) and builds a signing link with an approve step first when the token allowance is too low. Amount is in human units of the token you sell. The quote expires in a few minutes, so the link is valid for 10 minutes. Shows the expected and minimum amount out, the route and the fees.

ArgumentTypeMeaning
fromstringWallet that will sign and receive.
sellstringToken to sell: "ETH", a symbol (USDG, AAPL...) or an address.
buystringToken to buy: "ETH", a symbol or an address.
amountstringAmount of the sell token in human units, e.g. "0.01".
slippage optionalnumberMax slippage in percent (default 0.5).
Example arguments
{
  "from": "0x15d24b87794b22c283138149560136fce2e0aca1",
  "sell": "ETH",
  "buy": "USDG",
  "amount": "0.001",
  "slippage": 0.5
}

prepare_revokePrepare a revoke

Builds a signing link that removes an approval: approve(spender, 0) for an ERC-20, or setApprovalForAll(operator, false) for an NFT collection (detected on-chain). Reads the current allowance first and says if there is nothing to revoke.

ArgumentTypeMeaning
ownerstringWallet that gave the approval (it signs the revoke).
tokenstringToken or NFT contract address.
spenderstringSpender or operator to remove.
Example arguments
{
  "owner": "0x15d24b87794b22c283138149560136fce2e0aca1",
  "token": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
  "spender": "0xB477751B76CF82d00a686A1232f5fCD772414Af3"
}

Build

prepare_token_deployPrepare a token deploy

Builds a signing link that deploys a new fixed-supply ERC-20 from Toolhood's open-source contract (compiled once with solc, source on /docs): 18 decimals, the whole supply minted to owner (or to the signer when owner is empty), no owner powers, no mint, no tax, no pause. Supply is in whole tokens. The deploy is estimated on-chain when owner is given. After signing, the user can ask their AI to read the new token back with scan_token.

ArgumentTypeMeaning
namestringToken name, e.g. "Harbor Coin".
symbolstringTicker, letters and digits, e.g. "HARBOR".
supplystringTotal supply in whole tokens, e.g. "1000000000" (1 to 10^30).
owner optionalstringReceives the whole supply and is the expected signer. Optional: empty = whoever signs.
Example arguments
{
  "name": "Harbor Coin",
  "symbol": "HARBOR",
  "supply": "1000000000",
  "owner": "0x15d24b87794b22c283138149560136fce2e0aca1"
}

ReferenceResults

  • content[0].text: a one-line summary, a blank line, then compact JSON. This is what your AI reads.
  • structuredContent: the same data as an object, for clients that use it.
  • isError: true with a plain message when a call fails (bad address, unknown token, chain unreachable).
  • Prepare tools put the signing link in data.url and the decoded steps next to it.

ReferenceLimits

One table drives every limit; the numbers here come from the engine.

TierTool callsAskHow
Free60 / min20 / dayNo key, no sign-in. Counted per IP address.
Access key120 / min50 / daySend Authorization: Bearer th_live_… (create keys on /keys with a wallet signature).
Holder600 / min200 / dayA key whose wallet holds at least 1,000,000 $TOOLHOOD, read on-chain. after launch

The holder tier reads your $TOOLHOOD balance on-chain at the moment you call, from the wallet that owns your key. Minimum: 1,000,000 $TOOLHOOD. See $TOOLHOOD.

ReferenceErrors

REST errors look like {"error": {"code", "message", "retryAfter?"}}. Over MCP the same message arrives as a tool result with isError: true.

StatusCodesMeaning
400bad_args, bad_address, bad_amount, unknown_argAn argument is missing or malformed. The message names it.
401invalid_key, unauthorized, session_expiredThe key or session is not valid. Remove the header to fall back to the free tier.
403too_many_keysThe wallet already has the maximum number of keys. Revoke one first.
404unknown_tool, not_found, no_contract, unknown_tokenThe tool, transaction, contract or token does not exist on Robinhood Chain.
422revertedThe simulation says this transaction would fail, with the reason when the contract gives one.
429rate_limited, quotaToo many calls a minute (wait retryAfter seconds), or today's Ask questions are used up (resets 00:00 UTC).
502 / 503upstream, rpc_unavailable, explorer_unavailableA data source did not answer. Try again; Status shows which one.