Stabledrop escrow payments

Prepare Escrow Payment

prepare_escrow_payment

Work out where a payment must go, before anybody signs or sends anything.

seller and nominal_buyer may each be a wallet address OR AN EMAIL ADDRESS — an email is converted to the wallet that person owns, so you never need to know a wallet to use this.

The parties are checked against the sanctions lists before an address is given. If any of them is listed the answer is error: sanctioned_party with no address, and the payment cannot be made through this service.

Returns the escrow address these terms produce, and TWO ways to fund it. Both end at the same address holding the same money; they differ only in who sends the transaction.

Transfer it yourself. Send the tokens to the address from any wallet — a browser wallet, a hardware wallet, an exchange withdrawal. Nothing to sign for us, and no payer needed, because the escrow never asks who paid: it reads its own balance. Then call settle_escrow_payment with no signature and we create the escrow around what is there.

Or let us relay it. Pass payer and this returns an EIP-3009 authorization for them to sign. We broadcast it and pay the gas, so the payer needs no gas at all. This is the only one an agent can complete unattended, and the only one that needs a key anywhere.

Either way the address is the same, because it is a pure function of the terms. That is also what makes the relayed form safe: the payer signs to as part of the authorization, committing to every term at once — alter any of them afterwards and the address moves and the signature stops matching.

amount is in the TOKEN's base units (1 USDC = 1000000), because that exact figure is one of the terms the address derives from.

expiry_timestamp is an absolute Unix time — when the dispute window closes. 0 settles instantly with no recourse. There is no default: "instant, deliberately" and "nobody said" are different, and a caller must not discover afterwards which one they got.

nominal_buyer is who may dispute and receives a refund. For an agentic payment this should be the PERSON, not the agent — they are the one who will later read a report and decide whether to object.

seller and nominal_buyer may each be a wallet address OR an email address. An email resolves to the wallet Privy holds for that person — made for them if they have never logged in — and the same email always resolves to the same wallet, so the address derived here is the one settle_escrow_payment derives too. The resolved wallets come back under parties. A seller given by email is paid into that wallet; they sign in with the email to reach it.

external_id keeps two otherwise-identical payments apart, and is one of the terms the address derives from. Leave it out and a unique one is generated. That is the right default: two payments matching in seller, amount, maturity and buyer would otherwise derive to the SAME address, and funding the second sends money into the first escrow — recoverable only after that one is claimed, and only to ITS buyer.

⚠️ PASS BACK THE external_id THIS RETURNS, not the one you sent. A generated one is only knowable from the result, and settle derives the address again from whatever it is given: a different id is a different address, and the money is at this one.

Supply your own for the opposite behaviour — a checkout hash gives "one checkout, one escrow", so re-presenting the same purchase returns the same address rather than a second.

description is what the payment is FOR, in the buyer's own words — ask them for it rather than defaulting. It is what they will be looking at in the dashboard weeks later deciding whether to dispute, and "Escrow payment" tells them nothing about which one this was. It does not affect the address, so it can be set freely here.

brand is the white-label partner the payment is being made under, if any (the ?b= id, e.g. escrow-me). It is recorded on the contract for attribution only: it does not affect the address, and a malformed one is ignored rather than refused.

product_name is what is being bought, shown on both parties' dashboards. Display only, like brand. A seller or nominal buyer given by email is recorded with that email as well, so the escrow shows to them the way a request made on the site does.

⚠️ 1 to 160 characters. Longer is refused HERE rather than at the chain, where the check happens after the money has already moved.

arbiter is who decides a dispute. Leave it out for the default arbiter, which is almost always right. It is one of the terms the address derives from, so pass the same value to settle_escrow_payment.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`brand`	No
`payer`	No
`amount`	Yes
`seller`	Yes	Who gets paid: a wallet address (0x…) OR an email address. An email is converted to the wallet that person owns, created for them if they have never signed in; the same email always gives the same wallet.
`arbiter`	No
`description`	No		Escrow payment
`external_id`	No
`product_name`	No
`token_symbol`	No		USDC
`nominal_buyer`	Yes	Who may dispute and receives any refund — the PERSON, not the agent: a wallet address (0x…) OR an email address. An email is converted to that person's wallet, created for them if they have never signed in.
`expiry_timestamp`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 1, 2026

addedInput schema / properties / arbiter

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

Changed2 schema fields changedOct 1, 2026

addedInput schema / properties / brand

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / product_name

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

Changed2 schema fields changedSep 18, 2026

addedInput schema / properties / nominal_buyer / description

Added value: +"Who may dispute and receives any refund — the PERSON, not the agent: a wallet address (0x…) OR an email address. An email is converted to that person's wallet, created for them if they have never signed in."

addedInput schema / properties / seller / description

Added value: +"Who gets paid: a wallet address (0x…) OR an email address. An email is converted to the wallet that person owns, created for them if they have never signed in; the same email always gives the same wallet."

First observedSep 17, 2026

TDQS

A4.5/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so thoroughly: sanctions screening with the exact error code (sanctioned_party), address derivation as a pure function of terms, the email-to-wallet resolution side effect (wallets may be created), gas sponsorship on the relayed path, no default for expiry_timestamp, the 160-char pre-chain validation, and the warning to pass back the generated external_id. These are exactly the mutation/side-effect and failure-mode details annotations would otherwise supply.

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

Conciseness3/5

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

Warnings are front-loaded and the sectioned structure with bolded anchors aids scanning, but the email-or-address rule is stated almost verbatim twice (opening paragraph and the bolded sentence near the end), and the length is inflated for a derivation call. The repetition and density cost it despite otherwise sensible ordering.

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

Completeness4/5

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

For an 11-parameter tool with an output schema, the description covers the semantics an agent needs and does not need to restate return values. It is nearly complete, with token_symbol's role in interpreting amount and any permission requirements for the relayed path being the only real omissions.

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

Parameters5/5

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

Schema description coverage is only 18%, so the description must compensate and largely does: it explains email-or-address resolution for seller and nominal_buyer, amount in token base units (1 USDC = 1000000), expiry_timestamp as absolute Unix time with 0 meaning instant, external_id generation and address impact, description's purpose, brand/product_name as display-only, and arbiter's default. Only token_symbol (default USDC) goes unmentioned, which is a minor gap against otherwise complete coverage.

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 object ('Work out where a payment must go, before anybody signs or sends anything') and then names the exact artifact it produces (the escrow address plus two funding routes). It routes clearly against its sibling settle_escrow_payment, which it names as the follow-up step, so an agent can place this tool in the workflow 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 Guidelines4/5

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

It gives clear when-to-use context ('before anybody signs or sends anything'), the sequencing into settle_escrow_payment, and an explicit fork between self-transfer and relayed EIP-3009 (with the note that only the relayed path works unattended). It does not, however, contrast itself against the other escrow siblings such as check_escrow_payment or payment_qr, so exclusions are left implicit.

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

All Stabledrop escrow payments tools Inspect

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

Need Help?