Signer tools

Thirteen tools on referrer-signer, the server that runs on your machine over stdio and holds the private key. Eight sign an EIP-712 commitment and return a signature. Five send a transaction; none carries a commitment, and the four that call a contract spend your own key's gas. Nothing here calls our backend except pay_for_product, and even that decodes the ref link locally rather than asking us to resolve it.

Configuration

At least one of AGENT_KEYS and AGENT_PRIVATE_KEY must be set or the process exits at boot. Key selection is by agent id: an exact AGENT_KEYS entry first, then the fallback. The fallback answers for any agent id, which is why a wrong-agent transaction is caught by the contract rather than by the key lookup.

The seven commitment-object signing tools

Seven of the eight signing tools take the same shape — one commitment object, passed exactly as the referrer-agent step-1 response returned it, including its types and primaryType — and all seven return the same shape: a single signature, 0x-prefixed 65-byte hex, ready to pass back as agent_sig. sign_charge_commitment is the eighth and is the exception on both counts; it has its own section below.

Do not strip or reshape the object. The signer recomputes the digest from domain and message and ignores types/primaryType, but it must still accept them, and the key it signs with is selected from message.agentId.

Returns, all seven

Errors, all seven

There is no signature verification here and no policy check: whatever commitment you hand it, it signs. The gate is on the receiving end — and it is the identity owner's key that gate wants on all seven, because the backend's step-2 check recovers the signer and compares it against ownerOf. A signature from the bound agent wallet is rejected even where the contract itself would have accepted it; see Identity and commitments.

The message shape differs per commitment, and so does the form of nonce. Each tool below shows the one it must receive. domain is elided in the examples — pass through whatever step 1 returned.

sign_review_commitment

Signs a ReviewCommitment. Call it between submit_admin_approved_review steps 1 and 2.

{ "commitment": { "primaryType": "ReviewCommitment", "types": { }, "domain": { },
  "message": { "agentId": "7", "merchantId": "3", "productId": "0x1f…",
               "contentHash": "0x9c…", "nonce": "834…", "expiry": "1785…" } } }

nonce is a decimal uint256 string here.

sign_vote_commitment

Signs a VoteCommitment. Call it between cast_review_votes steps 1 and 2.

{ "commitment": { "primaryType": "VoteCommitment", "types": { }, "domain": { },
  "message": { "agentId": "7", "escrowId": "88", "votesHash": "0x4b…",
               "nonce": "1290…", "expiry": "1785…" } } }

nonce is a decimal uint256 string here too. votesHash commits to the whole votes array, so it cannot change between the caller's two steps.

sign_cashback_rate_commitment

Signs a CashbackRateCommitment. Call it between set_default_cashback_rate steps 1 and 2.

{ "commitment": { "primaryType": "CashbackRateCommitment", "types": { }, "domain": { },
  "message": { "agentId": "7", "cashbackOfCommissionBps": "1500",
               "nonce": "0x6d…", "expiry": "1785…" } } }

From here down, nonce is 0x-prefixed 32-byte hex, not a decimal.

sign_telegram_link_commitment

Signs a TelegramLinkCommitment. Call it between link_telegram steps 1 and 2.

{ "commitment": { "primaryType": "TelegramLinkCommitment", "types": { }, "domain": { },
  "message": { "agentId": "7", "nonce": "0x6d…", "expiry": "1785…" } } }

The caller burns this nonce on use, so a signature is good for exactly one deep link.

sign_intent_access_commitment

Signs an IntentAccessCommitment. Call it between get_pending_intents steps 1 and 2.

{ "commitment": { "primaryType": "IntentAccessCommitment", "types": { }, "domain": { },
  "message": { "agentId": "7", "nonce": "0x6d…", "expiry": "1785…" } } }

This is the one signature that authorises a read, and its nonce is not burned — treat it as a short-lived read token.

sign_intent_mark_commitment

Signs an IntentMarkCommitment. Call it between mark_intent_executed steps 1 and 2.

{ "commitment": { "primaryType": "IntentMarkCommitment", "types": { }, "domain": { },
  "message": { "agentId": "7", "intentId": "itn_9f3c…", "result": "escrow:88",
               "nonce": "0x6d…", "expiry": "1785…" } } }

intentId and result are both inside the signed struct, so this signature authorises exactly one intent recorded with exactly one result. result may be the empty string.

sign_intent_skip_commitment

Signs an IntentSkipCommitment. Call it between mark_intent_skipped steps 1 and 2.

{ "commitment": { "primaryType": "IntentSkipCommitment", "types": { }, "domain": { },
  "message": { "agentId": "7", "intentId": "itn_9f3c…",
               "reason": "live price above the confirmed cap",
               "nonce": "0x6d…", "expiry": "1785…" } } }

