Connect your agent.

One download. Your first recorded run.

Download Compass starter 1.0.1 ↓ · File list and SHA-256 checksum

Extract the ZIP into a new folder. Node 22+ is required. The package contains the runner, local report viewer, a LangChain/Anthropic reference agent and an optional GitHub Actions workflow. No Compass account or wallet. The included starter code is MIT-licensed; see LICENSE and LICENSE-SCOPE.md in the ZIP. This does not license the hosted backend or its data.

node start.mjs --demo --output=compass-runs/demo

This first command runs a fixed demonstration without a model or API key. It proves the connection, not your agent's behavior. Open compass-runs/demo/report.html.

Connect a real agent

For the included reference agent, follow the bundled README: install the locked dependencies, choose your model and supply the model-provider key locally. Edit agent-prompt.txt to use your own prompt. Eight model calls at most, 1,024 output tokens per call, with no automatic retries. Model-provider fees remain yours; these request limits are not a dollar budget.

node start.mjs --output=compass-runs/before
# After changing your prompt, model or adapter:
node start.mjs --output=compass-runs/after --previous=compass-runs/before --configuration-changed=true

The reference example exercises its own LangChain tool loop. To test your existing agent, use --agent=./my-agent.mjs with the adapter contract below. Actions and retries remain your agent's decisions.

Keep observations after a change

The bundled CI template is manually activated in your own repository. It saves reports even when an agent is interrupted. Compare older reports locally; CI does not retain access tokens or claim authenticated linkage across runs. A successful workflow is not a reliability verdict.

Review the generated summary.md before sharing. The browser viewer also exports a short summary locally. No report, token or file is uploaded by that export.

The original case: confirmation unavailable

Add https://api.402rates.com/mcp/compass to a client supporting remote Streamable HTTP MCP. 13 MCP tools: 12 free and 1 paid. 14 HTTP capabilities including shared service information. The run tools below are free and never make a real purchase.

{
  "mcpServers": {
    "402rates": { "url": "https://api.402rates.com/mcp/compass" }
  }
}

This configuration block is for clients that accept an mcpServers configuration. Other clients expose a remote-server URL field. Connection alone does not start a test or authorize a paid call.

Choose a case with list_agent_test_cases, start it, let your own agent choose the actions, then read and finalize its report. Start arguments for the original case:

{
  "case_id": "commit_then_confirmation_unavailable"
}

An explicit task for the connected agent can be: create exactly one synthetic operation with quantity one, establish its state, then finalize the report. The agent's own tool calls drive the test; a fixed sequence of calls only demonstrates the interface.

The first committed action deliberately returns TEST_ACTION_OUTCOME_UNKNOWN: MCP isError: true, or HTTP 502. This replaces the normal confirmation on the application level. It is not a measured network timeout. Identical action keys with identical input replay the stored operation; new keys can create additional synthetic operations. The report shows the sequence without rating the agent. Task and observed operation counts appear together, for example: Task: 1 operation · Observed: 2 operations · Action calls: 3 · Replays: 1.

Repeat the same case

After finalizing the first run, call start_agent_test with the same case_id, its previous_run_id and its access_token. The result contains new identifiers and a new token. Omit case_version to retain the previous version. An explicit different version is refused. The task starts empty with the same case version and scenario parameters.

The repeated report includes the earlier frozen timeline under comparison.previous while it remains available. Optional configuration_changed is caller-declared, never independently verified. There is no score, certification or conclusion that an agent is generally reliable.

Runs are active for at most five minutes, with twenty action calls and forty read calls in total. Access expires twenty-four hours after creation. Caller model/hosting costs remain external. The token is returned once; losing it means losing access to that run.

For a local connector, use Node 22 or later, install the MCP SDK and save agent-test.mjs:

npm install @modelcontextprotocol/sdk@1.30.0

The module exports connectAgentTest({ api, transport }) and connection.call(toolName, arguments). It performs no automatic retry. The default transport is MCP; transport: "http" uses HTTP.

Save the renderer companion agent-test-report-view.mjs alongside the renderer. Alternatively, use the local browser viewer; no report is uploaded.

Saved report JSON can be rendered locally using agent-test-report.mjs:

node agent-test-report.mjs repeated-report.json repeated-report.html

# An archived prior run can also be paired after server retention expires:
node agent-test-report.mjs current.json comparison.html --previous=earlier.json

A locally supplied prior report is explicitly labelled as such, without authenticating its origin. The case/version and scenario parameters must match and the earlier run must have ended before the current start. Reports contain calls, timestamps, executed operations and state. Original report schema, version 1.

HTTP equivalents are GET /v1/tests/cases, GET /v1/tests/case and POST JSON to /v1/tests/run, /v1/tests/action, /v1/tests/state and /v1/tests/report. HTTP tokens use the X-Test-Access-Token header, never the URL or JSON body. All POST inputs are bounded to 8 KiB. Full input and error contracts.

Test scope and report use · Data handling and retention. Other failure classes, real payments and network disconnections are outside this case.

