Herramientas MCP

Catalog for the hosted MCP endpoint https://mcp.domesticmonero.com/mcp. Tools run as your Mini App session. Read MCP agents for the mental model; MCP agent setup for install.

Confirm tool names against a live tools/list after connect. Names below match the product server (auth_whoami … trade_refund).

Auth / Market

Tool	When to use	Side effect	Key inputs	Notes
auth_whoami	First call after connect	None (read)	(none)	Returns the profile for this Bearer. Must match the Mini App user who published the token.
ticker_rates	Need market rates before creating or judging an offer	None (read)	(none)	Reference market data; UI says Market rate.

Offers

Tool	When to use	Side effect	Key inputs	Notes
offer_query	Browse or filter the offer list	None (read)	filters?, pagination?	Filters may include type, asset, XMR range, ratio, state, self_only / exclude_self.
offer_create	Post a BUY or SELL offer	Creates an open offer	type, asset, xmr_amount, rate	Rate must stay within the live ± band vs market. Wallet gates apply like the Mini App.
offer_accept	Take someone else’s open offer	Opens a trade	id (offer id)	You become Buyer or Seller per offer type.
offer_cancel	Pull your open offer	Cancels the listing	id	Maker action on Open only — not an edit form.

Trades

Tool	When to use	Side effect	Key inputs	Notes
trade_query	List your trades	None (read)	filters?, pagination?	Filter by status, asset, role, ref prefix, etc.
trade_get	Inspect one trade by ref	None (read)	ref	Source of chip, deadlines, refund_eligible.
trade_stake_info	Seller needs stake deposit details	None (read)	ref	Multisig wallet address / stake instructions for the seller role.
trade_cancel	Cancel while the Mini App still allows it	Cancels trade when eligible	ref, reason?	Created only in the app — after Staked, use product rules, not this as a dispute button.
trade_payment_proof	Buyer submits on-chain proof	Records TX for verification	ref, tx_hash, crypto, amount	Confirmations vary by asset — Payment proof.
trade_acknowledge_share	Confirm you saved the trade share	Marks share acknowledged	ref	Same moment as Agree on “Save your trade share”.
trade_resend_share	Lost share; ask Telegram resend	Triggers resend path	ref	UI: “Lost your trade share? Resend it via Telegram.”
trade_withdraw	Buyer claims XMR at the right chip	Withdraws when eligible	ref, share	Needs your trade share. Profile XMR address must already be set.

Profile

Tool	When to use	Side effect	Key inputs	Notes
profile_get	Read wallets, prefs, PGP flags	None (read)	(none)	Same payload family as auth_whoami.
profile_trading_limits	Check open-offer / active-trade caps	None (read)	(none)	Soft gates before create/accept.
profile_update	Change wallets or preferences	Updates profile	wallet_addresses?, notification_preferences?, ui_preferences?, …	Locked wallets while a trade is active still apply.

Refund

Tool	When to use	Side effect	Key inputs	Notes
trade_refund_preview	Seller checks refund eligibility	Issues one-time confirm_token when eligible	ref	If not eligible: confirm_token is null.
trade_refund	Confirm restitution after preview	Refunds when eligible	ref, share, confirm_token	Always preview first. Stale or missing confirm_token fails. Same trade-share rules as Request refund.

Recipes

Failure stops are in bold. Do not invent chip transitions — if unsure, trade_get and compare to Your first trade.

1. Who am I?

1. Call auth_whoami.
2. Stop if the profile is empty, errors, or is not the Mini App account you expect → check Bearer, /mcp URL, and that the token was not revoked.

2. Find an offer and open a trade

1. offer_query with filters (asset, type, …).
2. Pick a counterparty offer id (not yours unless you intend self_only workflows).
3. offer_accept with that id.
4. trade_get with the new trade ref.
5. Stop if accept fails (own offer, expired, wallets missing, limits) → fix Profile / pick another offer in the Mini App rules.
6. Acknowledge and store trade share via trade_acknowledge_share when the product requires it — stop if you never copied the share; you will need it later.

3. Create then cancel your own offer

1. ticker_rates (optional) then offer_create with type, asset, xmr_amount, rate.
2. Stop if rate is outside ± market band or wallets are gated.
3. offer_cancel with the created offer id when you no longer want it listed.
4. Stop if cancel fails because the offer is no longer Open (already matched / expired).

4. Trade progress (stake → proof → withdraw)

1. trade_get / trade_query until you know the chip.
2. Seller: trade_stake_info for deposit details; stake in an external Monero wallet (Automatic fee priority).
3. Buyer: send payment on-chain, then trade_payment_proof with tx_hash, crypto, amount.
4. Stop if proof is rejected (wrong asset network, reused TX, timeout) — see Payment proof.
5. Buyer at the verifying / receive stage: trade_withdraw with ref + share.
6. Stop if share mismatches or chip is wrong — MCP does not skip 2-of-3. 2-of-3 multisig.

5. Refund (two-step)

1. trade_refund_preview with ref.
2. Stop if refund_eligible is false or confirm_token is null — not refundable yet (or ever for that state).
3. trade_refund with ref, your seller share, and that fresh confirm_token.
4. Stop if confirm fails (stale token, wrong share, wrong ref) → run preview again; do not reuse an old confirm_token.

Troubleshooting

Symptom	Likely cause	What to do
HTTP 401 / Authorization Bearer required (DM_TOKEN)	Missing or non-Bearer auth	Send Authorization: Bearer dm_…
Connect fails / host not MCP	URL is host root without /mcp	Use https://mcp.domesticmonero.com/mcp
Tools missing in the client	Client not connected, or tool list not refreshed	Reload MCP; confirm initialize succeeds; call tools/list
auth_whoami wrong or empty	Wrong/revoked token, or pasted someone else’s	Revoke + publish; verify Profile user
Token worked yesterday, fails today	Revoked or rotated (only one active)	Publish again; update client header
trade_refund fails	No preview, stale confirm_token, or bad share	trade_refund_preview again; use new token + correct share
Offer vanished after agent “cleanup”	offer_cancel on your Open offer	Intended side effect — recreate if needed
Withdraw / refund blocked	Missing trade share or wrong chip	Resend share path; wait for eligible state; see multisig doc

Human support: official bot /support + Trade #ref — Cancel Trade, Cancel Offer, and /support.