Same shape as the mark commitment with reason in place of result — and unlike result, the caller requires it to be non-empty.

sign_charge_commitment

Signs a ChargeCommitment with the buyer wallet that made the charge transfer and owns the buyer agent.

This one takes five explicit arguments rather than a commitment object, because the values come from the payment you just made rather than from a step-1 response. The resulting signature goes to POST /mpp/charge as buyerSignature, not back into an MCP tool.

{ "txHash": "0x…", "attributionToken": "eyJ…", "buyerAgentId": "7" }

…plus chainId (a number) and splitRouterAddr, both required and both rejected at zero.

Parameters

The payer address in the commitment is derived from the key, not passed — the charge endpoint requires the recovered signer to equal the on-chain transfer sender.

Returns

Errors

pay_for_product

Completes an x402 buyer payment through a ref link, and optionally casts the buyer's votes in the same call.

It decodes the self-contained ref link locally — verifying its Ed25519 signature against the protocol attestation key — to read the merchant endpoint, the settlement router and the chain straight out of the token. Then it probes the merchant for payment requirements, signs an ERC-3009 authorisation, submits the payment, and waits for the on-chain deposit event.

{ "agent_id": "7", "ref_link": "https://…/r/eyJ…", "max_amount": "50000000",
  "idempotency_key": "itn_9f3c…" }

Parameters

max_amount and idempotency_key are the safety rails for an agent-runner executing a confirmed intent. Pass the intent's own approved amount as max_amount, or a price rise between confirmation and execution is authorised silently. idempotency_key makes the payment at-most-once on-chain: the nonce is derived from the payer and the key, so a retry of the same purchase reuses it and the second transfer reverts — pass the intent id.

Returns

A vote failure never voids the payment. If votes_error is set, the purchase stands and the escrow exists; retry the votes with cast_review_votes using the returned escrow_id.

Omitting agent_id buys agent-less: the buyer wallet is recorded on-chain for a later identity bind, cashback is held until then, and inline voting is refused. bind_escrow is how you claim it afterwards.

Errors

publish_escrow_review

Publishes a buyer review on-chain using an escrow purchase as proof.

Call it after a purchase is confirmed, then sync it with register_purchase_review. Unlike the other three contract-call tools it takes no chain_id argument — it reads CHAIN_ID and cannot be overridden per call.

{ "agent_id": "7", "merchant_id": "3", "product_id": "0x1f…",
  "content_json": "{\"rating\":4,\"description\":\"…\"}", "escrow_id": "88" }

Parameters

The content hash is computed from the merchant and product ids read off the escrow, not from the ones you passed — the contract stores the escrow's values, so a hash over anything else could never be reproduced by a verifier.

Returns

Errors

bind_escrow

Binds an agent-less purchase's escrow to your ERC-8004 agent identity.

It unlocks the deferred cashback and enables the deferred review. Two preconditions, both on the key: the signing key must be the exact wallet that paid the agent-less purchase, and it must already own agent_id. Register the identity first — that is out of scope for this tool.

{ "agent_id": "7", "escrow_id": "88" }

Parameters

Returns

Binding is one-shot. Afterwards the backend rebinds the purchase automatically, and cast_review_votes, publish_escrow_review and register_purchase_review all become available.

Errors

The five decoded refusals cost one estimate and no gas.

trigger_settle_fallback

Force-settles an escrow the oracle never settled.

Permissionless: any agent may call it, on any escrow, once 10 days have passed after that escrow's windowEnd. Around day 70.

{ "agent_id": "7", "escrow_id": "88" }

Parameters

Returns

On checking eligibility first. get_escrow_status reports fallback_available, but derives its day-70 date from the indexed confirmation date rather than the contract's own windowEnd, so on a non-default settlement window it can be wrong. This tool reads windowEnd itself and refuses with the real date, so calling it and reading a refusal costs one RPC call and no gas.

Errors

update_review_content_onchain

Edits a buyer review's content hash on-chain, inside its 7-day window.

First of two calls: this one updates only the hash, and you must then call update_review_content on referrer-agent with the same review_id and the same content_json to sync the stored text and re-score alignment.

{ "review_id": "412", "content_json": "{\"rating\":5,\"description\":\"…\"}" }

Parameters

Do not pass agent, merchant or product ids: the tool reads the review from the chain, both to build the hash from the authoritative ids and to pick the signing key. A hash built over any other ids would be accepted by the contract and then permanently un-syncable, with the window running down.

Returns

Errors

Next steps

• The eight commitments — the eight type strings, byte for byte
• Review tools — the referrer-agent half of publishing and editing
• Payment flow — what the fallback pays, and to whom