Skip to main content
Start by separating two kinds of outcome, because they need different fixes:
  • An error (isError: true, or a JSON-RPC error) means the server could not accept your request: a tool name, a resource URI or an input it does not recognise.
  • A weak result (NOT_ESTABLISHED, UNKNOWN, PARTIAL, STALE, CONFLICTING) is a successful answer about your evidence. It is not a bug, and it should not be retried away.

Discovery and setup

  1. Start a new session. A session that was open during the install does not gain the plugin.
  2. Run copilot plugin list --json and check that walletwall from marketplace walletwall is listed and enabled.
  3. Run copilot mcp list and check that walletwall appears among the plugin servers as a local server.
  4. Check that node --version works in the environment Copilot runs in, and reports 22.18 or newer.
  5. Install with the current names: the marketplace and the plugin are both walletwall, so the command is copilot plugin install walletwall@walletwall. Historical install records in the repository mention an earlier marketplace name; do not copy it.
Run claude --plugin-dir . from inside the walletwall-claude clone, or pass the clone’s path explicitly. The directory must contain .claude-plugin/plugin.json, .mcp.json, server/walletwall-mcp.mjs and node_modules/ (the server loads the SDK and zod from it). Check that node on your PATH is 22.18 or newer.
  • The command must be node, and its single argument the absolute path to walletwall-mcp.mjs. Relative paths resolve against whatever directory your client starts in.
  • In JSON on Windows, escape backslashes (C:\\Users\\...) or use forward slashes.
  • Add no arguments and no environment variables: the server ignores both, and a wrapper script that prints anything to standard output corrupts the stdio protocol.
  • If the process dies, its only message on standard error is the fixed line walletwall-mcp: fatal error. Run the same command by hand to see whether node itself reports a problem.
That is expected. It is a stdio server: it waits for JSON-RPC on standard input and writes nothing until it receives a request. It exits when its input closes, or press Ctrl+C. To exchange messages by hand, use the one-liners in the Quickstart.
Node.js 22.18 or newer. The bundled server (walletwall-mcp.mjs) needs no npm install. The loopback HTTP adapter runs the repository’s TypeScript source directly, so it additionally needs npm ci in the walletwall-copilot checkout, and Node.js 22.18 or newer to run .ts files.

Names and URIs

Tool names are exact and in snake case: resolve_asset, normalize_observation, inspect_evidence, check_invariants, trace_provenance, assess_vault_readiness. GitHub Copilot displays them with a walletwall- prefix, but the protocol name has none. There is no tool for signing, sending, approving, swapping or fetching data, and asking for one returns UNKNOWN_TOOL.
Resource URIs are exact strings: walletwall://schemas/claims, not walletwall://schema/claims. The eleven URIs are listed on Resources. Asking for resource templates or for prompts returns Method not found, because the server offers neither; that is expected.

Rejected input

The issues list gives the path and the issue code of each problem, never the value you sent:Path segments outside WalletWall’s vocabulary appear as *, and array positions as #. Compare your input with walletwall://schemas/evidence and walletwall://schemas/claims. A second message, Input structure is not permitted. with no issues, means the input is nested more than 12 levels deep, holds more than 20,000 values, or has a constructor or prototype key.
normalize_observation refuses a balanceAtomic larger than 2²⁵⁶ − 1, a decimals greater than 36, and a VALUE observation without both balanceAtomic and decimals. A spelling that is not a canonical atomic-unit decimal string at all (a sign, a decimal point, a leading zero) is rejected earlier, as INVALID_INPUT.
Use UTC with a Z suffix, for example 2026-10-23T12:00:30Z, optionally with milliseconds. Offsets such as +02:00 and impossible dates are rejected.

Weak or unexpected results

