Handoff Docs
Protocol ETHOnline 2026

Agent-built. Expert-verified.
On-chain.

Your agent fleet can draft, design, and ship — but the last mile needs a human who knows the domain. Handoff connects agents to credentialed experts who verify or complete the work. Funds lock up front, the expert signs off, and the proof lives on Hedera.

Get started View on GitHub

Quick start

Post an order from your agent

# Add the MCP server to your client config
# Then ask your agent:

I drafted a quarterly financial report for
submission to the tax authority. Have a certified
accountant verify the numbers and flag any
compliance issues before I file.

# Your agent calls handoff_verify, pays the
# 0.5 HBAR service fee, locks 100 HBAR in
# escrow, and waits for the expert's signed
# verdict.

How it works

From request to proof in six steps

One order, one credentialed expert, one signed verdict. A straight line from posting to payment.

1
Ask agent
→
2
0.5 HBAR fee
→
3
100 HBAR locked
→
4
Expert claims
→
5
Reviews & signs
→
6
Paid + verdict
1
Agent

You ask your agent

Describe the work in natural language and attach the document. Your agent picks the right credential and calls handoff_verify.

MCP tool call
Any MCP-compatible agent can call handoff_verify — Claude Code, Claude Desktop, or custom agents. No SDK integration needed.
2
x402

Agent pays the service fee

0.5 HBAR flows through x402 via the Blocky402 facilitator. This micropayment posts the order to Hedera.

x402 · 0.5 HBAR
The x402 protocol gates the API. Your agent partially signs a transfer; the Blocky402 facilitator co-signs as fee payer and settles on Hedera testnet. The fee is separate from the escrow.
3
Hedera

Funds lock in escrow

100 HBAR locks in a 2-of-3 threshold escrow. Only hashes go on-chain — the document stays private.

2-of-3 threshold key
The escrow is a Hedera account with a 2-of-3 threshold key: requester, platform verifier, and schedule admin. No single party can move the funds alone. Release requires the attestation to pass schema validation.
4
Hedera

A credentialed expert claims it

Only experts holding the required certification see the order. The claim is signed by the expert's own account.

credential routing · HCS
The claim is an HCS message signed by the expert's Hedera account. Consensus timestamp determines who won the race, not the UI. If a claim times out, the order reopens for the next expert.
5
On-chain

Expert reviews and signs

The expert reviews the document, writes defect codes and notes, then signs an attestation to the HCS attestations topic.

on-chain attestation
The account that submits the HCS message IS the signature — the platform is never in the signing path. The attestation is attributable forever, published to a dedicated topic with no submit key.
6
On-chain

Expert gets paid, you get the verdict

The escrow releases to the expert. You receive the verdict, defect codes, notes, and four transaction IDs as proof.

symmetric payment · 100 HBAR
Approve or reject, the expert gets paid the same amount. Payment is verified by a mirror-node read, not by hope. Settlement is confirmed by real transaction IDs that open on Hashscan.
Reject is a delivered product. Experts are paid for judgment, not approval. Funds only return if the submission is mechanically invalid — never over a disagreement.

Economics

Two money flows

Two separate payments happen when you post an order. Here's where each one goes.

Service fee

0.5 HBAR per order

What
Charge to place the order
How
x402 micropayment via Blocky402
When
Before the order posts

Order value

100 HBAR held in escrow

What
Price of the human judgment
How
Locked in a 2-of-3 threshold escrow
When
Locked at posting, paid at verdict
If nobody claims by the deadline, the escrow returns to you. The service fee does not refund — it paid for the order to be posted.

Tools

MCP tools

Your agent interacts with Handoff through two MCP tools. One submits work for expert verification, the other checks on progress.

GATED handoff_verify Submit work for expert verification
FREE handoff_status Check progress and get the verdict

handoff_verify

Submit work for expert verification. Your agent sends the document, states what to check for, and names the credential. The tool handles the x402 payment, posts the order to HCS, locks the escrow, and waits for the signed verdict.

artifact The document to review. Plain text.
ask What the expert should check for. One paragraph.
credential Required certification, e.g. "Certified accountant".

Response

// The signed verdict, with proof
{
  "verdict": "reject",
  "defects": ["REVENUE_MISMATCH", "MISSING_DISCLOSURE"],
  "notes": "Q3 revenue doesn't match the ledger...",
  "signed_by": "0.0.5234871",
  "proof": {
    "fee_tx": "0.0.x@1725...",
    "lock_tx": "0.0.x@1725...",
    "verdict_tx": "0.0.x@1725...",
    "payout_tx": "0.0.x@1725..."
  }
}
x402 gated · 0.5 HBAR

handoff_status

Check the status of a posted order. Returns the current lifecycle state, claim info, and settlement proof when available.

order_id The order id returned by handoff_verify.
No fee · read only

Setup

Installation

Three steps to your first expert-verified result.

1 Add the client config

The client is one npm package, @hedera-handoff/mcp-client, started with npx. It runs on your machine and signs there; the service never sees your key. Keep the key in your shell profile and let ${...} expand it.

Claude Code · .mcp.json

{
  "mcpServers": {
    "handoff": {
      "command": "npx",
      "args": ["-y", "@hedera-handoff/mcp-client"],
      "env": {
        "HANDOFF_SERVICE_URL": "https://api.the-handoff.xyz",
        "X402_PAYER_ACCOUNT_ID": "${X402_PAYER_ACCOUNT_ID}",
        "X402_PAYER_PRIVATE_KEY": "${X402_PAYER_PRIVATE_KEY}"
      }
    }
  }
}

Claude Desktop · claude_desktop_config.json

{
  "mcpServers": {
    "handoff": {
      "command": "npx",
      "args": ["-y", "@hedera-handoff/mcp-client"],
      "env": {
        "HANDOFF_SERVICE_URL": "https://api.the-handoff.xyz",
        "X402_PAYER_ACCOUNT_ID": "0.0.YOUR_ACCOUNT",
        "X402_PAYER_PRIVATE_KEY": "your-ecdsa-key"
      }
    }
  }
}

2 Get a Hedera testnet account

Visit the Hedera Portal to create a free testnet account — it takes a minute. Get test HBAR from the faucet. Your account must use an ECDSA key (not ED25519) for the x402 payment to work.

How much HBAR? Each order costs 0.5 HBAR (service fee) plus 100 HBAR (escrow). The testnet faucet gives enough for several orders. The escrow returns if no expert claims by the deadline.

3 Ask your agent to verify something

# In Claude Code or any MCP client

I drafted a quarterly financial report for
submission to the tax authority. Have a certified
accountant verify the numbers and flag any
compliance issues before I file.

Your agent calls handoff_verify, pays the service fee, locks the escrow, and waits for the expert's signed verdict.

On-chain

The attestation

Every verdict is permanently recorded on Hedera, signed by the expert's own account. It can never be altered or denied.

What gets published on-chain
order_id Which order this verdict answers
class review (returns a verdict) or execution (returns the outcome itself)
verdict approve, approve_with_changes, or reject
defects[] Machine-readable issues the expert found, e.g. REVENUE_MISMATCH.
notes_hash SHA-256 of the expert's written notes. The notes are delivered to you privately; only the fingerprint is published.
artifact_hash_in Fingerprint of the document the requester committed to.
cert_tag The credential the expert held when they signed
schema_version Ensures old attestations stay parsable as the format evolves
What stays private: the expert's written notes, the document itself, and the requester's identity. The on-chain hash is the commitment; parties keep their own copies.