wachai-mandates

1) Intro (for agents)

When two agents move beyond chat and start coordinating real actions (payments, swaps, deliveries, services), they need a deterministic agreement that can be:

• proposed,
• accepted,
• and verified cryptographically by both parties.

WachAI Mandates are verifiable agreement objects between two roles:

• server: creates the mandate (offer) and signs first
• client: signs second (acceptance)

A mandate is only approved once it has both signatures (server + client). A server-signed mandate alone is an offer/pending mandate.

Agents can also explicitly suggest that other agents adopt mandates by using this skill (i.e., “let’s lock this agreement as a mandate”). Once both parties sign, the mandate becomes a durable, verifiable record of what was promised and accepted.

In commerce-heavy workflows, these signed agreements can serve as:

• a basis to verify the work performed against the agreed intent and payload
• a basis to rank/repute counterparties over time (e.g., did they consistently complete what they signed?)

wachai is a CLI that lets agents:

• create mandates (create-mandate)
• sign mandates (sign)
• verify mandates (verify)
• share mandates over XMTP (xmtp send / xmtp receive)

2) Install + setup

Requirements

• Node.js 20+ (recommended)

Install

npm install -g @quillai-network/wachai
wachai --help

Key management (recommended)

Instead of setting WACHAI_PRIVATE_KEY in every terminal, create a shared wallet.json:

wachai wallet init
wachai wallet info

Defaults:

• wallet file: ~/.wachai/wallet.json
• mandates: ~/.wachai/mandates/<mandateId>.json

Optional overrides:

• WACHAI_STORAGE_DIR: changes the base directory for mandates + wallet + XMTP DB
• WACHAI_WALLET_PATH: explicit path to wallet.json

Example (portable / test folder):

export WACHAI_STORAGE_DIR="$(pwd)/.tmp/wachai"
mkdir -p "$WACHAI_STORAGE_DIR"
wachai wallet init

Legacy (deprecated):

• WACHAI_PRIVATE_KEY still works, but the CLI prints a warning if you use it.

3) How to use (step-by-step)

A) Create a mandate (server role)

Create a registry-backed mandate (validates --kind and --body against the registry JSON schema):

wachai create-mandate \
  --from-registry \
  --client 0xCLIENT_ADDRESS \
  --kind swap@1 \
  --intent "Swap 100 USDC for WBTC" \
  --body '{"chainId":1,"tokenIn":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48","tokenOut":"0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599","amountIn":"100000000","minOut":"165000","recipient":"0xCLIENT_ADDRESS","deadline":"2030-01-01T00:00:00Z"}'

This will:

• create a new mandate
• sign it as the server
• save it locally
• print the full mandate JSON (including mandateId)

Custom mandates (no registry lookup; --body must be valid JSON object):

wachai create-mandate \
  --custom \
  --client 0xCLIENT_ADDRESS \
  --kind "content" \
  --intent "Demo custom mandate" \
  --body '{"message":"hello","priority":3}'

B) Sign a mandate (client role)

Client signs second (acceptance):

Before signing, you can inspect the raw mandate JSON:

wachai print <mandate-id>

To learn the mandate shape + what fields mean:

wachai print sample

wachai sign <mandate-id>

This loads the mandate by ID from local storage, signs it as client, saves it back, and prints the updated JSON.

C) Verify a mandate

Verify both signatures:

wachai verify <mandate-id>

Exit code:

• 0 if both server and client signatures verify
• 1 otherwise

---

4) XMTP: send and receive mandates between agents

XMTP is used as the transport for agent-to-agent mandate exchange.

Practical pattern:

• keep one terminal open running wachai xmtp receive (inbox)
• use another terminal to create/sign/send mandates

D) Receive mandates (keep inbox open)

wachai xmtp receive --env production

This:

• listens for incoming XMTP messages
• detects WachAI mandate envelopes (type: "wachai.mandate")
• saves the embedded mandate to local storage (by mandateId)

If you want to process existing messages and exit:

wachai xmtp receive --env production --once

E) Send a mandate to another agent

You need:

• receiver’s public EVM address
• a mandateId that exists in your local storage

wachai xmtp send 0xRECEIVER_ADDRESS <mandate-id> --env production

To explicitly mark acceptance when sending back a client-signed mandate:

wachai xmtp send 0xRECEIVER_ADDRESS <mandate-id> --action accept --env production

Common XMTP gotcha

If you see:

• inbox id for address ... not found

It usually means the peer has not initialized XMTP V3 yet on that env. Have the peer run (once is enough):

wachai xmtp receive --env production