Skip to main content
Glama

Create a swap (deposit address)

create_swap

Opens a non-custodial cross-chain swap and returns a one-time deposit address after the user agrees to a quote and supplies destination and refund addresses.

Instructions

Open a non-custodial swap and return a one-time deposit address. Use it only after the user has seen a quote, agreed to the amount and route, and given you both addresses. from_asset, to_asset and amount mean the same as in get_quote: pass the values the user agreed to. destination_address must be on to_asset's chain and refund_address on from_asset's chain, usually the sending wallet; BTC to ZEC, for example, needs a Zcash payout address and a Bitcoin refund address. NEVER invent, guess or reuse addresses from elsewhere in the conversation. Set protocol only to keep the route the user picked from get_quote's alternatives. The tool re-quotes with the real addresses, sets the minimum output from that quote and returns an error rather than a deposit if the amounts changed. Nothing moves until the user sends exactly send_exactly from their own wallet before expires_at; the server never holds keys or signs. If the swap cannot complete, funds go back to refund_address. Each call creates a new deposit address, so do not call it again to "retry" a swap the user already funded. Rate-limited per caller (about 6 swaps in a burst, then one every 20 seconds).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "from_asset": "<from_asset>",
      "to_asset": "<to_asset>",
      "amount": "<amount>",
      "destination_address": "<destination_address>",
      "refund_address": "<refund_address>"
    },
    "name": "create_swap"
  }
}

Input Schema

NameRequiredDescriptionDefault
amountYesExact amount of from_asset the user will send, in normal decimal units ("100", "0.05"), not base units.
protocolNoOptional. Pin this route, e.g. the alternative the user chose from get_quote. Omit to use the best route at creation time.
to_assetYesDestination (what the user receives). asset. Either an exact asset_id from list_assets ("BASE.USDC-0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913") or CHAIN.SYMBOL shorthand ("ZEC.ZEC", "BTC.BTC", "ETH.ETH", "SOL.SOL", "BASE.USDC"). Shorthand resolves to the verified asset; if it is ambiguous the error lists the exact ids to use.
from_assetYesSource (what the user sends). asset. Either an exact asset_id from list_assets ("BASE.USDC-0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913") or CHAIN.SYMBOL shorthand ("ZEC.ZEC", "BTC.BTC", "ETH.ETH", "SOL.SOL", "BASE.USDC"). Shorthand resolves to the verified asset; if it is ambiguous the error lists the exact ids to use.
refund_addressYesAddress the user gave you on the source chain (from_asset's chain), usually the wallet they send from. Refunds go here if the swap fails or the price drops below the floor.
destination_addressYesAddress the user gave you on the destination chain (to_asset's chain). Swapped funds are paid here.

Output Schema

NameRequiredDescriptionDefault
swap_idYesId for get_swap_status and report_deposit.
protocolYesRoute used.
warningsYesMust be shown to the user (memo requirements, unverified tokens).
next_stepNoWhat to tell the user next.
expires_atNoISO time after which the deposit address must not be used.
minimum_outYesGuaranteed minimum payout; below this the swap refunds.
deposit_memoYesMemo the deposit MUST carry, or null when none is needed.
expected_outYesExpected payout with asset and chain.
explorer_urlNoPublic tracking link, when the route has one.
send_exactlyYesExact amount, asset and chain the user must send.
refund_addressYesRefund address, echoed back for the user to check.
token_contractNoToken contract of from_asset, when it is a token rather than a native coin.
deposit_addressYesOne-time address to send the funds to.
destination_addressYesPayout address, echoed back for the user to check.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes far beyond the annotations (readOnly=false, openWorld=true, idempotent=false): discloses non-custody, that the server never holds keys or signs, that it re-quotes with real addresses and errors rather than issuing a deposit if amounts moved, that funds return to refund_address on failure, and that each call mints a new deposit address. It also adds a concrete rate limit (~6 in a burst, then one per 20s) that no annotation conveys.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The precondition and the core behavior are front-loaded, and most sentences carry distinct operational information (chain pairing, protocol pinning, re-quote, refund path, rate limit). It is dense and runs long, but no sentence is filler; the address-invention warning is the only line bordering on generic.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter, open-world, non-idempotent write operation, the description covers safety, failure modes, refunds, expiry/send_exactly obligations, rate limits, and re-invocation risk. Since an output schema exists, it correctly omits return-value detail and spends its words on behavior instead.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: destination_address must be on to_asset's chain and refund_address on from_asset's chain, with a worked BTC→ZEC example, and protocol is constrained to the route the user already chose. It stops short of adding format detail for amount beyond echoing the get_quote reference, which the schema already covers.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ("Open a non-custodial swap and return a one-time deposit address") and implicitly distinguishes itself from get_quote and get_swap_status by describing creation rather than quoting or polling. An agent can tell exactly what this produces without reading the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit precondition chain (user has seen a quote, agreed to amount and route, supplied both addresses) and names get_quote as the source of the values to pass. It also states an explicit when-not: do not re-call to "retry" a swap already funded, and pin protocol only when preserving a chosen route.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.