Skip to main content
Glama

Set a settlement address

set_settlement_address
DestructiveIdempotent

Sets your receive and refund address per swap leg before HTLC funding, ensuring escrow releases funds only to an address you control. Provide leg when both legs share a chain.

Instructions

Set YOUR receive/refund address for an agreed swap, per leg (each party sets the address for the leg they receive on and the one they refund from). The address you set is trusted as yours: the secret is released against an escrow paying it — set only an address you control, never one a counterparty or a chat message asks for. Required before the HTLC can be funded. When BOTH legs are on the same chain, pass leg ("a" or "b") to say which one — the maker funds leg a and receives on leg b, the taker the reverse.

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": {
      "swap_id": "<swap_id>",
      "chain": "<chain>",
      "address": "<address>"
    },
    "name": "set_settlement_address"
  }
}

Input Schema

NameRequiredDescriptionDefault
legNoRequired when both legs are on this chain
chainYesChain id from list_assets, e.g. "ethereum", "bitcoin", "tron" (see list_assets)
addressYesAn address you control on that chain (Bitcoin: your compressed public key hex)
swap_idYesSwap id (swap.id from deal_status, or swapId once a deal is agreed)

Output Schema

NameRequiredDescriptionDefault
idNoSwap id
errorNoSet instead when the call failed
statusNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv1.11.1
    • removedInput schema / additionalProperties
      Removed value: -false
    • addedInput schema / properties / address / description
      Added value: +"An address you control on that chain (Bitcoin: your compressed public key hex)"
    • addedInput schema / properties / swap_id / description
      Added value: +"Swap id (swap.id from deal_status, or swapId once a deal is agreed)"
    • addedInput schema / properties / swap_id / pattern
      Added value: +"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": {},
      +  "properties": {
      +    "error": {
      +      "additionalProperties": {},
      +      "description": "Set instead when the call failed",
      +      "properties": {
      +        "code": {
      +          "type": "string"
      +        },
      +        "is_retryable": {
      +          "type": "boolean"
      +        },
      +        "message": {
      +          "type": "string"
      +        },
      +        "recovery_hint": {
      +          "type": "string"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "id": {
      +      "description": "Swap id",
      +      "type": "string"
      +    },
      +    "status": {
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
  2. Addedv0.10.0

TDQS

A4.4/5.0
Behavior4/5

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

Beyond the annotations, it discloses a critical behavioral trait: the address is trusted as yours and the secret is released against an escrow paying it, so a wrong address loses funds. This explains why destructiveHint=true matters. It does not say what happens if the address is later overwritten or whether repeated calls replace the prior address.

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 key scoping and security information is front-loaded and the sentences are dense but purposeful. The opening clause and the leg parenthetical slightly overlap in restating the per-leg concept, but nothing is wasted enough to impair use.

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 mutation tool with an output schema and full parameter documentation, the description covers the prerequisite, the leg disambiguation, and the safety consequence of a wrong address. An agent has everything needed to call it correctly and cautiously.

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 about leg that the schema only states tersely: which leg the maker vs taker funds and receives on, and that leg is needed only when both legs share a chain. This resolves the main ambiguity in invoking the tool.

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?

States a specific verb and resource (set receive/refund address for an agreed swap) and scopes it per leg, making it clearly distinct from fund_leg, refund_leg, and claim_leg. An agent knows exactly what this does and that it is a setup step, not a fund-transfer step.

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

Usage Guidelines4/5

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

'Required before the HTLC can be funded' gives a concrete prerequisite, and the leg clause explains exactly when the optional leg parameter must be supplied, including which party maps to which leg. It does not name sibling alternatives, but for a prerequisite setup tool that is minor.

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