> For the complete documentation index, see [llms.txt](https://docs.doma.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.doma.xyz/agentic-commerce/mcp-server/tools.md). # Tool Reference You don't need this page to use the server — your MCP client discovers the tools, parameters, and schemas on connect, and the descriptions the agent reads are more detailed than the summaries here. This page is for deciding whether to connect. {% hint style="info" %} **Your client's tool list is authoritative.** Tools ship to testnet before mainnet, so the two endpoints can differ for a while. {% endhint %} ## Read tools No authentication. Nothing is signed, nothing is spent. ### Domains | Tool | What it does | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `domains.lookup.v1` | Look up a tokenized domain by name: expiry, registrar, nameservers, ownership token, fractionalization status, active offer count. | | `domains.search.v1` | Search tokenized domains, filtered by name fragment and TLD. Paginated. | | `domains.check.v1` | Check availability for registration across supported TLDs (RDAP). | | `domains.pricing.v1` | Per-registrar USD pricing for one operation (registration, renewal, or transfer), plus availability and coupon validation. | | `domains.nameservers.v1` | The nameservers currently configured for a tokenized domain. | ### DNS | Tool | What it does | | ---------------- | ----------------------------------------------------------------------------------- | | `dns.records.v1` | The DNS record sets for a tokenized domain, optionally filtered by host. Paginated. | ### Marketplace | Tool | What it does | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `marketplace.listings.v1` | Active listings for tokenized domains, filtered by name, TLD, or network. Paginated. | | `marketplace.offers.v1` | Active offers on a tokenized domain, optionally filtered by offerer. Paginated. | | `marketplace.quote.v1` | What an order actually costs: total price, fee breakdown (treasury fee, royalties), and seller proceeds — for a listing or an offer. | ### Tokens | Tool | What it does | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `tokens.info.v1` | On-chain details for a Doma token by token ID: owner, network, contract, validity. | | `tokens.price.v1` | USD price, 24h change, TVL, and volume for one or more Doma token contracts. | | `tokens.fractional.v1` | Fractional (ERC-20) domain tokens with their contracts and trading venue, filtered by status, launch timing, name, TLD, or network. | | `tokens.quote.v1` | Exact-in swap quote, routed automatically between the bonding curve and Uniswap pools depending on whether the token has graduated. | ### Bridge | Tool | What it does | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bridge.quote.v1` | Preview a cross-chain bridge via Relay: destination amount, relayer and gas fees, and ETA for moving ETH or USDC between Doma and Base. USDC means each chain's canonical USD stablecoin — `USDC` on Base, `USDC.e` on Doma. Same-asset in v1. Reports whether executing it would be gasless — bridging out of Doma is, bridging in is not. | | `bridge.status.v1` | Track a bridge by its Relay `requestId`: whether the destination fill is waiting, pending, succeeded, failed, or refunded, with the origin and destination transaction hashes. | ### Wallet & server | Tool | What it does | | -------------------- | ------------------------------------------------------------------------------------------------------------ | | `wallet.balances.v1` | A wallet's Doma balances: fractional domain tokens, currency tokens, native balances, and specified ERC-20s. | | `server.ping.v1` | Liveness probe. Reports the server timestamp and which Doma network this server executes on. | ## Execute tools These sign and broadcast from your wallet and require [authorization](/agentic-commerce/mcp-server/authorization.md). Each one is gated by your spend allowance, the per-transaction limit, and the rate limit. | Tool | What it does | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `marketplace.buy.v1` | Buy a listed tokenized domain: resolves the listing (cheapest active one unless you name an order), pays the total price, receives the ownership token — one atomic gasless operation with the payment approval and the Seaport fulfillment batched together. | | `tokens.swap.v1` | Swap tokens on Doma, exact-in, routed like `tokens.quote.v1` — one atomic gasless operation with the approval and the trade batched together. | | `bridge.execute.v1` | Bridge an asset (ETH, or USDC — each chain's canonical stablecoin, `USDC.e` on Doma) out of Doma to Base via Relay: quotes the route, then signs and broadcasts the origin deposit as one atomic gasless operation, and returns a Relay `requestId` to track the fill with `bridge.status.v1`. Same-asset and out-of-Doma only; charges the deposited USD value. | | `agent.execute.v1` | Sign and broadcast a prepared transaction. The escape hatch for operations without a dedicated tool; ERC-20 approvals are refused. | | `agent.allowance.v1` | Report the session's wallet, network, budget, and limits. Read-only, but session-scoped. | | `agent.setCap.v1` | Lower the spend cap. Raising requires re-consent. | | `agent.revoke.v1` | Revoke the spend allowance. Kill switch. | Execute tools are deliberately **listed to unauthorized clients** so an agent can see what's possible and prompt you to authorize, rather than concluding the server is read-only. Calling one without a token returns a `401` challenge. ### Limit orders Conditional limit orders rest a swap of one Doma token for another until it fills at your target price, expires, or you cancel. They fill **off-session** — later, by Doma's orders-worker — which makes them work differently from the other execute tools. All six require [authorization](/agentic-commerce/mcp-server/authorization.md) (they act on your session wallet), but only the two router-approval tools broadcast on-chain: * **They don't draw on your USD spend allowance.** The real swap lands when a fill does, which the spend ledger can't price ahead of time. A limit order is bounded instead by a **standing on-chain allowance** you grant to the DomaOrderRouter — a shared pool the router draws down as fills land — and `defi.revokeRouter.v1` is the kill switch. See [Authorization & Spend Controls](/agentic-commerce/mcp-server/authorization.md#limit-orders-a-separate-authority-track). * **Creating and cancelling sign nothing** and cost nothing against the budget — they only write the order record. The router approval is the only on-chain, gasless operation here, and because a grant moves no funds it is charged just the minimum floor, not a spend. | Tool | What it does | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `defi.approveRouter.v1` | Approve the DomaOrderRouter to spend one of your ERC-20 tokens, so limit orders on that token can fill. One atomic gasless operation; the spender is fixed to the server-resolved router, never caller-supplied. This is the one sanctioned standing approval. | | `defi.revokeRouter.v1` | Zero that approval — the kill switch for further fills on that token. Existing open orders remain but cannot fill until re-approved. | | `defi.limitOrder.create.v1` | Place a conditional limit order for the session wallet against a target price. Writes the order record only; approve the router first or it cannot fill. | | `defi.limitOrder.cancel.v1` | Cancel one of your `OPEN` or `PARTIALLY_FILLED` orders by ID. | | `defi.limitOrder.get.v1` | Fetch one of your limit orders by ID, with status and fill progress. Session-scoped read. | | `defi.limitOrder.list.v1` | List your limit orders, newest first, optionally filtered by status. Session-scoped read. | ## Not yet available * **Selling.** Listing a domain for sale and accepting an offer are not exposed as tools. Reading listings and offers, quoting them, and buying are. * **DNS and nameserver writes.** `dns.records.v1` and `domains.nameservers.v1` read; the matching write tools are built but not yet released. Use the [Doma CLI](/agentic-commerce/doma-cli.md) meanwhile. * **Registration.** Checking availability and pricing is here; registering a domain is not. See the [MPP skill](/agentic-commerce/skills/mpp.md). * **Cross-asset bridging and subdomains.** `bridge.execute.v1` bridges the same asset out of Doma — ETH→ETH, or USDC→USDC where USDC is each chain's stablecoin (`USDC.e` on Doma, so Relay swaps USDC.e→USDC across the hop). Bridging *different* assets (e.g. ETH↔USDC) and subdomains are [Doma CLI](/agentic-commerce/doma-cli.md) only. * **Solana live balance reads.** `wallet.balances.v1` reads EVM chains live and lists anything it skipped. ## Versioning Every tool name carries an explicit version suffix (`domains.lookup.v1`). Breaking changes ship as a new version alongside the old one, so an agent pinned to `.v1` keeps working; backwards-compatible changes land in place. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.doma.xyz/agentic-commerce/mcp-server/tools.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.