Create a swap (deposit address)
create_swapOpens 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
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Exact amount of from_asset the user will send, in normal decimal units ("100", "0.05"), not base units. | |
| protocol | No | Optional. Pin this route, e.g. the alternative the user chose from get_quote. Omit to use the best route at creation time. | |
| to_asset | Yes | Destination (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_asset | Yes | Source (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_address | Yes | Address 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_address | Yes | Address the user gave you on the destination chain (to_asset's chain). Swapped funds are paid here. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| swap_id | Yes | Id for get_swap_status and report_deposit. | |
| protocol | Yes | Route used. | |
| warnings | Yes | Must be shown to the user (memo requirements, unverified tokens). | |
| next_step | No | What to tell the user next. | |
| expires_at | No | ISO time after which the deposit address must not be used. | |
| minimum_out | Yes | Guaranteed minimum payout; below this the swap refunds. | |
| deposit_memo | Yes | Memo the deposit MUST carry, or null when none is needed. | |
| expected_out | Yes | Expected payout with asset and chain. | |
| explorer_url | No | Public tracking link, when the route has one. | |
| send_exactly | Yes | Exact amount, asset and chain the user must send. | |
| refund_address | Yes | Refund address, echoed back for the user to check. | |
| token_contract | No | Token contract of from_asset, when it is a token rather than a native coin. | |
| deposit_address | Yes | One-time address to send the funds to. | |
| destination_address | Yes | Payout address, echoed back for the user to check. |