The bundle passed the schema, but the assertion’s subject or value does not match its claim type’s contract or its observation. Read the assertion’s diagnostics: they name the record checked and its required, missing, invalid, unexpected (*) and mismatched keys. Rebuild the bundle from walletwall://schemas/claims, and treat the rebuilt bundle as new input, not as the original.
The assertion cites no observations and has no derivation. Add the observations it rests on and list their IDs in observationIds. If the assertion also carries a value, check_invariants reports INV-01 (NO_SOURCE_PRESENTED_AS_FACT): with no source, the value must be null.
Every observation behind the claim returned NO_RESULT or ERROR. That is the correct way to record a failed or empty lookup from your own provider: it is unknown, not zero. Keep the assertion’s value null; keeping a value reports INV-01 (NO_RESULT_AS_VALUE), or INV-04 / INV-05 for a zero or false value.
Check the limitations. NO_AUTHORITATIVE_OBSERVATION means no observation came from an origin that may establish the claim: an asset’s identity, for example, needs an AUTHORITY_ATTESTED observation from an ISSUER_PUBLICATION source whose authorityId matches the registry. A registry match from resolve_asset is PARTIAL at best. INSUFFICIENT_INDEPENDENT_CORROBORATION means fewer independence groups support the claim than its policy requires: a single source, or several sources in one group.
A balance read at an unfinalized block (NOT_FINALIZED), or with unknown finality (FINALITY_UNKNOWN), cannot be ESTABLISHED. Use a reading taken at a finalized block.
Freshness is judged against the evaluatedAt you send. A CURRENT claim older than its policy’s maximum age (30 days for asset identity, 120 seconds for a current balance, 300 seconds for a price) is STALE. An observation timestamped after evaluatedAt gives UNKNOWN_FRESHNESS with OBSERVATION_FROM_FUTURE: check the clock and the time zone of the tooling that produced the reading.
Observations or assertions about the same claim disagree. WalletWall will not choose between them. Find out why your sources disagree and gather better evidence; the conflict stays visible until the evidence changes.
Read the criteria. INDETERMINATE criteria give NOT_ESTABLISHED; any NOT_MET gives CRITERIA_NOT_MET. If every criterion says REQUIRED_INPUT_ASSERTION_MISSING_OR_WRONG_CLAIM_TYPE, identityAssertionId and balanceAssertionId are missing or swapped: the first must name an ASSET_IDENTITY assertion and the second a TOKEN_BALANCE_AT_BLOCK assertion.
Conflict grouping and supersession compare subjects exactly, so 0xA0b8… and 0xa0b8… are two subjects. Use lowercase addresses throughout; normalize_observation lowercases them for you.
WalletWall MCP never calls your provider, so provider and network failures happen in your own retrieval tooling, before WalletWall is involved. Record a failed lookup as an observation with NO_RESULT or ERROR rather than leaving it out or writing zero, and record how each reading arrived in transport.retrievedVia.

Loopback HTTP adapter

Check the line the adapter printed at start-up: it names the actual address and port. Then:
{"status":"ok"} means the adapter is up. If the adapter exited immediately with walletwall-mcp-http: fatal error, the port may be in use, the port value may be invalid, or --host was given something other than 127.0.0.1 or 0.0.0.0.
If /health answers correctly but MCP calls fail with errors about an invalid chunked response, something between the client and the adapter is rewriting local HTTP traffic. Security software that inspects HTTP connections can do this even on 127.0.0.1. Try from a different environment (for example WSL on Windows), or exclude the loopback adapter from that inspection.

WallPrint resolution

No record with that ID is published at the resolver. This is not a judgement on the record: it was never published there, or the reference was copied wrongly. Published records are listed at https://walletwall.org/wallprint/index.json.
  • DIGEST_MISMATCH: the record is published under other bytes than the digest in your reference. Every digest is printed, and the published version is offered as a link. It is an integrity finding, not an accusation of forgery.
  • MALFORMED_REFERENCE: the reference text was altered or truncated. References have exactly one valid spelling; copy them exactly.
  • UNSUPPORTED_VERSION: only reference and WallPrint version 0.1 resolve today.
The page could not read the store. It says nothing about the record. Reload, and check that the page is served from walletwall.org.

Still stuck?

Open an issue on Wallet-Wall/walletwall-copilot with the tool or resource involved, the error code and issues, and the output of walletwall://conformance/version. Use synthetic values only, and never include a real wallet address, key or credential. For security problems, follow Privacy & Security instead.