> ## Documentation Index
> Fetch the complete documentation index at: https://docs.walletwall.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Run WalletWall MCP end to end on synthetic evidence: resolve an asset, normalize a reading, evaluate a bundle, and watch readiness fail closed when evidence is missing.

> [!NOTE]
>
> **INSTALLABLE · LOCAL · PRE-RELEASE**
>
> Not independently reviewed. See [what you can use today](https://docs.walletwall.org/concepts/product-status.md) for every surface
> side by side.

This walkthrough runs the real server on your machine against **synthetic** evidence that the engine
itself publishes. It needs no wallet, no keys, no network access for the server and no
WalletWall-hosted service, and it is deterministic: the engine never reads a clock, so the same input
and the same evaluation time always give the same result. Every output on this page was produced by
the server on the repository's default branch (engine `0.1.0`, WWEP `0.1`, eleven resources).

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'actorBkg': '#BF4E32', 'actorBorder': '#8B3120', 'actorTextColor': '#FAF8F3', 'actorLineColor': '#8B6F47', 'signalColor': '#1E1A14', 'signalTextColor': '#1E1A14', 'labelBoxBkgColor': '#E6DED2', 'labelBoxBorderColor': '#9A9186', 'labelTextColor': '#1E1A14', 'loopTextColor': '#1E1A14', 'noteBkgColor': '#C9A47A', 'noteBorderColor': '#8B6F47', 'noteTextColor': '#1E1A14', 'activationBkgColor': '#FAF8F3', 'activationBorderColor': '#C9A47A', 'sequenceNumberColor': '#FAF8F3'}}}%%
sequenceDiagram
    autonumber
    actor You
    participant Client as MCP client or script
    participant WW as WalletWall MCP (local, stdio)

    You->>Client: Evidence: a reading or a bundle
    Client->>WW: resources/read walletwall://examples/...
    WW-->>Client: Synthetic bundle and the exact tool call to make
    Client->>WW: tools/call normalize_observation
    WW-->>Client: Canonical observation, digests, exact decimal
    Client->>WW: tools/call inspect_evidence or assess_vault_readiness
    WW-->>Client: States, authority, limitations, classification
    Note over Client,WW: Read-only. No network access, no keys, no files written.
```

## Before you start

Clone the source repository and check your Node.js version (22.18 or newer):

```bash theme={null}
git clone https://github.com/Wallet-Wall/walletwall-copilot.git
cd walletwall-copilot
node --version
```

The server is the committed bundle `plugin/server/walletwall-mcp.mjs`. It imports only Node.js
built-ins, so no `npm install` is needed. Steps 1 and 2 use a POSIX shell (macOS, Linux, WSL or Git
Bash); step 3 runs anywhere Node.js does.

## 1. Ask one question, with no AI client

MCP over stdio is newline-delimited JSON-RPC, so you can pipe messages straight into the server: an
`initialize` request, the `initialized` notification, then one tool call. The server answers each
request on its own line and exits when its input ends.

```bash theme={null}
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"quickstart","version":"1.0.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"resolve_asset","arguments":{"chainId":"1","address":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"}}}' \
  | node plugin/server/walletwall-mcp.mjs
```

The second line is the `resolve_asset` result. Its `structuredContent`, abridged:

```json theme={null}
{
  "origin": "WALLETWALL_DERIVED",
  "registry": { "version": "0.2.0", "status": "VERIFIED_POINT_IN_TIME" },
  "resolution": "REGISTRY_MATCH",
  "supportState": "PARTIAL",
  "asset": {
    "symbol": "USDC",
    "chainId": "1",
    "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "decimals": "6",
    "authorityId": "issuer:circle"
  },
  "limitations": ["REGISTRY_VERIFIED_POINT_IN_TIME", "NO_AUTHORITATIVE_OBSERVATION"]
}
```

The address is in WalletWall's bundled registry, yet the answer is only `PARTIAL`. A registry match is
WalletWall's own lookup (`WALLETWALL_DERIVED`), and no issuer attestation was presented with this
query, so the asset's identity is not `ESTABLISHED`. The registry itself was verified once, against
Circle's publication on 2026-10-24, and says nothing about later changes.

## 2. Normalize a reading

Suppose your own tooling read a balance at a finalized block. `normalize_observation` turns that draft
into a canonical WWEP observation. It does not fetch anything: you supply the reading. The block, hash,
holder and amount below are synthetic.

```bash theme={null}
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"quickstart","version":"1.0.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"normalize_observation","arguments":{"id":"obs-balance","sourceId":"src-chain","origin":"CHAIN_OBSERVED","observedAt":"2026-10-23T12:00:00Z","finality":"FINALIZED","result":"VALUE","chainId":"1","token":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48","holder":"0x1234567890123456789012345678901234567890","blockNumber":"21000000","blockHash":"0xabababababababababababababababababababababababababababababababab","balanceAtomic":"1500000","decimals":"6"}}}' \
  | node plugin/server/walletwall-mcp.mjs
