Test mode

Last updated Jun 14, 2026

Test mode is a completely isolated universe — separate data, separate signing keys, separate event streams. Nothing in test mode can leak into production.

Getting a test key

sk_test_matter_example_k2pqG7hN8mZxVb4R
pk_test_matter_example_G4xN9QrPm2vB7kA

Grab them at https://mattermode.com/dashboard/keys. Test keys are free and there is no limit on how many entities you can form or dissolve.

Accelerated timelines via X-Matter-Test-Speed

Live-mode formation takes 2–3 weeks; dissolution can run months. In test mode, control the pace:

curl -X POST https://api.mattermode.com/v1/entities \
  -H "X-Matter-Test-Speed: instant" \
  -H "Authorization: Bearer $MATTER_TEST_KEY" \
  ...

Or set it as a default on the key via the dashboard.

Distinct signing-key hierarchy

Live mode and test mode use different signing keys for IncorporatorReceipt, document proof, and webhook signatures. A live-mode verifier never accepts a test-mode signature and vice versa. The public key bundle at https://mattermode.com/.well-known/matter-keys.json distinguishes the two sets clearly. Test-mode documents additionally carry a visible [TEST MODE] watermark on the rendered PDF.

Test strategy: unit / integration / e2e

Use ?dry_run=true for tests that assert response shape without creating fixture entities — see Dry run.

Idempotency-Key strategy in tests

Prefer deterministic keys derived from the test name + input hash:

import hashlib
key = hashlib.sha256(f"{test_name}:{input_hash}".encode()).hexdigest()[:32]

A repeated test run reuses the key and returns the memoized response — you verify replay semantics work and you don't accumulate fixture garbage.

Webhook testing

Two options:

1. Dashboard "Send test event": emits a webhook_endpoint.test_delivered event with a canned payload. Cheap and fast; great for verifying signature verification.
2. Live test-mode flows: create a webhook endpoint with a test-mode key, then exercise actual flows. Events fire just like live mode, signed with a distinct test-mode key.

For local development, tunnel with ngrok or Cloudflare Tunnel and register the tunnel URL as your webhook endpoint.

The fixture dataset

sk_test_eval_... keys expose a versioned, immutable fixture dataset:

• Two fully-formed Delaware C-Corps (Waypoint Systems, Inc.; Corestar Enterprises).
• An 8-entity venture-studio portfolio (Studio42).
• A CorporateTransaction in definitive stage spanning two entities.
• An entity mid-dissolution (winding_down).
• Complete operational history — stakeholders, cap tables, grants, valuations, filings, audit.

The fixture is the same dataset MCP evaluations run against. Answers are stable across releases.

Don't put real data in test mode

Test mode is a live data store — not a local sandbox. Don't put sensitive PII there. Use 00-0000000 for EINs, @example.com for emails, placeholder names.

CI recommendations

• Pin a single dated Matter-Version per CI branch. Bump in a PR.
• Use separate sk_test_… keys per CI environment (main CI, nightly, PR previews).
• Never commit a key — even a test key leaks account identity.

Promoting from test to live

There is no "promotion." When you're ready, switch the key in your environment to sk_live_… and issue your first real POST /v1/entities. Matter does not copy test data into live — legally distinct universes, always.

Related

• Test clocks — manipulate test-mode time.
• Idempotency — request replay semantics.
• Dry run — preview without side effects.