Call the tools.
The thirteen MCP tools, with arguments and example responses. The server uses CLI Protocol 5.
This page describes the Starknet backend. For Monad, see the Monad tool surface.
The tool surface
Negotiate, settle, disclose
Recovery & ops
A negotiation uses open_channel, propose_offer, wait_for_offers, counter_offer, and accept_and_settle, followed by grant_viewing_key and reveal to disclose the settled deal.
Every write operation requires an operation_id. Save the ID and request before the call. Reuse that ID after a restart. More on this under core concepts.
This page documents CLI Protocol 5 (v0.3.0), which exposes the thirteen tools listed above. Protocol 5 adds account setup through the installed package (erebus-init) while retaining Protocol 4’s operation_id mechanics for settlement requests. Version v0.2.0 implements Protocol 4, while v0.1.0 implements Protocol 2 with ten tools. To detect incompatible request and response formats, erebus-sdk validates protocol compatibility by protocol number before each call.
Request and response, per tool
All responses use the standard envelope {ok, backend, network, result | error}. Write operations include the operation_id supplied in the request. In the examples below, {"...": "..."} indicates fields truncated for readability.
An offer_id uses the format <channel>:us:<n> or <channel>:them:<n>, where us and them are relative to the caller. A single offer appears as us:0 to its proposer and them:0 to the recipient; an ID copied from the counterparty’s transcript refers to the wrong direction in your session. Unless noted otherwise, example payloads represent a single payer session.
open_channel
Request
{"operation_id": "op_3f9a...c02e", "counterparty": "0x04a1...9bd2"}Response
{"ok": true, "backend": "seam", "network": "sepolia",
"result": {"channel_handle": "ch_9f8106a8...29c6d12ac"},
"operation_id": "op_3f9a...c02e"}propose_offer
Request
{"operation_id": "op_1b7e...44aa", "channel_handle": "ch_9f8106a8...29c6d12ac",
"amount": "800000000000000000", "token": "0x0471...11ee",
"deadline": 1768003600, "memo_hash": "0x9f2c...ab01"}Response
{"ok": true, "backend": "seam", "network": "sepolia",
"result": {"offer_id": "ch_9f8106a8...29c6d12ac:us:0"},
"operation_id": "op_1b7e...44aa"}counter_offer
Request
{"operation_id": "op_5a11...09dc", "channel_handle": "ch_9f8106a8...29c6d12ac",
"reply_to": "ch_9f8106a8...29c6d12ac:them:0", "amount": "600000000000000000",
"token": "0x0471...11ee", "deadline": 1768003600, "memo_hash": "0x9f2c...ab01"}Response
{"ok": true, "backend": "seam", "network": "sepolia",
"result": {"offer_id": "ch_9f8106a8...29c6d12ac:us:0"},
"operation_id": "op_5a11...09dc"}This example runs on the payee. reply_to names the other party's offer (them:n). The response names the new counteroffer (us:n). Countering your own offer returns NOT_YOUR_OFFER.
wait_for_offers
Request
{"channel_handle": "ch_9f8106a8...29c6d12ac", "expected_count": 2, "timeout_seconds": 300}Response
{"ok": true, "backend": "seam", "network": "sepolia",
"result": {
"offers": [{"offer_id": "ch_9f8106a8...29c6d12ac:us:0", "deal_id": "319440722280485962",
"proposer": "0x04a1...9bd2", "status": "countered", "reply_to": null,
"created_at": 1768000012,
"terms": {"amount": "800000000000000000", "token": "0x0471...11ee",
"deadline": 1768003600, "memo_hash": "0x9f2cab01..."}},
{"offer_id": "ch_9f8106a8...29c6d12ac:them:0", "deal_id": "319440722280485962",
"proposer": "0x0763...c94f", "status": "proposed",
"reply_to": "ch_9f8106a8...29c6d12ac:us:0", "created_at": 1768000221,
"terms": {"amount": "600000000000000000", "token": "0x0471...11ee",
"deadline": 1768003600, "memo_hash": "0x9f2cab01..."}}],
"settlements": [], "timed_out": false}}expected_count counts all offers in the channel, including those already read. After the first proposal, set it to 2 to wait for a counteroffer. A counteroffer changes the original status to countered but does not cancel it. The original remains available until settlement or expiry.
read_channel_state
Request
{"channel_handle": "ch_9f8106a8...29c6d12ac"}Response
{"ok": true, "backend": "seam", "network": "sepolia",
"result": {"offers": [{"...": "same offer shape as wait_for_offers"}],
"settlements": [{"acceptance": "ch_9f8106a8...29c6d12ac:us:1", "accepted_offer": "ch_9f8106a8...29c6d12ac:them:0",
"agreed_amount": "600000000000000000", "paid_amount": "600000000000000000",
"consistency": "consistent"}]}}accept_and_settle
Request
{"operation_id": "op_c810...6f3e", "channel_handle": "ch_9f8106a8...29c6d12ac",
"offer_id": "ch_9f8106a8...29c6d12ac:them:0"}Response
{"ok": true, "backend": "seam", "network": "sepolia",
"result": {"offer_id": "ch_9f8106a8...29c6d12ac:them:0", "tx_hash": "0x79167f21...f97a",
"nullifiers": ["0x2c11...", "0x88a0..."], "proved_at": 1768000042,
"selected_input": "800000000000000000", "change": "200000000000000000"},
"operation_id": "op_c810...6f3e"}get_note_balance
Request
{}Response
{"ok": true, "backend": "seam", "network": "sepolia",
"result": {"spendable_notes": ["500000000000000000", "300000000000000000"],
"total": "800000000000000000", "pending_notes": []}}grant_viewing_key
Request
{"operation_id": "op_e922...10ab", "channel_handle": "ch_9f8106a8...29c6d12ac",
"deal_id": "319440722280485962", "grantee": "0x0763...c94f",
"expires_at": 1769990000, "output_path": "~/.erebus-c/grants/deal.json"}Response
{"ok": true, "backend": "seam", "network": "sepolia",
"result": {"channel_id": "ch_9f8106a8...29c6d12ac", "deal_id": "319440722280485962",
"grantee": "0x0763...c94f", "expires_at": 1769990000,
"grant_path": "/home/you/.erebus-c/grants/deal.json"}}reveal
Request
{"grant_path": "/home/you/.erebus-c/grants/deal.json"}Response
{"ok": true, "backend": "seam", "network": "sepolia",
"result": {"channel_id": "ch_9f8106a8...29c6d12ac", "participants": ["0x04a1...9bd2", "0x0763...c94f"],
"offers": [{"...": "same offer shape as wait_for_offers, this deal only"}],
"settlement": {"acceptance": "ch_9f8106a8...29c6d12ac:us:1", "accepted_offer": "ch_9f8106a8...29c6d12ac:them:0",
"agreed_amount": "600000000000000000", "paid_amount": "600000000000000000",
"consistency": "consistent"}}}reconcile
Request
{}Response
{"ok": true, "backend": "seam", "network": "sepolia",
"result": [{"operation_id": "op_c810...6f3e", "operation": "accept_and_settle",
"request": {"...": "the canonical replay request recorded before execution"},
"stage": "submitted", "channel": "ch_9f8106a8...29c6d12ac",
"transaction_hash": "0x79167f21...f97a", "accepted_at": null,
"outcome": "pending", "next_action": "wait",
"reason": "submitted but acceptance not yet confirmed on chain"}]}resume_operation
Request
{"operation_id": "op_c810...6f3e"}Response
{"ok": true, "backend": "seam", "network": "sepolia",
"result": {"result": "already_complete", "transaction_hash": "0x79167f21...f97a"}}This example returns already_complete. The result.result field can contain: already_complete, local_state_behind, resubmitted, recovered_proof, rebuilt, rebuild_required, or reconciliation_required. Other fields depend on the status. For example, rebuild_required returns a reason string instead of a transaction_hash.
rebuild_state
Request
{}Response
{"ok": true, "backend": "seam", "network": "sepolia",
"result": {"channels_found": 3, "rebuilt": ["ch_9f8106a8...29c6d12ac"],
"kept": 2, "other_token": 0, "unrecoverable": 0}}doctor
Request
{}Response
{"ok": true, "backend": "seam", "network": "sepolia",
"result": {"ready": true,
"checks": [
{"name": "rpc", "status": "pass", "detail": "reachable, head is block 14200931"},
{"name": "prover", "status": "pass", "detail": "reachable, spec 0.14.2"},
{"name": "allowance", "status": "pass", "detail": "3 writes funded"},
{"...": "pool_key_file, account_key_file, state_dir, chain_id, pool, registration, gas_balance also run"}
],
"repairs": []}}