# Architecture overview
Source: https://docs.compassguard.xyz/public-docs/architecture

How Compass Guard checks agent tool calls before Solana execution.

# Architecture overview

Compass is an execution gateway. The agent connects to Compass, not directly to execution tools. Compass evaluates every sensitive call before forwarding it.

```text theme={null}
AI agent / MCP client
  ↓
Compass MCP Guard
  ↓
Tool classification
  ↓
Policy + risk checks
  ↓
Simulation / decoding when available
  ↓
Allow, review, or deny
  ↓
Downstream Solana tool / signer
  ↓
Audit log
```

## Core components

| Component     | Role                                                                      |
| ------------- | ------------------------------------------------------------------------- |
| MCP guard     | Proxies downstream MCP tools and guards `tools/call` requests.            |
| Hosted API    | Accepts verification requests from custom integrations.                   |
| Policy engine | Applies limits, allowlists, denylists, and fail-closed defaults.          |
| Risk checks   | Flags suspicious recipients, risky tools, or unsafe execution conditions. |
| Audit trail   | Stores decisions with reasons and correlation IDs.                        |

## Current public surface

* `GET /health` — open liveness check.
* `POST /signup` — mints an email-scoped API key.
* `POST /v1/verify` — returns the live guard verdict.
* `POST /v1/verify/confirm` — optional post-execution confirmation path; decoding is still being expanded.

## Design stance

Compass fails closed for unknown mutating tools. If the system cannot classify an action safely, the answer is `deny` or `review`, not silent execution.


# Onboarding skill
Source: https://docs.compassguard.xyz/public-docs/onboarding-skill

How to use the public Compass Guard agent guide.

# Onboarding skill

The onboarding skill is a shareable guide for an assistant or human developer to test Compass Guard without reading this repo.

Use it when someone asks to:

* try Compass Guard;
* get a live `allow`, `review`, or `deny` verdict;
* wire the guard into an MCP client;
* understand common hosted API mistakes.

## Public skill URL

```text theme={null}
https://api.compassguard.xyz/skill-onboard.md
```

Prompt example:

```text theme={null}
Use https://api.compassguard.xyz/skill-onboard.md to guide me through testing Compass Guard.
```

## What the skill enforces

| Rule                      | Why it matters                                                       |
| ------------------------- | -------------------------------------------------------------------- |
| Never invent API keys     | Fake keys only return `401`; users should mint one with `/signup`.   |
| Use recognized tool names | Unknown mutating tools are denied by default.                        |
| Inspect real JSON         | Verdicts and reasons must come from the API, not guesswork.          |
| Treat `review` as a hold  | In the advisory tier, `review` means the agent should not auto-sign. |

## Source of truth

The raw skill remains in `public/skill-onboard.md` so existing `/skill-onboard.md` and `/docs/onboarding` routes continue to work. This Mintlify page is the public docs wrapper around that skill.


# Compass Guard
Source: https://docs.compassguard.xyz/public-docs/overview

Execution firewall for AI agents operating on Solana.

# Compass Guard

Compass Guard sits between an AI agent and Solana execution tools. Before a transfer, swap, or other sensitive action runs, Compass classifies the tool call, applies policy, returns `allow`, `review`, or `deny`, and records the decision for audit.

## What it protects

| Risk                           | Compass response         |
| ------------------------------ | ------------------------ |
| Unknown recipient              | Hold for human review    |
| Amount above policy            | Hold for human review    |
| Unknown mutating tool          | Deny by default          |
| Denylisted or dangerous action | Deny with a clear reason |

## Ways to use it

1. **MCP proxy** — place Compass in front of an existing Solana MCP server so agent tool calls are checked before execution.
2. **Hosted API** — call `POST /v1/verify` directly from a backend, wallet flow, or integration.
3. **Future signer gateway** — move from advisory checks toward validation, approval, and signing control.

## What it is not

Compass is not a wallet, custodian, chatbot, or identity layer. Wallets control signing. Compass controls whether an agent action should be allowed to reach execution.

## Next step

Start with the [quickstart](/public-docs/quickstart) to mint an API key and get a live verdict.


# Hosted quickstart
Source: https://docs.compassguard.xyz/public-docs/quickstart

Get an API key, call /v1/verify, and wire the MCP guard into Claude Code.

# Hosted quickstart

Use this page to get one real Compass Guard verdict from the hosted API.

<Note>
  The public docs live at `https://docs.compassguard.xyz`. The hosted API examples below use the current API base URL: `https://api.compassguard.xyz`.
</Note>

## 1. Check health

```sh theme={null}
curl -s https://api.compassguard.xyz/health
```

Expected: `{"ok":true,"service":"compass-hosted-guard",...}`.

## 2. Mint an API key

```sh theme={null}
curl -sX POST https://api.compassguard.xyz/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'
# → {"email":"you@example.com","apiKey":"compass_…"}

export COMPASS_HOSTED_API_KEY='compass_…'
```

## 3. Ask for a verdict

```sh theme={null}
curl -sX POST https://api.compassguard.xyz/v1/verify \
  -H "Authorization: Bearer $COMPASS_HOSTED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toolName": "transfer",
    "intent": { "kind": "transfer" },
    "arguments": {
      "recipient": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      "amountUsd": 5,
      "recipientKnown": false
    }
  }'
```

Unknown recipients return `review`:

```json theme={null}
{
  "correlationId": "…",
  "decision": "review",
  "riskLevel": "medium",
  "reasons": ["TRANSFER_UNKNOWN_RECIPIENT"],
  "humanExplanation": "Recipient is not on the allowlist."
}
```

Set `recipientKnown` to `true` and keep `amountUsd <= 10` to demo an `allow` verdict.

## 4. Optional: add the MCP proxy

```sh theme={null}
claude mcp add compass \
  --env COMPASS_HYBRID_GUARD_ENABLED=true \
  --env COMPASS_HOSTED_API_URL=https://api.compassguard.xyz \
  --env COMPASS_HOSTED_API_KEY=$COMPASS_HOSTED_API_KEY \
  -- npx -y @ramadan04/compass-mcp-guard \
     --downstream-name solana-tools \
     --downstream-command npx \
     --downstream-args-json '["@your-downstream/mcp-server"]'
```

Replace `@your-downstream/mcp-server` with the Solana MCP server you want protected.

## Reference

| Endpoint                  | Auth   | Purpose                              |
| ------------------------- | ------ | ------------------------------------ |
| `GET /health`             | none   | Liveness                             |
| `POST /signup`            | none   | Mint an email-scoped API key         |
| `POST /v1/verify`         | bearer | Decision on an intended tool call    |
| `POST /v1/verify/confirm` | bearer | Optional post-execution confirmation |