```

Result, abridged (the full response also carries `canonicalJson`, the RFC 8785 serialization that was
hashed):

```json theme={null}
{
  "observation": {
    "id": "obs-balance",
    "sourceId": "src-chain",
    "origin": "CHAIN_OBSERVED",
    "observedAt": "2026-10-23T12:00:00Z",
    "finality": "FINALIZED",
    "result": "VALUE",
    "subject": {
      "chainId": "1",
      "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "holder": "0x1234567890123456789012345678901234567890",
      "blockNumber": "21000000",
      "blockHash": "0xabababababababababababababababababababababababababababababababab"
    },
    "payload": { "balanceAtomic": "1500000", "decimals": "6" }
  },
  "evidenceDigest": "8f47a2811a02769ed92d2491dcf8da2cf1ea418ba1635fa9c45569572cdc3631",
  "contentDigest": "4e5e6bebd6ddd8faaa875914de602b8ad15dc40e0ad11aca2886290847fd3bb2",
  "balanceDecimal": "1.5"
}
```

* The token address was lowercased; every quantity stays a string.
* `evidenceDigest` covers the whole observation; `contentDigest` covers only `result`, `subject` and
  `payload`, so two readings of the same thing share it whatever their IDs, sources and times.
* `balanceDecimal` is exact: `1500000` atomic units at 6 decimals is `1.5`, computed with integers and
  never rounded.
* Had the reading come back empty (`"result": "NO_RESULT"`, no balance fields), the payload would be
  `{}` and `balanceDecimal` would be `null`. No result is never zero.

## 3. Evaluate a bundle and assess readiness

An evidence **bundle** gathers sources, observations and the assertions they support. The engine
publishes complete synthetic bundles as resources, each with the exact tool call to make. This short
script reads one and makes that call. Save it as `quickstart.mjs` in the `walletwall-copilot`
directory:

```js quickstart.mjs theme={null}
// quickstart.mjs: replay one of WalletWall's published examples through the local MCP server.
// Usage: node quickstart.mjs <path to walletwall-mcp.mjs> [example name]
import { spawn } from "node:child_process";
import { createInterface } from "node:readline";

const [serverPath, example = "vault-readiness-established"] = process.argv.slice(2);
const server = spawn(process.execPath, [serverPath], { stdio: ["pipe", "pipe", "inherit"] });

const waiting = new Map();
createInterface({ input: server.stdout }).on("line", (line) => {
  const message = JSON.parse(line);
  waiting.get(message.id)?.(message);
});
let lastId = 0;
const rpc = (method, params) =>
  new Promise((resolve) => {
    const id = ++lastId;
    waiting.set(id, resolve);
    server.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
  });

await rpc("initialize", { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "quickstart", version: "1.0.0" } });
server.stdin.write(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }) + "\n");

// 1. Read the example resource: a synthetic bundle plus the exact tool call to make with it.
const resource = await rpc("resources/read", { uri: `walletwall://examples/${example}` });
const { toolCall } = JSON.parse(resource.result.contents[0].text);