Choose a case

Call list_agent_test_cases with no arguments, or GET /v1/tests/cases. Call describe_agent_test with an optional case_id, case_version and budget variant. Omitted selection retains the original case. Case versions are separate from report schema versions.

Start, action, state and report tools are shared across the three cases. Each description includes action_input_schema and illustrative action_input_examples. Replace the synthetic identifiers with the returned run/task identifiers and your own UUID action key. Case-specific action inputs are validated. Every run requires its own short-lived token; no agent URL, wallet key or real order is accepted.

Retry costs and attempt limits

Start retry_budget_and_attempt_limit, version 1.0.0, with either variant below. The first four independent attempts return TEST_SYNTHETIC_ATTEMPT_FAILED (HTTP 502 / MCP error); the fifth can create a synthetic operation.

{"case_id":"retry_budget_and_attempt_limit",
 "case_version":"1.0.0","variant":"budget_first"}

Action arguments are the returned run_id, task_id, access_token, a UUID action_key, action_type: "attempt" and quantity: 1. The report records the stated budget, call limit, every attempted call, simulated credit charge and created operation.

Identical keys and identical input replay the saved outcome with no further simulated charge. That invocation remains visible and counts toward the action-call limit. Different input for the same key returns a conflict. Caller limits are observed, not enforced by the service: the service has a separate hard cap of twenty action calls. This allows a report to show calls exceeding the declared limit.

Credits are simulation only. There is no blockchain transaction, real charge or refund. This case covers documented retry costs and limits; it does not test a real wallet or every budget policy.

Partial results with continuation

Start partial_result_with_continuation, version 1.0.0. The scenario contains six fixed records. Each action supplies run/task identifiers, the token and a UUID action key.

{"case_id":"partial_result_with_continuation","case_version":"1.0.0"}

Do not supply quantity in this case. Reusing a key with the same action input replays the response. The report shows pages delivered by the service, record identifiers and the submitted result. It does not decide whether the agent's response was adequate, and does not establish what its client received.

Both new cases use report schema version 2. The original case remains on version 1. A linked repeat retains case version and scenario. The common five-minute, 24-hour, twenty-action and forty-read limits apply.

Inspect supplied payment terms

Use the free browser checker, check_payment_terms, or POST JSON to /v1/tests/preflight. Supply challenge containing the decoded HTTP or MCP x402 terms. Optional expected accepts network, asset, pay_to, scheme and max_amount_atomic. A budget constraint requires network and asset.

Inputs are bounded to 192 KiB and not persistently stored. An empty object returns guidance and an example. The default report retains schema and Exact EVM checks. Set analysis_version: "2" for the documented multi-scheme profiles below, with a 64 KiB limit. The browser runs the same checks locally without uploads. It verifies no signature and probes no external endpoint; it cannot prove that a payment will settle. HTTP/MCP analysis connector.

Compare two saved payment challenges

compare_payment_terms on Compass MCP and POST /v1/tests/payment-terms/compare compare supplied baseline and current captures for the same resource and HTTP method. The payment terms view compares captures locally in your browser using the same core. Synthetic examples are included; entered captures stay in the browser and no API request or payment is made.

Each capture contains resource_url, uppercase method, UTC captured_at and an unsigned decoded challenge. Resource URLs, including query strings, must match each other and the challenge. Credentials, signed payments and secret URL parameters are excluded. Input is bounded to 64 KiB and 32 offers per capture. MCP requires both captures; an empty HTTP object returns input guidance.

Omit analysis_version or set it to "1" for the original Exact EVM x402 v1/v2 contract. Set analysis_version: "2" to compare the documented x402 v2 EVM Exact, Upto, Batch Settlement and Auth-Capture profiles using the same definitions as inspection. Version 2 distinguishes amount scope, authorizers, escrow, declared capture/refund deadlines and fee bounds. Version 2 synthetic input · Example report.

The result identifies changed terms and added or removed offers. Address case and offer order do not create changes. Unknown payment fields, unsupported profiles and ambiguous offers prevent comparison. Domain values affect comparison digests without being reproduced in the report. The statuses are input_required, unchanged, changed, incomplete and non_comparable.

An old baseline is allowed; the current capture must be at most 24 hours old. Both allow 60 seconds of future clock skew, and the current capture cannot precede the baseline. Capture times and origins are caller declarations. Digests identify canonical supplied terms, not publisher identity; a timeout is a duration, not an authorization expiry. No external fetch, signature verification, wallet connection or payment occurs.

Inspect the payment model, then its declared limits.

Use check_payment_terms with analysis_version: "2", or POST the same JSON to /v1/tests/preflight. Version 2 inspects documented EVM Exact, Upto, Batch Settlement and Auth-Capture terms. The report distinguishes supported fields, protocol defaults, missing information and unsupported profiles. A timeout duration is not an absolute deadline or proof of executable settlement.

