Enables AI agents to perform non-custodial 2-of-3 Bitcoin escrow payments using the Lightning Network for secure agent-to-agent transactions.
Also known as yuvlero/mark, mark, @yuvlero/mark
- Stars
- 0
- Tools
- 20
- Downloads, 30 days
- —
- Latest version
- 0.4.0
- Last commit
- Nov 14, 2026
- License
- MIT
What is Mark: Agent Escrow MCP?
Mark: Agent Escrow enables AI agents to perform non-custodial 2-of-3 Bitcoin escrow payments using the Lightning Network for secure agent-to-agent transactions. It exposes 20 tools, such as pubkey, escrow_create, escrow_reputation.
Summary generated from the project's README
About Mark: Agent Escrow MCP server
Enabling AI agents to conduct secure, non-custodial financial transactions is the primary function of Mark. It allows agents to buy and sell services from one another using a 2-of-3 Bitcoin escrow system on the Lightning Network. By using this server, agents can sign terms, fund deals, and receive payouts without needing to trust a central authority or hand over custody of their private keys. Each agent maintains its own identity locally, and the escrow service only holds an arbiter key to resolve disputes or handle timeouts.
Developers can use this as a CLI tool or run it as an MCP stdio server to integrate escrow capabilities into AI workflows. The system requires Node.js 20.19 or higher and a Lightning-compatible wallet, such as Bark, to manage real Bitcoin on the mainnet. For testing without real money, the mutinynet network can be specified. The server handles the coordination of funds through Satora swaps, ensuring that payments are released only when both parties agree or an arbiter intervenes.
What you can do with it
- 1Automated agent-to-agent paymentsAn AI agent can pay another agent for a specific service like logo design using Bitcoin.
- 2Secure service delivery verificationA buyer agent can review a Markdown summary of a delivered web page before approving a payment.
- 3Testing agent workflowsDevelopers can simulate transactions using test coins instead of real Bitcoin.
Written from the project's README. Every use case is checked against a quote from it.
How to install Mark: Agent Escrow MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Mark: Agent Escrow MCP in Claude Code
$ claude mcp add --env 'MARK_PASSWORD=<YOUR_MARK_PASSWORD>' mark -- npx -y @yuvlero/mark mcpInstall Mark: Agent Escrow MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mark": {
"command": "npx",
"args": [
"-y",
"@yuvlero/mark",
"mcp"
],
"env": {
"MARK_PASSWORD": "<YOUR_MARK_PASSWORD>"
}
}
}
}Install Mark: Agent Escrow MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mark": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@yuvlero/mark",
"mcp"
],
"env": {
"MARK_PASSWORD": "<YOUR_MARK_PASSWORD>"
}
}
}
}Install Mark: Agent Escrow MCP in VS Code CLI
$ code --add-mcp '{"name":"mark","type":"stdio","command":"npx","args":["-y","@yuvlero/mark","mcp"],"env":{"MARK_PASSWORD":"<YOUR_MARK_PASSWORD>"}}'Install Mark: Agent Escrow MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mark": {
"command": "npx",
"args": [
"-y",
"@yuvlero/mark",
"mcp"
],
"env": {
"MARK_PASSWORD": "<YOUR_MARK_PASSWORD>"
}
}
}
}Install Mark: Agent Escrow MCP in Codex
$ codex mcp add mark --env 'MARK_PASSWORD=<YOUR_MARK_PASSWORD>' -- npx -y @yuvlero/mark mcpInstall Mark: Agent Escrow MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mark] command = "npx" args = ["-y", "@yuvlero/mark", "mcp"] [mcp_servers.mark.env] MARK_PASSWORD = "<YOUR_MARK_PASSWORD>"
Install Mark: Agent Escrow MCP in Gemini CLI
$ gemini mcp add -s user -e 'MARK_PASSWORD=<YOUR_MARK_PASSWORD>' mark npx -- -y @yuvlero/mark mcpInstall Mark: Agent Escrow MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mark": {
"command": "npx",
"args": [
"-y",
"@yuvlero/mark",
"mcp"
],
"env": {
"MARK_PASSWORD": "<YOUR_MARK_PASSWORD>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @yuvlero/mark 0.4.0 in an isolated container with no network and no keys. It answered and listed 20 tools.
Mark: Agent Escrow MCP tools 20
Read from the server with tools/listpubkeyThis agent's escrow public key (x-only hex)
escrow_createStart an escrowed deal with another agent so you can pay it (role buyer) or get paid by it (role seller) without trusting it: non-custodial 2-of-3 bitcoin escrow, funded and paid out over Lightning. Terms you write here are signed by both sides and are what the arbiter rules on. Check escrow_limits and escrow_reputation first; next the counterparty calls escrow_accept, then the buyer calls escrow_fund.
escrow_reputationCheck a counterparty before you pay or accept a deal. Public reputation of a pubkey on this escrow server: dealsCompleted, satsTransacted (approx, 2 significant figures), ruled disputesWon/Lost, firstSeen (first funded deal), lastSeen (latest released/refunded deal; null if none). Funded deals only. An indicator, not a guarantee (wash trading between one's own keys is possible). escrow_show/escrow_status/escrow_accept include the counterparty's automatically
escrow_demoNo counterparty yet? Make a first real escrowed purchase from the always-on house seller agent (default offer: 350 sats). First real deal with the escrow server's always-on house seller agent (default offer: a Markdown summary of one public web page for 350 sats; also research for 1,500; no platform fee). REAL MONEY on mainnet, and not instant: the seller checks every few minutes and delivers within the offer's turnaround. Without confirm=true it only previews (offer, cost, inputs, exact terms) and creates nothing. Inputs become the deal description's Key: value lines (url, words, ...; validated locally). With confirm=true it creates the deal as buyer, waits for the seller's accept and returns the Lightning funding invoice; after paying, call escrow_fund with wait=true (that claims the payment into the escrow; funding stays pending until then). The seller delivers in the deal thread (escrow_messages); then release with escrow_approve. Call again to see where the demo deal stands (it resumes; fresh=true starts a new one)
escrow_showDeal terms (what it is for), who accepted (signatures verified locally), evidence, awaiting / action_required_for / arbiterPolicy, and deadlineCountdown: the auto-refund deadline, disputeBy and secondsLeft with a note for your role (a seller who delivered to a silent buyer must dispute before disputeBy)
escrow_acceptAccept the deal terms: verifies termsHash, the escrow address and the arbiter key locally, then signs termsHash with this agent's key (terms v2: the signature also covers the release rule, arbiter mode and deadline). Required from both parties before funding. A buyer is refused (UNSAFE_RULE) when the seller chose an automatic release rule (hash lock / webhook); pass allowCounterpartyRule=true only after the user explicitly agrees
escrow_evidenceAdd a signed, timestamped evidence note to a deal (seller: post the deliverable sha256 after delivering off-band; for the arbiter in a dispute)
escrow_messagesRead a deal's support thread with the operator (signatures verified: operator against the deal's arbiter key). since = cursor from the last read
escrow_messagePost a signed message to a deal's thread (ask the operator a question, explain a dispute, point to evidence). A dispute message does NOT open a dispute: use escrow_dispute for that
escrow_invitesDeals created for this agent's key that wait for its accept (no id needed). all=true lists every deal this key is in; needs filters accept|fund|sign|any; state filters by deal state. Each item has awaiting, action_required_for and nextStep (newer servers also send deadlineCountdown for your role)
escrow_inboxUnread messages across this agent's deals (operator replies, system notices)
escrow_statusEscrow state, proposals, events, and deadlineCountdown (auto-refund deadline, disputeBy, secondsLeft, a note for your role)
Show all 20 toolsShow fewer tools
escrow_fundBuyer: get the Lightning invoice that funds the escrow; after paying, call again with wait=true to lock the funds. Or rail=ark: direct Ark payment with no swap fee: returns the escrow address, the exact sats and the Arkade server (url + key); pay it in ONE payment from an Arkade wallet on that server (Bark / Second cannot pay it: use Lightning), then call with rail=ark, wait=true; smaller payments are not added up (status shows underpaid), a larger one is held whole. Switching rails after one was started needs switchRail=true (only if nothing was paid on the other rail). Refuses (DEADLINE_TOO_CLOSE) when the deal expires (deadline + 1 h grace) within an invoice lifetime for Lightning, or within 10 minutes for rail=ark; an expired deal reports state expired. Refuses (UNSAFE_RULE) a deal whose auto-release rule the seller chose (a hash lock it created, or a webhook rule): the seller could be paid without you. Pass allowCounterpartyRule=true only after the user explicitly agrees. A later call shows the same invoice again while it is unpaid, and says paymentReceived (do NOT pay again) once it is paid. If a claim fails (claimFailed, note) or times out at swap status serverfunded/clientredeeming, call again with resumeClaim=true: it finishes or retries the claim of the paid swap into the escrow and never creates an invoice.
escrow_quotePayout quote: exact payout sats, recommendedInvoiceSats (create the BOLT11 for this) and the accepted min/maxInvoiceSats range
escrow_limitsServer limits: arkade (the Arkade server URL and key this escrow runs on; Ark addresses must come from an Arkade wallet there, not Bark/Second), minimum deal size for Lightning and Ark payouts, platform fee schedule (free up to 33000 sats, then 1% of the whole amount; ruled dispute +max(5%,330) from 3300), free tier, Satora min/max, Ark dust. With sats: upfront fee preview (platform fee, possible dispute fee, estimated swap cost, min/max deal)
escrow_pendingPending payout proposals and their payout details (read-only). Without id: across all this agent's deals, with what each awaits and the co-sign command
escrow_approveSign a pending proposal, or (as payee) propose with a payout: payoutInvoice (fresh BOLT11 for the quote's recommendedInvoiceSats). A co-signer passes no payout, payoutLnaddr, or payoutArk
escrow_disputeOpen a dispute (arbiter auto-signing stops; admin rules)
escrow_refundBuyer: propose refund with a fresh payout (arbiter co-signs after deadline)
escrow_refund_payoutRefund a failed Lightning payout swap to an Ark address (from an Arkade wallet on this escrow's Arkade server)
Configuration
MARK_PASSWORDSecretKeystore password (else MARK_PASSWORD_FILE, else an auto-created 0600 file)
MARK_ESCROW_URLEscrow server URL. Default on bitcoin: https://agentescrow.to
MARK_HOMEDirectory for the agent's key and config (default ~/.mark)
MARK_NETWORKbitcoin (default, real money) or mutinynet (test)
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableyuvlero/mark is public and reachablegithub.com/yuvlero/mark ↗Pass
- Package names this repository as its source@yuvlero/mark names yuvlero/mark as sourcenpmjs.com/package/@yuvlero/mark ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/yuvlero/mark ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @yuvlero/markPass
- No critical advisory in the package or its dependencies180 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model1 tool description and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMark: Agent Escrow for AI agents (bitcoin, Lightning, MCP)
Let your agent pay another agent, and get paid, without trusting it. Mark is a CLI and MCP server for non-custodial 2-of-3 Bitcoin escrow. Two agents sign the terms. The buyer funds over Lightning, the seller delivers and is paid over Lightning, and a neutral arbiter key only matters if they disagree or one goes silent. No accounts and no custody: each agent holds its own key, and every command prints JSON that agents can act on.
Proof: a real agent-to-agent deal on Bitcoin mainnet ran from create to payout in about 9 minutes. Production deal 6930c46a: 5,000 sats, 330 sats platform fee (the fee schedule before 0.3.0; that deal size is free now), 4,634 sats delivered to the seller over Lightning.
Try a real deal in about 10 minutes
You need Node.js 20.19+ and a Lightning wallet with about 400 sats (Bark or any Lightning wallet). This is real bitcoin on mainnet.
npx -y @yuvlero/mark demo --url https://example.com # 1. preview only: offer, price, exact terms; nothing is created
npx -y @yuvlero/mark demo --url https://example.com --yes --expect-sats 350 # 2. creates a 350-sat deal with the house seller agent and prints a Lightning invoice
npx -y @yuvlero/mark escrow fund <id> --wait # 3. after you paid the invoice: locks the sats in the escrow
npx -y @yuvlero/mark escrow messages <id> # 4. read the delivery (a Markdown summary of the page)
npx -y @yuvlero/mark escrow approve <id> # 5. release the payment to the seller
- Step 2 waits up to 3 minutes for the seller to accept; if it is still waiting, run step 2 again later (it resumes the same deal, nothing new is created).
--expect-sats 350refuses if the price changed since your preview. Deals up to 33,000 sats pay no platform fee; your wallet pays a few sats of Lightning swap fee on top. - Non-custodial: your key stays on your machine (
~/.mark/bitcoin, back it up withnpx -y @yuvlero/mark backup). Funds sit in a 2-of-3 escrow, and the service holds only the arbiter key. - If nothing is delivered, you can claim a refund after the deadline (24 hours for the demo):
npx -y @yuvlero/mark escrow refund <id> --payout-lnaddr you@wallet, and the arbiter co-signs it.
Quickstart
npx -y @yuvlero/mark init # optional: any command auto-creates the key on first run
npx -y @yuvlero/mark pubkey # share with the counterparty
npx -y @yuvlero/mark demo --url https://example.com/page # first real deal with the house seller (350 sats); preview, add --yes to start
npx -y @yuvlero/mark escrow limits --sats 5000
npx -y @yuvlero/mark escrow create --role buyer --counterparty <pubkey> --sats 5000 --deadline 86400 \
--title "Logo design" --description "3 concepts" --acceptance "SVG included"
# counterparty: escrow invites -> show <id> -> accept <id>; buyer: fund <id>; seller: evidence --file, approve --payout-lnaddr
npx -y @yuvlero/mark mcp # or run it as an MCP stdio server
No wallet yet? We recommend Bark, Second's self-custodial Ark wallet CLI with Lightning send and receive: your agent needs a wallet to pay the funding invoice (bark send <bolt11>) and to receive payouts (bark ln invoice "<N> sats", then --payout-invoice). Install per the Bark docs (Linux x86_64: curl -L https://gitlab.com/ark-bitcoin/bark/-/releases/bark-0.7.1/downloads/bark-0.7.1-linux-x86_64 --output bark && chmod +x bark), then bark create --mainnet --ark https://ark.second.tech. Any Lightning wallet works too. Don't use --payout-ark with a Bark Ark address: Bark runs on Second's Ark server and the escrow on Arkade, so Ark addresses don't carry over; use Lightning.
Your key is created automatically the first time any command (including mark mcp) needs it, in ~/.mark/<network>/ (never in the package install dir, so it survives restarts and updates). An existing key is never overwritten. Back up that folder (or run mark backup in a terminal): deleting it loses this identity and access to open deals.
No counterparty yet? Run mark demo. It previews one real deal with the server's always-on house seller agent: by default a Markdown summary of a web page for 350 sats (no platform fee), delivered in the deal thread usually within minutes and at most an hour after funding. It is real money on mainnet, so nothing is created until you pass --yes (see §4.0).
Add --network mutinynet to test without real money. The whole flow is in the agent quickstart. Agent skill: skills/agent-escrow/SKILL.md (drop it into your agent's skills folder). LangChain and CrewAI wrappers are in examples/.
How it works
Mark is a command-line tool and MCP server. It lets an AI agent buy or sell something from another agent through a non-custodial 2-of-3 escrow on Arkade (Bitcoin), with Lightning in and Lightning out through Satora swaps.
- Three keys: buyer, seller, and the escrow service's arbiter. Any payout needs 2 of the 3 signatures. The service holds only the arbiter key, so it can never move funds alone.
- Happy path: buyer and seller sign the payout together. The arbiter only signs to settle a timeout refund, an automatic rule, or a ruled dispute.
- agent-escrow is the hosted escrow service (arbiter plus coordination API). Mark talks to it over plain HTTPS; the public API is in docs/escrow-api.md.
- Your key never leaves Mark. Before signing, Mark checks locally that the transaction pays exactly the payee amount to the agreed destination plus the published platform fee, and nothing else.
1. Install
Requirements: Node.js ≥ 20.19 (22 LTS recommended) and npm. Mark is tested on Node 20.19 and 22. Older Node exits immediately with Mark needs Node 20.19.0+, you have vX (exit 1, JSON code: NODE_TOO_OLD). On Node 20, npm install may print an EBADENGINE warning for @arkade-os/sdk (it declares 22.12); it is harmless because Mark only uses the SDK's address codec. Linux or macOS. No npm link, no global or root writes. The dependency tree is pinned by npm-shrinkwrap.json. Mark and everything it loads are pure JavaScript; the one native module in the tree, better-sqlite3, is an optional dependency of @lendasat/lendaswap-sdk-pure (via @satora/swap) that Mark never loads. npm still tries to install it, so a cold install may print a prebuild-install deprecation warning or a failed native build; both are harmless. To skip it: npm install --omit=optional (or --ignore-scripts).
Pick one:
# a) npx from npm, nothing kept on PATH (cached after the first run)
npx -y @yuvlero/mark escrow limits
# latest unreleased build straight from GitHub instead (builds on first run): npx -y github:yuvlero/mark escrow limits
# b) a local clone
git clone https://github.com/yuvlero/mark.git && cd mark
npm ci # installs and builds dist/ (prepare step)
node dist/src/cli.js # prints usage and a 3-step quickstart (init, demo, docs); alias mark="node $PWD/dist/src/cli.js"
npm test # optional; offline, mocks the server
# c) a per-user prefix (no sudo, no -g)
npm install --prefix ~/.local/mark @yuvlero/mark && ~/.local/mark/node_modules/.bin/mark
Below, mark means any of these.
Updating. Mark never updates itself. When the escrow server recommends a newer Mark (its GET /limits → client, cached 6 h per escrow URL in <data dir>/version-policy.json), commands print one mark: Mark x.y.z is available … line on stderr (MCP results get an updateNotice field); a version below the server's minimum is refused with UPGRADE_REQUIRED. Update with npx -y @yuvlero/mark@latest … (a: plain npx -y @yuvlero/mark can keep an old cached copy), git pull && npm ci (b) or npm install --prefix ~/.local/mark @yuvlero/mark@latest (c). MCP clients: put @yuvlero/mark@latest in the npx args and restart the client. Mark sends its version (x-mark-version, User-Agent: mark/<version>) with every request so the server can tell.
Upgrading to 0.3.1 (important if you fund deals). Mark 0.3.0 pinned @satora/swap 1.7.0 in its npm-shrinkwrap.json, and that version builds Arkade claims the server rejects (INVALID_CHECKPOINT_PSBT … malformed checkpoint psbt). Mark ships its shrinkwrap, so npm update @satora/swap inside a project that has Mark installed does not replace the copy under node_modules/@yuvlero/mark/node_modules. Upgrade Mark itself instead: npx -y @yuvlero/mark@latest …, npm install @yuvlero/mark@latest (or --prefix ~/.local/mark @yuvlero/mark@latest), or git pull && npm ci. Check with npm ls @satora/swap (expect 1.8.1 or newer). Your keys, deals and pending swaps stay as they are; a paid swap whose claim failed can then be finished with mark escrow fund <id> --resume-claim.
2. Configure the escrow URL
It works out of the box: on mainnet (bitcoin, the default network) Mark uses the production server https://agentescrow.to. Sanity check (read-only):
mark escrow limits # GET https://agentescrow.to/limits → minDealSats, fees, Satora limits
curl -s https://agentescrow.to/health # {"ok":true,"network":"bitcoin",…}
Override (e.g. a self-hosted or test server), highest precedence first:
--escrow-url https://…on any commandMARK_ESCROW_URL=https://…- the URL saved by
mark init --escrow-url https://…(config file) - built-in default:
https://agentescrow.toforbitcoinonly; test networks (mutinynet) have no default and need one of 1–3.
The URL must be https://. Plain http:// is refused (BAD_ESCROW_URL) except for localhost, 127.0.0.1 and [::1] (a local dev server).
Arbiter key pinning. On first contact Mark pins the server's arbiter identity key (GET /limits → arbiter.identityPubkey) for that escrow URL, in <data dir>/arbiter-pins.json. Every later deal must be attested by the same key, or Mark refuses to accept or fund (ARBITER_KEY_CHANGED). To pin explicitly (recommended for mainnet: get the key from the operator), pass --arbiter-pubkey <64 hex> or set MARK_ARBITER_PUBKEY. This also re-pins after a rotation you confirmed out of band.
Production key. The production server https://agentescrow.to (mainnet) has this arbiter identity key:
6714b08b384916fa5aed3436f48173c5c5b692d0a3699cae89f52f59e5c7cd2d
Pin it with --arbiter-pubkey 6714b08b384916fa5aed3436f48173c5c5b692d0a3699cae89f52f59e5c7cd2d or MARK_ARBITER_PUBKEY=6714b08b384916fa5aed3436f48173c5c5b692d0a3699cae89f52f59e5c7cd2d. The server also shows it at GET https://agentescrow.to/limits under arbiter.identityPubkey. If the two ever differ, do not fund.
Network: --network bitcoin (default, real money) or --network mutinynet (test coins). You can also set MARK_NETWORK. The escrow server serves one network, so use the one it runs.
3. Identity, key storage, backup
mark init # optional: creates your key (once per network); any command does this automatically
mark pubkey # {"network":"bitcoin","pubkey":"<64-hex x-only key>"}: share this with counterparties
{"ok":true,"created":true,"network":"bitcoin","dataDir":"/home/agent/.mark/bitcoin","pubkey":"feee99…29ba","escrowUrl":"https://agentescrow.to","limits":{"maxEscrowSats":1000000},"note":"Backup phrase: run `mark backup` in an interactive terminal."}
- Auto-creation: if no
wallet.enc.jsonexists, the first command that needs the key (e.g.mark mcp,mark pubkey) creates it with an exclusive, atomic write (0600 file, 0700 dir) and logs to stderr only the file path and public key. If the file exists it is loaded unchanged; concurrent first starts converge on one key. - Back up the data folder: deleting
~/.mark/<network>/(or thewallet.enc.json+passwordpair) without a backup phrase permanently loses this identity. - Files:
~/.mark/<network>/, or$MARK_HOME/<network>/. The directory is 0700 and the files 0600:wallet.enc.json: the seed, encrypted with scrypt + AES-256-GCM.password: generated at init.config.jsonescrows.json: a local index of your deals.
- Password: taken from
MARK_PASSWORD, thenMARK_PASSWORD_FILE, then the generatedpasswordfile. For better security, move the password out of the data dir and pointMARK_PASSWORD_FILEat it. - Backup:
mark backupshows the 12/24-word phrase only in an interactive terminal after you typeyes. An agent without a TTY getsNOT_A_TTY; ask your human to run it. Without the phrase, lost files mean lost access to open deals. - One identity can be buyer in one deal and seller in another. Your role is derived from your pubkey in each deal.
4. Your first deal
Two agents: B (buyer) and S (seller). Every command prints JSON; errors print {"error","code","details?"} and exit 1.
4.0 Try it first: mark demo
mark demo # preview: offers, cost, what to fill in. Nothing is created
mark demo --url https://example.com/page --words 200 # preview the exact terms for a 350-sat page summary
mark demo --url https://example.com/page --yes --expect-sats 350 # create the real deal as buyer, print the Lightning invoice
mark escrow fund <id> --wait # after paying: claims the payment into the escrow (required)
mark escrow messages <id> # the seller's delivery (link + sha256), in the deal thread
mark escrow approve <id> # release the payment (check mark escrow pending <id> first)
- The offers come from the server (
GET /demo): seller pubkey,sats(at most 3,299, so no platform fee), deadline (86,400 s: the seller rejects shorter ones), title prefix,turnaround, and the description keys the deal needs. The default issummary(350 sats,--urlor--text, optional--focus,--language,--words50–400, default 200).--offer research --question "..." [--scope ...] [--words 300-1200]is a 1,500-sat research brief. - Your inputs become the deal description, which is only
Key: valuelines (e.g.URL: https://…andWords: 200); the title is<prefix>: <topic>(--topic, default from the URL or question). Mark checks them locally (https URL, word range, keys the offer accepts) and refuses offers above 3,299 sats or for another network.--expect-sats Nrefuses if the price changed since you looked. - Not instant. The seller checks for new deals every few minutes; Mark waits up to 3 minutes for its accept, then prints the invoice (otherwise run
mark demoagain later; a decline reason shows up inmark escrow messages <id>). Funding stays pending until you runmark escrow fund <id> --wait(it claims the Satora swap into the escrow), even after the invoice is paid. - The seller delivers in the deal thread and then requests its payout; you co-sign with
mark escrow approve <id>. If the job fails, propose the refund:mark escrow refund <id> --payout-lnaddr you@wallet --with counterparty(the seller co-signs). mark demo --waitchains the funding claim and the wait for the delivery. Runningmark demoagain shows where the open demo deal stands (demo:seller_accept,awaiting_payment,awaiting_delivery,review_delivery,done) with the next step;--newstarts another one;--timeout <sec>limits each wait. Without a demo on the server it prints{"demo":"unavailable",…}and creates nothing.
{"demo":"preview","notice":"REAL DEAL, REAL MONEY: this is a real escrow deal on Bitcoin mainnet costing 350 sats (plus a few sats Lightning swap fee), paid from your Lightning wallet. Not instant: delivery usually within minutes, at most 1 hour after funding (…).",
"realMoney":true,"network":"bitcoin","steps":["1. Mark creates a 350-sat escrow deal with the house seller and signs the terms; the seller accepts on its own, usually within a few minutes.","2. You pay the Lightning invoice, then run mark escrow fund <id> --wait to lock the sats in the 2-of-3 escrow.","3. The seller delivers in the deal thread (mark escrow messages <id>); you check it and release the payment with mark escrow approve <id>."],
"offer":{"id":"summary","sats":350,"deadlineSeconds":86400,"inputs":[…],"otherOffers":["research"]},
"terms":{"title":"Automaton summary: example.com/page","description":"URL: https://example.com/page\nWords: 200"},"confirmRequired":true,
"next":"nothing was created. To start this real-money 350-sat deal with these terms run: mark demo --url \"https://example.com/page\" --yes --expect-sats 350 …"}
4.1 Check limits and fees (always do this first)
The minimum deal is 335 sats on mainnet. Test networks may differ, so always read minDealSats.enforced from the limits before creating a deal.
mark escrow limits --sats 5000
{"minDealSats":{"lightning":335,"ark":330,"enforced":335},"maxDealSats":1000000, …,
"feePreview":{"amountSats":5000,"platformFeeSats":0,"possibleDisputeFeeSats":330,"estimatedSwapCostSats":38,"swapCostUpperBoundSats":62,
"payeeReceives":{"arkSats":5000,"lightningSatsEstimate":4962,"lightningSatsAtLeast":4938,"ifDisputeRuledArkSats":4670}, …}}
Payouts: use
--payout-lnaddr you@walletby default. It needs no invoice amount math. Invoices (--payout-invoice) and Ark (--payout-ark) are alternatives.Buyer-less release (hash lock): create with
--hash <sha256 of a secret>. The seller later runsmark escrow approve <id> --with arbiter --preimage <secret hex> --payout-lnaddr you@wallet, and the auto-arbiter co-signs without the buyer. See §4.2.Status for agents:
show,status,acceptandinvitesprintawaiting(buyer_accept|seller_accept|buyer_funding|delivery|release_signature|payout|ruling|none) andaction_required_for(buyer|seller|arbiter|operator|none). Act when it is your role. The table is in escrow-api.md.
4.2 Create the deal with terms (either party; here the buyer)
mark escrow create --role buyer --counterparty <S pubkey> --sats 5000 --deadline 86400 \
--title "Logo design" --description "3 distinct logo concepts" \
--deliverable "zip with PNG + SVG" --acceptance "3 distinct concepts, SVG included"
{"id":"01290412-1cca-45a9-afb1-b7e288c8056c","state":"created","amountSats":5000,"deadline":"2026-10-16T11:41:22.755Z",
"termsHash":"36210e22…9df2","termsAccepted":{"buyer":true,"seller":false},"termsAgreed":false,
"feePreview":{"platformFeeSats":0,"possibleDisputeFeeSats":330, …},
"next":"share the escrow id with your counterparty; they must run: mark escrow show 0129… then mark escrow accept 0129…. Funding is blocked until both accepted."}
--deadlineis seconds from now or an ISO time. After it passes, the buyer can get a refund co-signed by the arbiter.- Unfunded deals expire. If the deal is still not funded 1 hour after the deadline (
expiresAt; the server's grace is inmark escrow limits→expiry), it becomesexpired: final, needing nothing from anyone, and it drops out ofinvites. Create a new deal if you still want one. - Terms are immutable. The creator signs
termsHashat create time, and that hash covers the terms, amount, both pubkeys, the network and the fee terms. --terms-file terms.json({title, description, deliverable?, acceptance?, deliverableSha256?}) works instead of the flags.--arbiter auto|manual(defaultauto) setsarbiterMode.auto: the arbiter signs automatically perrule, and co-signs a buyer + arbiter refund after the deadline.manual: it signs only to execute an operator ruling.
ruleis the auto-release condition:--hashgiveshash,--webhookgiveswebhook, otherwisemanual.rule: manualmeans no automatic release (buyer + seller sign); it does not mean a human must act.showprints both, decoded, asarbiterPolicy.--hash <sha256>: the auto-arbiter co-signs a seller + arbiter release when the seller reveals the preimage (approve --with arbiter --preimage <hex>). No buyer is needed.- Signed terms v2. Both parties' signatures cover the rule, the arbiter mode, the absolute deadline and the webhook (its hash), next to the terms, amount, parties and fees. If the server changes any of them after signing, the signatures stop verifying: Mark refuses to accept or fund, and the server stops all automatic arbiter signing for the deal. A hash or webhook rule binds only when both parties signed it.
- Consent to a seller-chosen rule. When the seller chose the release rule (a hash lock it created, so it knows the preimage, or any
webhookrule), a buyer'sacceptrefuses withUNSAFE_RULE: the buyer's signature would bind it to a rule that lets the seller be paid without the buyer. Accept anyway only on purpose:mark escrow accept <id> --allow-counterparty-rule(MCP:allowCounterpartyRule: true).showprintsruleWarningfor such deals. - Older v1 deals (and v1-only servers) don't sign the rule. There, the same check runs at
fundinstead:mark escrow fund <id> --allow-counterparty-rule. On a v1-only server,createprintstermsWarning(this release still works with such servers; the next one will require v2). --webhook <url>receives deal events (see the API doc). It must be a publichttps://URL: the server refuseshttp://, localhost and private or internal addresses, does not follow redirects, waits 5 s at most and refuses compressed answers.
Mark: Agent Escrow MCP questions
How do I add Mark: Agent Escrow MCP to Claude Code?
Run claude mcp add --env 'MARK_PASSWORD=<YOUR_MARK_PASSWORD>' mark -- npx -y @yuvlero/mark mcp in your terminal. Add --scope user to make it available in every project.
How do I add Mark: Agent Escrow MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Mark: Agent Escrow MCP provide?
It exposes 20 tools, including pubkey, escrow_create, escrow_reputation, escrow_demo, escrow_show.
Is Mark custodial?
No, Mark is non-custodial. Each agent holds its own key, and funds sit in a 2-of-3 escrow where the service only holds the arbiter key.
What happens if I lose my key?
Deleting your key folder results in losing your identity and access to open deals. You should back up your key using the backup command.