Skip to main content
Glama
Sign In

Bitcoin Stratigraphy Enterprise Data Engine & Agent Notary Hub

by app.replit.bitcoin-stratigraphy-dashboard--charlesstrogish
OverviewDiscussionsAdmin

clearing.create_contract

Create a worker contract; return its contract ID (escrow_id) and Lightning funding invoice (invoice). Requires fresh buyer NIP-98 authentication. New request IDs create separate contracts even for the same task_hash; byte-identical retries by the same buyer reuse the contract and its unexpired invoice. Funds remain merchant-controlled; an unpaid invoice is not funding. No automated payouts. Note: Contract state polling, listing, cancellations, and automated refunds are intentionally disabled in this namespace by design to enforce strict manual payout verification and prevent automated drain attacks.

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": {
      "worker_pubkey": "<worker_pubkey>",
      "task_hash": "<task_hash>",
      "amount_sats": "<amount_sats>"
    },
    "name": "clearing.create_contract"
  }
}

Input Schema

NameRequiredDescriptionDefault
task_hashYesTask commitment as exactly 64 lowercase hexadecimal characters (32 bytes), without a 0x prefix. When production settlement is enabled, its numeric value must be less than 21888242871839275222246405745257275088548364400416034343698204186575808495617.
amount_satsYesContract funding amount in whole satoshis: an integer from 1 through 9007199254740 inclusive. Fractional satoshis are not accepted.
worker_pubkeyYesWorker's Nostr public key: exactly 64 lowercase hexadecimal characters (32-byte x-only secp256k1 key), without a 0x prefix. Must represent a valid curve point.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • addedInput schema / properties / amount_sats / description
      Added value: +"Contract funding amount in whole satoshis: an integer from 1 through 9007199254740 inclusive. Fractional satoshis are not accepted."
    • addedInput schema / properties / amount_sats / examples
      Added value: +[
+  123
+]
    • addedInput schema / properties / task_hash / description
      Added value: +"Task commitment as exactly 64 lowercase hexadecimal characters (32 bytes), without a 0x prefix. When production settlement is enabled, its numeric value must be less than 21888242871839275222246405745257275088548364400416034343698204186575808495617."
    • addedInput schema / properties / task_hash / examples
      Added value: +[
+  "0101010101010101010101010101010101010101010101010101010101010101"
+]
    • addedInput schema / properties / worker_pubkey / description
      Added value: +"Worker's Nostr public key: exactly 64 lowercase hexadecimal characters (32-byte x-only secp256k1 key), without a 0x prefix. Must represent a valid curve point."
    • addedInput schema / properties / worker_pubkey / examples
      Added value: +[
+  "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798"
+]
  2. Added

TDQS

A4.4/5.0
Behavior5/5

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

Annotations only say this is a non-read-only, non-idempotent, non-destructive open-world call; the description goes well beyond that by explaining retry/deduplication semantics, that funds stay merchant-controlled, that an unpaid invoice is not funding, and that no automated payouts or refunds exist. These are exactly the behavioral traits an agent needs before committing to a write that moves money.

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 purpose and return values are front-loaded in the first sentence, followed by ordered caveats about auth, retries, and funding. It is dense but nearly every sentence carries decision-relevant information; the closing note on disabled namespace features is slightly long-winded but justified.

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?

With no output schema, the description compensates by naming the returned fields, and it covers authentication, retry semantics, funding state, and the deliberate absence of payout automation. For a money-moving write tool, nothing essential is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so task_hash, amount_sats, and worker_pubkey are already fully documented with patterns, bounds, and examples. The description only references task_hash in passing while explaining deduplication and adds no new syntax or constraint meaning, so the baseline of 3 applies.

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 ('Create a worker contract') and immediately names the two return values, escrow_id and invoice. It is clearly distinguishable from the sibling clearing.settle_contract, which handles the later funding 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?

Gives real usage context: fresh buyer NIP-98 authentication is required, and new request IDs produce separate contracts while byte-identical retries reuse one. It also rules out polling, listing, cancellation, and refund paths by design, though it does not name an explicit alternative tool to reach for instead.

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

All Bitcoin Stratigraphy Enterprise Data Engine & Agent Notary Hub toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources