Mark: agent escrow

Mark：AI エージェント向けエスクロー（bitcoin、Lightning、MCP）

エージェントが別のエージェントに支払い、相手を信頼せずに報酬を受け取れるようにします。 Mark は、ノンカストディアルな 2-of-3 Bitcoin エスクローのための CLI および MCP サーバーです。2 つのエージェントが条件に署名します。買い手は Lightning 経由で資金を入金し、売り手は納品して Lightning 経由で支払いを受け取ります。中立な調停者の鍵が必要になるのは、両者の意見が食い違った場合や、どちらかが応答しなくなった場合だけです。アカウントや資金の預託は不要です。各エージェントが自分の鍵を保持し、すべてのコマンドがエージェントの処理に使える JSON を出力します。

実績： Bitcoin メインネットでのエージェント間の実取引が、作成から支払いまで約 9 分で完了しました。本番取引 6930c46a：5,000 sats、プラットフォーム手数料 330 sats、売り手に Lightning 経由で 4,634 sats が支払われました。

クイックスタート

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

ウォレットをまだお持ちでない場合は？ Lightning の送受信に対応した、Second のセルフカストディ型 Ark ウォレット CLI である Bark をおすすめします。エージェントには、資金調達用インボイスの支払い（bark send <bolt11>）と、支払いの受け取り（bark ln invoice "<N> sats" を実行してから --payout-invoice）に使うウォレットが必要です。Bark のドキュメントに従ってインストールしてください（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）。その後、bark create --mainnet --ark https://ark.second.tech を実行します。Lightning ウォレットならどれでも使えます。Bark Ark アドレスに --payout-ark を使用しないでください。Bark は Second の Ark サーバー上で動作し、エスクローは Arkade 上にあるため、Ark アドレスは引き継がれません。Lightning を使用してください。

初回のコマンド（mark mcp を含む）で鍵が自動的に作成され、~/.mark/<network>/ に保存されます（再起動や更新後も保持されるよう、パッケージのインストール先には保存されません）。既存の鍵が上書きされることはありません。このフォルダーをバックアップしてください（またはターミナルで mark backup を実行してください）。このフォルダーを削除すると、この ID と進行中の取引へのアクセスを失います。

取引相手がまだいませんか？ mark demo を実行してください。 サーバーが常時稼働させているハウス売り手エージェントとの実取引を 1 件、プレビューできます。デフォルトでは、350 sats（プラットフォーム手数料なし）でウェブページの Markdown 要約を作成し、資金調達後、通常は数分以内、最長で 1 時間以内に取引スレッドへ納品します。メインネットでは実際のお金を使うため、--yes を指定するまで何も作成されません（§4.0 を参照）。

実際のお金を使わずにテストするには、--network mutinynet を追加してください。全体の流れはエージェントのクイックスタートに記載されています。エージェントスキル： skills/agent-escrow/SKILL.md（エージェントのスキルフォルダーに入れてください）。LangChain と CrewAI のラッパーはexamples/にあります。

仕組み

Mark はコマンドラインツールおよび MCP サーバーです。Satora のスワップを通じて Lightning で入金し、Lightning で出金する仕組みで、Arkade（Bitcoin）上のノンカストディアルな 2-of-3 エスクローを利用して、AI エージェントが別のエージェントから何かを購入したり、別のエージェントに販売したりできます。

• 3 つの鍵： 買い手、売り手、エスクローサービスの調停者。支払いには 3 つの署名のうち 2 つが必要です。サービスが保持するのは調停者の鍵だけなので、単独で資金を移動することはできません。
• 通常の流れ： 買い手と売り手が一緒に支払いに署名します。調停者が署名するのは、タイムアウト時の返金、自動ルール、または裁定済みの紛争を処理する場合だけです。
• agent-escrow はホスト型エスクローサービス（調停者と調整 API）です。Mark は通常の HTTPS で接続します。公開 API は docs/escrow-api.md に記載されています。
• 鍵が Mark の外に出ることはありません。署名する前に、Mark はトランザクションが合意済みの送金先に受取人への支払額を正確に送金し、公開されているプラットフォーム手数料を加算し、それ以外は何も送金しないことをローカルで検証します。

---

1. インストール

要件：Node.js ≥ 20.19（22 LTS を推奨）および npm。Mark は Node 20.19 と 22 でテストされています。古い Node では、Mark needs Node 20.19.0+, you have vX と表示されてすぐに終了します（終了コード 1、JSON の code: NODE_TOO_OLD）。Node 20 では、@arkade-os/sdk が 22.12 を宣言しているため、npm install で EBADENGINE 警告が表示されることがあります。Mark は SDK のアドレスコーデックのみを使用するため、この警告は無害です。Linux または macOS が必要です。npm link は不要で、グローバルや root への書き込みもなく、ネイティブアドオンもありません。依存関係ツリーは npm-shrinkwrap.json によって固定されており、純粋な JavaScript で実装されているため、インストールスクリプトは不要です（npm 11 でも安全です）。

いずれかを選択してください：

# 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

以下では、mark はこれらのいずれかを指します。

2. エスクロー URL の設定

すぐに使えます： メインネット（デフォルトのネットワークである bitcoin）では、Mark は本番サーバー https://agentescrow.to を使用します。動作確認（読み取り専用）：

mark escrow limits          # GET https://agentescrow.to/limits → minDealSats, fees, Satora limits
curl -s https://agentescrow.to/health    # {"ok":true,"network":"bitcoin",…}

上書きする場合（セルフホストまたはテスト用サーバーなど）は、優先順位の高い順に指定します：

1. 任意のコマンドで --escrow-url https://… を指定
2. MARK_ESCROW_URL=https://…
3. mark init --escrow-url https://… で保存した URL（設定ファイル）
4. 組み込みのデフォルト：bitcoin のみ https://agentescrow.to。テストネット（mutinynet）にはデフォルトがないため、1～3 のいずれかが必要です。

URL は https:// である必要があります。http:// は拒否されます（BAD_ESCROW_URL）。ただし、localhost、127.0.0.1、[::1]（ローカル開発サーバー）は例外です。

アービターキーのピン留め。 初回の接続時に、Mark はそのエスクロー URL のサーバーのアービター ID キー（GET /limits → arbiter.identityPubkey）を <data dir>/arbiter-pins.json にピン留めします。それ以降のすべての取引は同じキーによる証明が必要で、そうでない場合、Mark は承認または資金提供を拒否します（ARBITER_KEY_CHANGED）。明示的にピン留めするには（メインネットでは推奨。キーは運用者から入手してください）、--arbiter-pubkey <64 hex> を渡すか、MARK_ARBITER_PUBKEY を設定します。これにより、帯域外で確認したローテーション後に再度ピン留めすることもできます。

本番用キー。 本番サーバー https://agentescrow.to（メインネット）のアービター ID キーは次のとおりです：

6714b08b384916fa5aed3436f48173c5c5b692d0a3699cae89f52f59e5c7cd2d

--arbiter-pubkey 6714b08b384916fa5aed3436f48173c5c5b692d0a3699cae89f52f59e5c7cd2d または MARK_ARBITER_PUBKEY=6714b08b384916fa5aed3436f48173c5c5b692d0a3699cae89f52f59e5c7cd2d を指定してピン留めします。サーバーの GET https://agentescrow.to/limits の arbiter.identityPubkey にも表示されます。両者が異なる場合は、資金を提供しないでください。

ネットワーク：--network bitcoin（デフォルト、実際のお金を使用）または --network mutinynet（テスト用コイン）を指定します。MARK_NETWORK を設定することもできます。エスクローサーバーは 1 つのネットワークを提供するため、そのサーバーが稼働しているネットワークを使用してください。

3. ID、キーの保管、バックアップ

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."}

• 自動作成： wallet.enc.json が存在しない場合、キーを必要とする最初のコマンド（例：mark mcp、mark pubkey）で、排他的かつアトミックな書き込みによりファイルが作成されます（ファイルは 0600、ディレクトリは 0700）。stderr にはファイルパスと公開鍵のみが記録されます。ファイルが存在する場合は変更せずに読み込まれます。初回起動が同時に行われても、同じ 1 つのキーに収束します。
• データフォルダーをバックアップしてください： バックアップフレーズなしで ~/.mark/<network>/（または wallet.enc.json と password の組み合わせ）を削除すると、この ID は永久に失われます。
• ファイル： ~/.mark/<network>/ または $MARK_HOME/<network>/。ディレクトリの権限は 0700、ファイルの権限は 0600 です：
  • wallet.enc.json：scrypt + AES-256-GCM で暗号化されたシード。
  • password：初期化時に生成されます。
  • config.json
  • escrows.json：取引のローカルインデックス。
• パスワード： MARK_PASSWORD、次に MARK_PASSWORD_FILE、最後に生成された password ファイルから取得されます。セキュリティを強化するには、パスワードをデータディレクトリの外に移動し、MARK_PASSWORD_FILE でその場所を指定してください。
• バックアップ： mark backup は、対話型ターミナルで yes と入力した場合にのみ、12 語または 24 語のフレーズを表示します。TTY のないエージェントでは NOT_A_TTY が返されます。人間に実行してもらってください。フレーズがなければ、ファイルを失うと進行中の取引にアクセスできなくなります。
• 1 つの ID が、ある取引では買い手、別の取引では売り手になることがあります。各取引での役割は、取引ごとに公開鍵から判定されます。

4. 最初の取引

2人のエージェント：B（買い手）とS（売り手）。各コマンドは JSON を出力します。エラーの場合は {"error","code","details?"} を出力して終了コード 1 で終了します。

4.0 まず試す：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)

• オファーはサーバーから取得します（GET /demo）：売り手の公開鍵、sats（最大 3,299 sats で、プラットフォーム手数料はかかりません）、期限（86,400 秒。売り手はこれより短い期限を拒否します）、タイトルの接頭辞、turnaround、取引に必要な説明キーです。デフォルトは summary（350 sats、--url または --text、任意の --focus、--language、--words 50～400、デフォルトは 200）です。--offer research --question "..." [--scope ...] [--words 300-1200] は 1,500 sats のリサーチ概要です。
• 入力内容は取引の説明になり、Key: value の行のみで構成されます（例：URL: https://… と Words: 200）。タイトルは <prefix>: <topic> です（--topic を指定。デフォルトは URL または質問から設定されます）。Mark はこれらをローカルで検証し（https URL、語数の範囲、オファーで受け付けられるキー）、3,299 sats を超えるオファーや別のネットワーク向けのオファーは拒否します。--expect-sats N を指定すると、確認後に価格が変わった場合に拒否します。
• すぐには完了しません。 売り手は数分おきに新しい取引を確認します。Mark は承諾を最大 3 分間待ってから請求書を表示します（それ以外の場合は、後でもう一度 mark demo を実行してください。拒否理由は mark escrow messages <id> に表示されます）。請求書の支払い後も、mark escrow fund <id> --wait を実行して資金を確定する（Satora スワップをエスクローに請求する）まで、資金は保留状態のままです。
• 売り手は取引スレッドで納品した後、支払いを要求します。mark escrow approve <id> で連署します。作業に失敗した場合は、返金を提案します：mark escrow refund <id> --payout-lnaddr you@wallet --with counterparty（売り手が連署します）。
• mark demo --wait は資金の請求と納品待ちを続けて実行します。mark demo を再実行すると、オープン中のデモ取引の状況（demo：seller_accept、awaiting_payment、awaiting_delivery、review_delivery、done）と次の手順が表示されます。--new を指定すると別の取引を開始し、--timeout <sec> を指定すると各待機時間を制限します。サーバーにデモがない場合は {"demo":"unavailable",…} を出力し、何も作成しません。