// 2. Make that call and print the structured result.
const response = await rpc("tools/call", toolCall);
console.log(JSON.stringify(response.result.structuredContent, null, 2));
server.stdin.end();
```

Run it:

```bash theme={null}
node quickstart.mjs plugin/server/walletwall-mcp.mjs
```

The default example, `vault-readiness-established`, holds two assertions: an asset identity attested by
the issuer's publication, and a balance read from chain state at a finalized block. The resource's tool
call is `assess_vault_readiness`. Result, abridged:

```json theme={null}
{
  "claimType": "VAULT_TECHNICAL_READINESS",
  "classification": "CRITERIA_MET",
  "ruleId": "wwvr.vault-technical-readiness",
  "rulesVersion": "0.1.0-draft",
  "criteria": [
    { "id": "C1", "outcome": "MET", "reason": "IDENTITY_ESTABLISHED" },
    { "id": "C2", "outcome": "MET", "reason": "BALANCE_ESTABLISHED" },
    { "id": "C3", "outcome": "MET", "reason": "SUBJECT_CONSISTENT" },
    { "id": "C4", "outcome": "MET", "reason": "DECIMALS_CONSISTENT" },
    { "id": "C5", "outcome": "MET", "reason": "NO_CONFLICT" },
    { "id": "C6", "outcome": "MET", "reason": "FRESH_OR_PINNED" }
  ],
  "supportOfInputs": "ESTABLISHED",
  "limitations": [
    "REGISTRY_VERIFIED_POINT_IN_TIME",
    "TRANSPORT_FIDELITY_NOT_VERIFIED",
    "WALLETWALL_DERIVED_NOT_UPSTREAM_AUTHORITY"
  ],
  "doesNotEstablish": [
    "investment merit",
    "solvency",
    "creditworthiness",
    "legal status",
    "regulatory compliance",
    "absence of fraud",
    "future performance"
  ]
}
```

Even a fully met result carries its limits with it:

* `TRANSPORT_FIDELITY_NOT_VERIFIED`: the engine cannot check that a chain reading was faithfully
  retrieved. It evaluates evidence as presented.
* `WALLETWALL_DERIVED_NOT_UPSTREAM_AUTHORITY`: the classification is WalletWall's rule applied to the
  inputs. It is not a statement by the issuer or the chain.
* `doesNotEstablish` lists what technical readiness never implies.

To see the per-assertion evaluation instead, replay an example whose call is `inspect_evidence`:

```bash theme={null}
node quickstart.mjs plugin/server/walletwall-mcp.mjs balance-established
```

The balance assertion comes back `ESTABLISHED`, with freshness `PINNED` (it is about a specific block),
finality `FINALIZED`, and authority `canonical-chain-state` satisfied.

## 4. Watch it fail closed

Now replay the example in which the asset's identity was only read from chain state and no issuer
attestation exists:

```bash theme={null}
node quickstart.mjs plugin/server/walletwall-mcp.mjs vault-readiness-not-established
```

```json theme={null}
{
  "classification": "NOT_ESTABLISHED",
  "criteria": [
    { "id": "C1", "outcome": "INDETERMINATE", "reason": "IDENTITY_PARTIAL" },
    { "id": "C2", "outcome": "MET", "reason": "BALANCE_ESTABLISHED" },
    { "id": "C3", "outcome": "MET", "reason": "SUBJECT_CONSISTENT" },
    { "id": "C4", "outcome": "MET", "reason": "DECIMALS_CONSISTENT" },
    { "id": "C5", "outcome": "MET", "reason": "NO_CONFLICT" },
    { "id": "C6", "outcome": "MET", "reason": "FRESH_OR_PINNED" }
  ],
  "supportOfInputs": "PARTIAL",
  "limitations": [
    "INSUFFICIENT_INDEPENDENT_CORROBORATION",
    "NO_AUTHORITATIVE_OBSERVATION",
    "REGISTRY_VERIFIED_POINT_IN_TIME",
    "SYMBOL_NOT_AUTHORITY",
    "TRANSPORT_FIDELITY_NOT_VERIFIED",
    "WALLETWALL_DERIVED_NOT_UPSTREAM_AUTHORITY"
  ]
}
```

The bundle is complete and well formed; the **evidence** is incomplete, and WalletWall keeps it that
way. One criterion cannot be decided, so the classification is `NOT_ESTABLISHED`: not "not ready", and
not a guess. The example resource also names the smallest measurement that could change the outcome:

> An AUTHORITY\_ATTESTED observation of the identity from an ISSUER\_PUBLICATION source whose
> authorityId equals the registry authorityId for the deployment.

## 5. Try it from your AI client

Once the server is connected to your client ([Install & Connect](https://docs.walletwall.org/mcp/install.md)), ask in plain
language. For example:

```text theme={null}
Read walletwall://examples/vault-readiness-not-established, make the tool call it
describes, and report the classification exactly, with every criterion, every
limitation and the missing measurement. Do not infer missing evidence.
```

```text theme={null}
Audit this WalletWall evidence bundle for freshness, authority, conflicts,
limitations, and invariant violations. Identify the smallest next measurement
that would resolve each material unknown.
```

> [!WARNING]
>
> Use synthetic or otherwise non-sensitive evidence while you evaluate WalletWall. Prompts, tool inputs
> and tool outputs pass through your AI client and its model provider under their own policies. Never
> put private keys, seed phrases or signatures into a prompt or a bundle; WalletWall never needs them.

## Next steps

> [card] [Tools](https://docs.walletwall.org/mcp/tools.md)
>
> Inputs, outputs and refusals for all six tools.

> [card] [Evidence Model (WWEP)](https://docs.walletwall.org/mcp/evidence-model.md)
>
> Why the same evidence can be ESTABLISHED, STALE or PARTIAL.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.