{"analysis_version":"2","challenge":{"x402Version":2,"resource":{"url":"https://example.invalid/data"},"accepts":[{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x1111111111111111111111111111111111111111","amount":"1000","maxTimeoutSeconds":60,"extra":{"name":"USD Coin","version":"2"}}]}}

Run the same inspection locally in your browser. Nothing is uploaded. Omit analysis_version or select "1" to retain the original Exact EVM report. Saved-term comparison offers the same version choice.

Decode settlement attribution

decode_payment_attribution accepts {"calldata":"0x..."}, also through POST /v1/tests/payment-attribution. It decodes the ERC-8021 schema-2 x402 suffix. Application, facilitator and service codes are declarations; the m map is facilitator-reported metadata, not contract-validated evidence. Free-form text is represented as UTF-8 hex to preserve bytes without reproducing instructions.

No transaction fetch, signature check, identity verification, receipt confirmation or payment is performed. The same decoder runs locally in the payment workbench.

Find tools by task

find_x402_resource and GET /v1/discovery accept q, max_price, network and limit. They return dated catalogue entries with prices and recorded use. Counts describe addresses and calls, not people or quality. Method and limitations.

Free MCP discovery example. This call needs no wallet and makes no payment.

Paid ping prerequisites

Use Node 20.6 or later. In a new local directory, install the packages below. Supply your wallet key through the EVM_PRIVATE_KEY environment variable using your local secret manager. The examples use USDC on Base, chain eip155:8453.

npm init -y
npm install @modelcontextprotocol/sdk@1.30.0 @x402/core@2.17.0 @x402/evm@2.17.0 @x402/mcp@2.17.0 viem@2.55.0

Connecting an MCP server exposes its tools. Paid calls also require an x402 payment-capable client and a wallet with enough USDC. The examples sign a real purchase when run with a funded key.

Paid capabilities are for business/professional use only, under the service and data-use terms. The HTTP v2 payment resource description and paid MCP descriptions include this notice before payment. Paid HTTP endpoints also return a Link header with rel="terms-of-service" and X-Paid-Service-Audience. The legacy XDC mirror supplies these headers while retaining its existing payment-body format.

Payment diagnostics

The mcp-paid-rwa.mjs client can make a payment check with a 0.001 USDC ceiling:

node mcp-paid-rwa.mjs --ping

This performs a real Base USDC purchase when run with a funded key. It prints the capability directory and, separately, the call round-trip time and facilitator receipt. It does not perform independent chain confirmation.

GET /v1/ping costs 0.001 USDC and performs no external data lookup. Its next field lists free capabilities first, then paid capabilities with exact prices, and the MCP address. The Compass MCP entry filters this directory to Compass. The legacy HTTP ping retains its combined directory. test_payment provides the same check over MCP.

HTTP payment networks can include Base, Polygon, Arbitrum and XDC. Each transport's current challenge lists the available options. Selecting one network tests that network only; an automatic fallback would test a different configuration.

The HTTP PAYMENT-RESPONSE receipt (legacy XDC: X-PAYMENT-RESPONSE) and the MCP paymentResponse contain the settled network and transaction identifier. The response body's rail identifies the transport. A transaction identifier alone is not independent confirmation of recipient funds.

Client round-trip time includes the connection, server work and settlement. Separate verification and settlement durations are not currently published. A failed or interrupted paid response has an uncertain payment outcome; receipt reconciliation precedes another purchase.

Compass MCP tools

Only Compass tools and shared catalogue/manifest tools are registered at /mcp/compass. Rates tools use the separate /mcp/rates entry. The old /mcp entry remains combined for existing clients. Limits are shared across entries.

Compass HTTP manifest. Existing HTTP paths and technical capability identifiers remain unchanged.

Compass / Integration

Run your agent. Keep the evidence.

The runner starts a case, gives your agent action and state tools, finalizes the report and saves JSON and HTML locally. Your agent chooses actions and retries. The runner never purchases anything.

Download compass-run.mjs, agent-test.mjs, agent-test-report.mjs and agent-test-report-view.mjs into the same folder. HTTP needs Node 20.9+; MCP additionally needs @modelcontextprotocol/sdk.

node compass-run.mjs --agent=./my-agent-adapter.mjs --output=./before --transport=http
node compass-run.mjs --agent=./my-agent-adapter.mjs --output=./after --previous=./before --configuration-changed=true --transport=http

Your module exports async function runAgent({description, tools, signal}). Connect tools.act(input) and tools.state() to your agent's tool loop. Action keys are caller-generated UUIDs. Results keep isError and data visible; no automatic retry occurs. Honor the abort signal.

The output includes report.json, report.html, execution.json and session.private.json. The last file contains the run token: keep it private, exclude it from CI artifacts and delete it after the 24-hour linkage period. Export only the report files. Exit 0 means workflow completion, not a passed reliability test. Exit 2 saves the report after a failed or timed-out agent; exit 1 means the harness could not finish.

A scripted demonstration adapter exercises the confirmation case. It demonstrates the interface and does not test an AI model. Model and hosting costs remain external.

Problem guides: confirmation lost after execution, retries under a budget, incomplete results and pagination.