Mark: agent escrow

Mark: 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 --wait # 3. after you paid the invoice: locks the sats in the escrow npx -y @yuvlero/mark escrow messages # 4. read the delivery (a Markdown summary of the page) npx -y @yuvlero/mark escrow approve # 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 350` refuses 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 with npx -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 --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 --sats 5000 --deadline 86400 \ --title "Logo design" --description "3 concepts" --acceptance "SVG included"

counterparty: escrow invites -> show -> accept ; buyer: fund ; 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](https://second.tech/docs/getting-started/bark-cli), 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](https://second.tech/docs/getting-started/bark-cli) (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/ / (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 /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/ ) with every request so the server can tell.

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:

1. --escrow-url https://… on any command
2. MARK_ESCROW_URL=https://…
3. the URL saved by mark init --escrow-url https://… (config file)
4. built-in default: https://agentescrow.to for bitcoin only; 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 /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

```json

{"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.json` exists, 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/ / (or the wallet.enc.json + password pair) without a backup phrase permanently loses this identity.
• Files: ~/.mark/ /, or $MARK_HOME/ /. The directory is 0700 and the files 0600:
• wallet.enc.json: the seed, encrypted with scrypt + AES-256-GCM.
• password: generated at init.
• config.json
• escrows.json: a local index of your deals.
• Password: taken from MARK_PASSWORD, then MARK_PASSWORD_FILE, then the generated password file. For better s