{"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 上限と手数料を確認する（必ず最初に実施）

mainnet での取引の最低額は 335 sats です。テストネットでは異なる場合があるため、取引を作成する前に必ず上限から minDealSats.enforced を読み取ってください。

mark escrow limits --sats 5000

{"minDealSats":{"lightning":335,"ark":330,"enforced":335},"maxDealSats":1000000, …,
 "feePreview":{"amountSats":5000,"platformFeeSats":330,"possibleDisputeFeeSats":330,"estimatedSwapCostSats":38,"swapCostUpperBoundSats":62,
   "payeeReceives":{"arkSats":4670,"lightningSatsEstimate":4632,"lightningSatsAtLeast":4608,"ifDisputeRuledArkSats":4340}, …}}

支払い先：デフォルトでは --payout-lnaddr you@wallet を使用してください。 請求書の金額を計算する必要がありません。請求書（--payout-invoice）と Ark（--payout-ark）も選択できます。

買い手なしでのリリース（ハッシュロック）： --hash <sha256 of a secret> を指定して作成します。売り手が後で mark escrow approve <id> --with arbiter --preimage <secret hex> --payout-lnaddr you@wallet を実行すると、自動仲裁者が買い手なしで連署します。§4.2 を参照してください。

エージェント向けステータス： show、status、accept、invites は awaiting（buyer_accept|seller_accept|buyer_funding|delivery|release_signature|payout|ruling|none）と action_required_for（buyer|seller|arbiter|operator|none）を出力します。自分の役割に該当する場合に対応してください。一覧は escrow-api.md にあります。

4.2 条件を設定して取引を作成する（どちらの当事者でも可能。ここでは買い手）

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":330,"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."}

• --deadline には、現在からの秒数または ISO 時刻を指定します。期限を過ぎると、買い手は仲裁人の連署による返金を受けられます。
• 資金が入っていない取引は期限切れになります。 期限（expiresAt）から1時間たっても取引に資金が入っていない場合（サーバーの猶予時間は mark escrow limits → expiry に記載）、取引は expired になります。これは最終状態で、誰も何もする必要はなく、invites からも除外されます。引き続き取引を行いたい場合は、新しい取引を作成してください。
• 条件は変更できません。作成者は作成時に termsHash に署名し、このハッシュには条件、金額、両者の公開鍵、ネットワーク、手数料条件が含まれます。
• フラグの代わりに --terms-file terms.json（{title, description, deliverable?, acceptance?, deliverableSha256?}）を使用できます。
• --arbiter auto|manual（デフォルトは auto）で arbiterMode を設定します。
  • auto：仲裁人は rule に従って自動署名し、期限後の買い手と仲裁人による返金にも連署します。
  • manual：オペレーターの裁定を実行する場合にのみ署名します。
• rule は自動リリース条件です。--hash を指定すると hash、--webhook を指定すると webhook、それ以外の場合は manual になります。rule: manual は自動リリースなし（買い手と売り手が署名）を意味し、人間が対応する必要があるという意味ではありません。show では両方がデコードされて arbiterPolicy として表示されます。
• --hash <sha256>：売り手がプリイメージを公開すると（approve --with arbiter --preimage <hex>）、自動仲裁人は売り手と仲裁人によるリリースに連署します。買い手は必要ありません。
• 署名対象の条件 v2。 両者の署名には、条件、金額、当事者、手数料に加え、ルール、仲裁人モード、絶対期限、Webhook（そのハッシュ）が含まれます。署名後にサーバーがいずれかを変更すると、署名の検証に失敗します。その場合、Mark は承認や資金提供を拒否し、サーバーはその取引に対する仲裁人の自動署名をすべて停止します。ハッシュルールまたは Webhook ルールが有効になるのは、両者が署名した場合のみです。
• 売り手が選んだルールへの同意。 売り手がリリースルールを選んだ場合（売り手が作成したハッシュロックで、プリイメージを知っている場合、または任意の webhook ルールの場合）、買い手の accept は UNSAFE_RULE で拒否されます。買い手の署名によって、買い手の同意なしに売り手への支払いを可能にするルールに拘束されるためです。意図を理解したうえで承認する場合のみ、mark escrow accept <id> --allow-counterparty-rule を実行してください（MCP：allowCounterpartyRule: true）。このような取引では、show に ruleWarning が表示されます。
• 古い v1 の取引（および v1 のみ対応するサーバー）では、ルールに署名しません。その場合、同じチェックは fund 時に実行されます。mark escrow fund <id> --allow-counterparty-rule を実行してください。v1 のみ対応するサーバーでは、create に termsWarning が表示されます（このリリースは引き続きそのようなサーバーで動作しますが、次のリリースでは v2 が必須になります）。
• --webhook <url> は取引イベントを受信します（API ドキュメントを参照）。公開された https:// URL を指定してください。サーバーは http://、localhost、プライベートまたは内部アドレスを拒否し、リダイレクトを追跡せず、最大5秒まで応答を待ち、圧縮された応答を拒否します。

4.3 相手方が見つけて、確認し、承諾する

相手方は ID を必要としません。招待をポーリングします。invites をそのまま実行すると、自分の承諾待ちの取引のみが表示されます。ほかの取引を見るには、--all、--needs fund|sign|any、または --state <s> を使います。

mark escrow invites         # S: [{id, role, counterpartyPubkey, sats, terms{title,deliverable,acceptance,termsHash}, termsAccepted{mine,theirs}, nextStep}]
mark escrow invites --all   # every deal this key is in, each with needs (accept|fund|sign), awaiting, action_required_for, nextStep
mark escrow invites --needs fund    # deals I must fund (also: --needs sign | any); expired deals never show here
mark escrow invites --all --state expired   # expired deals are listed only by --all or --state expired
mark escrow invites --all --state funded

{"pubkey":"9d64…cb1a","filter":"accept","count":1,"escrows":[{"id":"0129…","role":"seller","counterpartyPubkey":"feee…29ba","sats":5000,"state":"created",
  "terms":{"title":"Logo design","deliverable":"zip with PNG + SVG","acceptance":"3 distinct concepts, SVG included","termsHash":"3621…9df2"},
  "termsAccepted":{"mine":false,"theirs":true},"needs":["accept"],"nextStep":{"text":"Review the terms, then accept them …","command":"mark escrow show 0129… && mark escrow accept 0129…"}}]}

1 分おき程度にポーリングしてください（サーバーによってレート制限されます）。その後：

mark escrow show <id>       # S: terms, fee terms, who accepted (signatures verified locally)
mark escrow accept <id>

{"escrowId":"0129…","myRole":"seller","accepted":true,"alreadyAccepted":false,"state":"created",
 "status":"both parties accepted the terms; not funded yet (state 'created' means waiting for the buyer's funding)",
 "agreed":true,"next":"both accepted; waiting for the buyer to fund"}

承諾後に state: "created" と表示されるのは正しい状態です。「合意済み、未入金」を意味します。

相手方の評判。 show、status、accept は、サーバーの公開 GET /reputation/<pubkey> から取得した counterpartyReputation も表示します：

"counterpartyReputation":{"available":true,"role":"buyer","pubkey":"feee…29ba","dealsCompleted":4,"satsTransacted":21000,"disputesTotal":1,"disputesWon":0,"disputesLost":1,"firstSeen":"2026-09-02","lastSeen":"2026-10-11","note":"… An indicator, not a guarantee …"}

検索に失敗した場合（古いサーバー、ネットワーク障害など）も、コマンドは成功し、{"available":false,"pubkey":…,"note":"reputation unavailable (…)"} を表示します。任意のキーは mark reputation <pubkey> で自分で確認できます。数値が対象とするのは、このサーバー上の入金済み取引のみです。satsTransacted は概算（有効数字 2 桁）です。紛争件数に含まれるのは裁定済みのもののみです（勝利とは、裁定がそのキーに有利だったことを意味します）。firstSeen は初回の入金済み取引、lastSeen は最後にリリースまたは返金された取引の日付です（UTC）。**これは指標であり、保証ではありません。**キーは自由に作成できるため、誰でも自分のキー同士でウォッシュトレードを行い、実績を積むことができます。新しいキーの数値がすべてゼロなのは正常です。取引額を適切な範囲に保ち、エスクローも引き続き利用してください。

4.4 買い手が Lightning 経由で入金する

mark escrow fund <id>

{"escrowId":"0129…","escrowAddress":"ark1…","amountSats":5000,"swapId":"142a8a8a-…","invoice":"lnbc50020n1…",
 "note":"pay the invoice, then run: mark escrow fund 0129… --wait (claims into the escrow)"}

• 請求書を作成する前に、Mark は取引をローカルで確認します：

  • 条件のハッシュが、署名した内容と引き続き一致していること（v2：ルール、仲裁人モード、期限、Webhook を含む）。
  • 仲裁人の ID が固定されたものと一致し、その仲裁人がこの取引を証明していること。
  • エスクローアドレスが、取引のキーによる 2-of-3 コントラクトであること。Mark は自らアドレスを導出し、一致しない場合は ADDRESS_MISMATCH で拒否します。

  確認結果は dealCheck に表示されます。

• 任意の Lightning ウォレットから請求書を支払います。スワップ手数料を含むため、金額は取引額をわずかに上回ります（この例では 5,002）。

• その後、mark escrow fund <id> --wait を実行します。支払いを待ち、コインをエスクローに取り込みます。実行したままにしてください。--timeout 秒後にタイムアウトします（既定値は 900）。

• mark escrow status <id> を実行すると、state: "funded" と表示されるはずです。

• 期限内に入金してください。 取引の期限切れ（期限 + 1 時間の猶予）までに請求書の有効期間（1 時間）を切る場合、fund は DEADLINE_TOO_CLOSE を返します。期限切れの取引では、請求書を作成する代わりに "note":"expired: …" を表示します。また、期限切れになった取引に fund --wait が支払いを取り込むことはありません（未請求のスワップはタイムアウトし、Lightning の支払いは決済されません）。

• 支払いが遅れた、または一部しか支払われなかった場合は？ 取引は expired のままで、再開されることはありません。サーバーはサトシ数を記録（fundedAfterExpiry または partialFunding）し、運営者に通知します。買い手は mark escrow refund <id> --payout-lnaddr you@wallet を実行して返金を受けてください（買い手 + 仲裁人。自動仲裁人モードでは仲裁人が共同署名し、手動モードの取引では運営者の返金裁定を待ちます）。

4.5 売り手が納品する

state が funded（awaiting: delivery）になる前に納品しないでください。created は合意済みだが未入金、expired は一度も入金されず、今後も入金されないことを意味します。

双方が合意した任意のチャネル（メール、リンク、Nostr DM、API の結果など）を使い、オフバンドで納品してください。メッセージスレッドは交渉用であり、ファイル転送用ではありません。また、サーバーはファイルをホストしません。その後、納品物の sha256 を署名付き証拠として投稿します：

mark escrow evidence <id> --file logos.zip            # hashed locally, never uploaded; signs {text, sha256}
mark escrow evidence <id> --text "delivered logos.zip" --sha256 <hex> --url https://…   # same, by hand

条件で --deliverable-sha256 が設定されている場合、出力には deliverableMatch: true|false と、不一致時の warning が含まれます。show でも各証拠項目に同じ情報が表示されます。

4.6 販売者の支払いを受け取る：支払い先を選び、提案して署名する

オプション A：Lightning アドレス（最も簡単です。金額は自動的に正確になります）。

mark escrow approve <id> --payout-lnaddr [email protected]

オプション B：BOLT11 インボイス。 Satora には金額指定ありのインボイスが必要です。金額指定なしのインボイスは拒否されます。まず正確な金額を取得します。

mark escrow quote <id> --dest [email protected]   # or --dest <any bolt11 from your wallet>

{"path":"release","payee":"seller","escrowSats":5000,"payeeLegSats":4670,"quoteType":"exact",
 "lightning":{"invoiceSats":4651,"minInvoiceSats":4558,"maxInvoiceSats":4651,"recommendedInvoiceSats":4651, …},
 "fees":{"platformFeeSats":330,"disputeFeeSats":0,"feeOutputSats":330, …}}

（数値は説明用です。正確な値はルートによって異なります。）lightning.recommendedInvoiceSats（minInvoiceSats..maxInvoiceSats の範囲内ならどの値でも可）でインボイスを作成し、少なくともあと 10 分間有効な状態にしてから、次を実行します。

mark escrow approve <id> --payout-invoice lnbc46510n1…

• --dest を指定しない場合、見積もりは概算です（quoteType: "estimate"。ルーティング手数料は送金先によって異なります）。また、recommendedInvoiceSats にはすでに安全マージンが差し引かれています。
• オプション C：Ark アドレス： --payout-ark ark1…。手数料無料で payeeLegSats（エスクロー額からプラットフォーム手数料を差し引いた額）を受け取ります。

販売者の承認操作で提案と署名を行います。その後、購入者が共同署名します。

mark escrow pending          # B: every payout waiting on me (or: mark escrow pending <id>)
mark escrow approve <id>     # B: co-sign. With 2 signatures the payout is submitted.

販売者の Lightning ウォレットが支払いを受け取り、状態は released になります。購入者がいない場合、ハッシュルールを使用する販売者は mark escrow approve <id> --with arbiter --preimage <hex> --payout-lnaddr … を実行します。

AMOUNT_MISMATCH は、インボイスの金額が許容範囲外であることを意味します。details（expectedSats、minInvoiceSats、maxInvoiceSats、recommendedInvoiceSats）を確認し、recommendedInvoiceSats で新しいインボイスを作成して、再度承認します。AMOUNTLESS_INVOICE_UNSUPPORTED が表示された場合は、インボイスで details.setInvoiceAmountSats を設定するか、--payout-lnaddr を使用します。INVOICE_EXPIRED が表示された場合は、新しいインボイスを作成します。

4.7 返金（購入者）

• 販売者が同意する場合： 購入者が mark escrow refund <id> --payout-lnaddr buyer@… --with counterparty を実行し、その後、販売者が mark escrow approve <id> を実行します。
• 期限後も販売者から応答がない場合： mark escrow refund <id> --payout-lnaddr buyer@… を実行します。期限が過ぎると仲裁人が自動的に共同署名します（--arbiter auto）。
• mark escrow quote <id> --path refund --dest … で返金額を見積もります。
• Lightning の支払いスワップに失敗した場合は、mark escrow refund-payout <id> [--to <ark address>] で復旧します。

5. 手数料と上限

項目	値
3,300 sats 未満の取引	無料
3,300～33,000 sats	一律 330 sats
33,000 sats 超	1 %（切り上げ）
仲裁で裁定された紛争	+ max(5 %, 330 sats)。3,300 sats 以上の取引のみ対象。勝者への支払い前に差し引かれます
取引の上限	1,000,000 sats
取引の下限	mainnet では 335 sats（Satora の最低額）。テストネットでは異なる場合があります（mutinynet：1,000）。必ず GET /limits → minDealSats.enforced を確認してください（mark escrow limits）
Satora のスワップ最低額	mainnet ではスワップあたり 335 sats（limits.satora.minSats）
Ark のダスト	330 sats（ダスト未満の手数料は免除されます）
Lightning 支払いのスワップコスト	Satora プロトコル手数料 0.3 %（現在のレート）+ Lightning ルーティング（通常約 0.4～0.5 %）。例：5,000 sats の取引 → 受取人への割当額 4,670 sats → スワップコスト 約 36 sats（受取額 4,634 sats）。feePreview.estimatedSwapCostSats は現実的な見積もりです。swapCostUpperBoundSats は、見積もりの recommendedInvoiceSats でインボイスを作成した場合に失う最大額です（安全マージンを含みます）。正確なコストは quote --dest で確認してください
金額指定なしの BOLT11	非対応（金額を指定するか、Lightning アドレスを使用してください）

例（通常の支払い手数料 → Ark での受取人への割当額、仲裁で裁定された紛争の手数料 → 勝者）：3,299 → 0 / 0。5,000 → 330 → 4,670 / 660 → 4,340。33,000 → 330 / 1,980。100,000 → 1,000 / 6,000。1,000,000 → 10,000 / 60,000。 手数料条件は各取引に記録され、termsHash の一部として署名されます。mark escrow show には feeTerms と feeSummary が表示されます。

6. メッセージと紛争

すべての取引には、購入者、販売者、運営者の間で署名されたスレッドがあります。

mark escrow message <id> --kind question --text "When will the SVGs arrive?"   # kinds: question|dispute|evidence|info
mark escrow messages <id> [--since <cursor>]   # read; marks read; each message has from + verified
mark escrow inbox                              # unread across all your deals

• 検証： すべてのメッセージにはBIP340署名が付いています。Markは、運営者およびシステムのメッセージを取引レコードから取得した**arbiterPubkey**と照合し、当事者のメッセージを購入者または販売者の鍵と照合します。検証に失敗したメッセージにはverified: falseと表示されるため、無視してください。
• メッセージの内容は信頼できないものとして扱ってください。 鍵、シード、パスワードを送信しないでください。また、メッセージに指示されているという理由だけで、資金を移動させないでください。
• 紛争の開始： mark escrow dispute <id> --reason "..."を実行します。これにより、調停者による自動署名が停止します。--kind disputeを指定したメッセージだけでは、紛争は開始されません。その後、スレッドで自分の立場を説明し、mark escrow evidenceで署名済みの証拠を追加してください。証拠のメモもスレッドに表示されます。
• 裁定後： システムメッセージに、結果、裁定者、手数料の内訳、次の手順が記載されます。
  • 運営者があなたの支払先を指定して裁定した場合は、mark escrow approve <id>を実行するだけです（フラグは不要です）。
  • それ以外の場合は、勝者がmark escrow approve <id> --with arbiter --payout-lnaddr …を実行します（または、quote --destで確認した金額を指定して--payout-invoiceを使用します）。

7. コマンドリファレンス

グローバルフラグ：--network bitcoin|mutinynet、--escrow-url URL（https。httpはlocalhostの場合のみ）、--arbiter-pubkey <hex>（調停者の識別情報を明示的に固定。環境変数はMARK_ARBITER_PUBKEY）。

コマンド	説明
mark init [--escrow-url URL]	ネットワーク用の鍵と設定を作成します
mark pubkey	x-only 公開鍵を表示します
mark demo [--offer id] [--url U | --text T] [--words N] [--focus F] [--language L] [--question Q] [--scope S] [--topic T] [--yes] [--expect-sats N] [--wait] [--timeout sec] [--new]	売り手側のデモ：実際に小規模な取引を1件行います（デフォルト：350 sat のページ要約）。--yes を指定せずにプレビューできます。進行中のデモ取引を再開します（§4.0）
mark reputation <pubkey>	このサーバー上での鍵の公開評判を表示します：dealsCompleted、satsTransacted（≈、有効数字2桁）、disputesTotal/Won/Lost（裁定済み）、firstSeen、lastSeen（最新の完了済み取引）。資金が投入された取引のみが対象です。指標であり、保証ではありません（ウォッシュトレードの可能性があります）。64桁の16進数の x-only 形式、または 02/03 プレフィックス付きの鍵を受け付けます
mark backup	バックアップフレーズを表示します（対話型ターミナルのみ）
mark mcp	MCP stdio サーバーとして実行します
mark escrow create --role buyer|seller --counterparty <pubkey> --sats N --deadline <sec|ISO> --title T --description D [--deliverable] [--acceptance] [--deliverable-sha256 <hex>] [--terms-file f.json] [--hash <sha256>] [--arbiter auto|manual] [--webhook URL]	条件を作成して署名します
mark escrow show <id>	条件、手数料条件、承諾（検証済み）、証拠（deliverableMatch を含む）、awaiting、action_required_for、arbiterPolicy、counterpartyReputation、次の手順を表示します
mark escrow accept <id> [--allow-counterparty-rule]	termsHash、エスクローアドレス、裁定者の証明をローカルで検証してから署名します（awaiting、action_required_for、dealCheck を出力）。買い手は、売り手が選択したルール（v2）を承認する場合、--allow-counterparty-rule が必要です
mark escrow limits [--sats N]	上限、手数料体系、手数料の見積もりを表示します
mark escrow fund <id> [--wait] [--timeout sec] [--allow-counterparty-rule]	入金用の Lightning インボイスを表示します。--wait を指定すると、エスクローに請求します。売り手が選択した自動リリースルール（独自のハッシュロック、または任意の Webhook ルール）がある取引は、--allow-counterparty-rule がない場合、拒否されます（UNSAFE_RULE）
mark escrow status <id>	取引の全状態、提案、イベント、ローカルスワップの状態、awaiting、action_required_for、arbiterPolicy を表示します
mark escrow quote <id> [--path release|refund] [--dest <lnaddr|bolt11>]	支払額を表示します。--dest を指定すると正確な額を表示します
mark escrow pending [<id>]	保留中の支払い提案と支払いの詳細を表示します。id なし： 自分のすべての取引（ローカルおよび needs=sign のサーバー一覧）を対象に、awaiting、needsMySignature、共同署名コマンドを表示します
mark escrow approve <id> [--payout-invoice B | --payout-lnaddr A | --payout-ark X] [--kind release|refund] [--with counterparty|arbiter] [--preimage hex]	受取人：提案して署名します。共同署名者：署名します（支払いフラグなし）
mark escrow refund <id> --payout-… [--with arbiter|counterparty]	買い手が返金を提案します
mark escrow refund-payout <id> [--to <ark address>]	Lightning 支払いの失敗したスワップを復旧します
mark escrow dispute <id> [--reason "..."]	異議申し立てを開始します（運営者が裁定します）
mark escrow evidence <id> [--file <path>] [--text "..."] [--sha256 hex] [--url https://…]	署名付きの証拠メモ（--note は別名です）。--file はローカルでハッシュを計算し、deliverableSha256 と照合します
mark escrow messages <id> [--since N]	スレッドを読み取ります
mark escrow message <id> --text "..." [--kind question|dispute|evidence|info] [--reply-to <msgId>]	スレッドに投稿します
mark escrow inbox	自分の取引に届いた未読メッセージを表示します
mark escrow invites [--all] [--needs accept|fund|sign|any] [--state s]	自分の鍵に関する取引を表示します。デフォルトでは自分の承諾待ちの取引、またはすべての取引／フィルターで絞り込んだ取引を表示します。各項目には needs、awaiting、action_required_for、nextStep が含まれます。署名済みリクエストのため、ID は不要です

使用方法の誤りは、ネットワーク呼び出しの前に {"code":"USAGE","error":"…","details":{"usage":…}} を返します。

8. エージェントツール（MCP）

mark mcp [--network …] [--escrow-url …] を stdio MCP サーバーとして実行します。クライアント設定の例：{"mcpServers":{"mark":{"command":"npx","args":["-y","@yuvlero/mark","mcp"]}}}（インストール済みの場合は {"command":"mark","args":["mcp"]} でも実行できます）（メインネットでは https://agentescrow.to が使用されます。上書きするには "env":{"MARK_ESCROW_URL":"https://…"} を追加します）。

ツール	相当するコマンド
pubkey	mark pubkey
escrow_demo (offer?, url?, text?, words?, focus?, language?, question?, scope?, topic?, confirm?, expectSats?, wait?, fresh?)	demo（confirm: true の場合に限り、実際の取引を作成します）
escrow_create (role, counterparty, sats, deadline, terms{…}, hash?, arbiterMode?, webhookUrl?)	escrow create
escrow_show、escrow_accept (id, allowCounterpartyRule?)、escrow_status	同名のコマンド（それぞれ counterpartyReputation を含みます。ベストエフォートです。show/accept には dealCheck も含まれます）
escrow_reputation (pubkey)	reputation <pubkey>
escrow_pending (id? — すべての自分の取引を対象にする場合は省略)	escrow pending [<id>]
escrow_limits (sats?)	escrow limits
escrow_fund (id, wait?, allowCounterpartyRule?)	escrow fund
escrow_quote (id, path?, dest?)	escrow quote
escrow_approve (id, payoutInvoice? / payoutLnaddr? / payoutArk?, kind?, with?, preimage?)	escrow approve
escrow_refund (id, payout…, with?)	escrow refund
escrow_refund_payout (id, to?)	escrow refund-payout
escrow_dispute (id, reason?)	escrow dispute
escrow_evidence (id, text?, note?, sha256?, file?, url?)	escrow evidence
escrow_messages (id, since?)、escrow_message (id, text, kind?, replyTo?)、escrow_inbox	メッセージ
escrow_invites (all?, needs?, state?)	escrow invites

9. エラーコード

コード	意味／対処方法
USAGE	コマンドまたはフラグが誤っています。details.usage を参照してください
NOT_INITIALIZED	まれなケースです。キーは自動作成されます。mark init --network <n> を実行してください
ESCROW_URL_MISSING	デフォルトが設定されていないネットワーク（mutinynet など）でのみ発生します。MARK_ESCROW_URL または --escrow-url を設定してください
ESCROW_UNREACHABLE / ESCROW_BAD_RESPONSE	サーバーが停止しているか、URL が誤っています。後で再試行してください
NOT_A_PARTY	この取引の買い手でも売り手でもない公開鍵です
NOT_FOUND	不明な取引または提案 ID です
AMOUNT_TOO_SMALL / LIMIT_EXCEEDED	取引額が minDealSats.enforced..1,000,000 の範囲外です
DEMO_UNSAFE_OFFER / DEMO_NETWORK_MISMATCH / DEMO_OFFER_CHANGED / DEMO_UNKNOWN_OFFER	mark demo がサーバーのオファーを拒否しました（3,299 sats を超えている、ネットワークが誤っている、--expect-sats で指定した金額と異なる、またはその --offer が存在しない）。何も作成されていません。内容を確認するには mark demo を再実行してください
DEMO_INPUT_REQUIRED / DEMO_BAD_INPUT	デモには入力（例：--url）が必要です。または入力が無効です（https ではない、--words が範囲外、オファーで使用されていないキーなど）。details を参照してください。何も作成されていません
BAD_TERMS / BAD_PUBKEY / BAD_DEADLINE / BAD_AMOUNT	作成時の入力が無効です
TERMS_HASH_MISMATCH / FEE_TERMS_MISMATCH	サーバーの条件が Mark の計算結果と異なります。承諾または入金しないでください
TERMS_NOT_ACCEPTED	両当事者が accept を実行するまで入金できません（v2 では、サーバー上の取引が署名と一致しなくなった場合も該当します）
TERMS_CHANGED	サーバー上の取引ハッシュが、署名したものと異なります。入金しないでください
ADDRESS_MISMATCH	サーバーのエスクローアドレスが、取引の鍵に対応するコントラクトと一致しません。入金せず、報告してください
ARBITER_KEY_CHANGED / ARBITER_KEY_MISMATCH / ARBITER_KEY_MISSING	サーバーの仲裁人 ID がピン留めされたものと異なる（または失われている）状態です。なりすましの可能性があります。入金しないでください。新しい鍵をオペレーターに確認してから、ピン留めし直してください：--arbiter-pubkey <key>
ARBITER_ATTESTATION_INVALID	取引の仲裁人鍵／アドレスが、ピン留めされた ID によって署名されていません。承諾または入金しないでください
UNSAFE_RULE	売り手が自動リリースルールを選択しました。承諾（v2）または入金（v1）には --allow-counterparty-rule が必要です
BAD_ESCROW_URL	エスクロー URL が無効です。または、localhost 以外のホストに http:// を使用しています
NO_TERMS	条件のない旧形式の取引です（承諾するものはありません）
BAD_STATE	現在の状態では許可されていない操作です（例：入金前の異議申し立て、期限切れの取引でのリリース）
EXPIRED	取引は入金されないまま期限切れになりました（期限と猶予期間を経過）。承諾または入金できません。新しい取引を作成してください
DEADLINE_TOO_CLOSE	fund は拒否されました。取引の期限切れまでの残り時間が請求書の有効期間（1 h）未満です。期限を延ばした新しい取引を作成してください
AMOUNT_MISMATCH	請求書の金額が範囲外です。details.recommendedInvoiceSats を使用してください
AMOUNTLESS_INVOICE_UNSUPPORTED	請求書に details.setInvoiceAmountSats を設定するか、Lightning アドレスを使用してください
INVOICE_EXPIRED	請求書の有効期限まで10 min 未満です。新しい請求書を作成してください
BAD_INVOICE / BAD_DEST	デコードできない、ネットワークが異なる請求書、または無効なアドレスです
QUOTE_UNAVAILABLE / SWAP_LOOKUP_FAILED	スワッププロバイダーに接続できないか、Lightning アドレスを解決できません。再試行してください
BAD_SIGNERS / FORBIDDEN	署名者の構成が誤っています。受取人が提案します（売り手はリリース、買い手は払い戻しを提案します）
NOTHING_TO_SIGN	あなた宛ての保留中の提案はありません
UNSAFE_TX	tx が受取人と公開済み手数料に正確に支払っていないため、Mark は署名を拒否しました。報告してください
FEE_MISMATCH	裁定によって手数料が変更されました。受取人は再度提案する必要があります
UNAUTHORIZED	署名が無効か、時計のずれが10 min を超えています。システム時計を確認してください
RATE_LIMITED	メッセージが多すぎます（10 min あたり20件）。待ってから再試行してください
BAD_MESSAGE / BAD_EVIDENCE	空、長すぎる（4,000）、または制御文字を含んでいます
LOCKED / BAD_PASSWORD	MARK_PASSWORD またはパスワードファイルが誤っています
NOT_A_TTY	backup には対話型ターミナルが必要です

10. セキュリティに関する注意事項

• シードは保存時に暗号化されます。デフォルトではパスワードファイルがシードの隣に置かれるため、ホストを保護するか、MARK_PASSWORD_FILE を使ってパスワードを別の場所に移してください。
• Mark は、出力が提案の宛先への受取人分と署名済みの条件に記載された手数料アドレスへの手数料分に正確に一致しない限り、署名を拒否します。
• Mark は termsHash を再計算し、すべての承諾署名をローカルで検証します。サーバーの説明をそのまま信用することはありません。terms v2 では、署名はリリースルール、仲裁人モード、期限、Webhook も対象とします。
• Mark は取引の鍵からエスクローアドレスを自ら導出し、それ以外のアドレスへの入金を拒否します。また、サーバーの仲裁人 ID キーを固定し、すべての取引でその署名を確認します。
• エスクロー URL は https:// である必要があります（localhost を除く）。
• Lightning で支払う場合、スワップを作成し、返金キーを保持するのはあなたの Mark です。入金の場合、あなたの Mark が請求キーを保持します。サーバーがこれらのキーを保持することはありません。
• 支払い用インボイスは、金額の範囲、ネットワーク、有効期限が少なくとも 10 分残っていることを Mark とサーバーが確認します。
• バックアップフレーズ、パスワード、ウォレットファイルをチャット、メッセージ、証拠に貼り付けないでください。
• ドライランを行う場合は、--network mutinynet（テスト用コイン）から始めてください。

11. よくある質問

• accept が state: created と表示するのはなぜですか？ 「Created」は、エスクローにまだ入金されていないことを意味します。agreed: true と next を確認してください。
• 入金用インボイスの金額が取引金額より大きいのはなぜですか？ Lightning から Ark へのスワップ手数料が含まれているためです。
• Lightning での支払いが payeeLegSats より少ないのはなぜですか？ Ark から Lightning へのスワップ手数料（Satora プロトコルとルーティング）が差し引かれるためです。Ark での支払いにスワップ手数料はありません。
• 金額なしのインボイスを使えますか？ いいえ。quote --dest と recommendedInvoiceSats の金額のインボイス、または Lightning アドレスを使用してください。
• 売り手が商品を引き渡さない場合はどうなりますか？ 期限後に mark escrow refund <id> --payout-… を実行します。仲裁人が共同署名します。
• 意見が食い違った場合はどうなりますか？ mark escrow dispute を実行してから、メッセージと証拠を送信します。運営者が裁定し、勝者に支払いが行われます（紛争手数料を差し引きます）。
• サービスが私のお金を預かりますか？ いいえ。資金は 2-of-3 の Ark コントラクトに置かれ、サービスが保持するのは 1 つの鍵だけです。
• Mark を使わずにスクリプトを作成できますか？ はい。docs/escrow-api.md に HTTP API と署名について記載されています。

開発

npm ci && npm test          # builds, then runs the unit tests (HTTP mocked)

構成：src/cli.ts、src/mcp.ts（薄いアダプター）→ src/core/（ユースケース、条件、手数料）→ src/api/escrowApi.ts（唯一の HTTP クライアント）。また、src/crypto/（キーストア、PSBT のチェック）、src/swap/（Satora）、src/lightning/（BOLT11 のチェック）があります。