{
  "openapi": "3.1.0",
  "info": {
    "title": "Swaps Wallet Screen connector for Claude (MCP)",
    "version": "1.0.0",
    "description": "The connector is a signed-in MCP server for Claude: one public address on a network the person named, checked from their Swaps account. Sign-in is OAuth 2.1 with PKCE through Supabase Auth (dynamic client registration). `initialize`, `tools/list` and `resources/*` need no token; `tools/call` needs one. Two tools: `screen_wallet_address` (model-visible, read-only, spends nothing, returns the priced card) and `run_wallet_screen` (app-only, called by the card's button, sends `expected_charge`). Pricing: the first check on a Swaps account is free, then 1 credit ($1); a saved report of the last 30 days opens free; a `no_credits` card links to `https://www.swaps.app/dashboard/settings/credits`. Contract tests: `api/mcp-claude.test.ts`.",
    "x-swaps-status": "available"
  },
  "servers": [
    {
      "url": "https://www.swaps.app"
    }
  ],
  "paths": {
    "/api/mcp-claude": {
      "post": {
        "operationId": "claudeConnectorMcpPost",
        "summary": "Send a Claude connector MCP message",
        "description": "JSON-RPC over stateless MCP Streamable HTTP; send `application/json, text/event-stream` in Accept. One JSON-RPC request per HTTP request (a batch is 400 `batch_not_supported`). Lazy auth: a body without `tools/call` is answered without a token; a `tools/call` without a valid Supabase OAuth access token (a JWT with a `client_id` claim, verified against the project JWKS and confirmed live at `/auth/v1/oauth/userinfo`) is HTTP 401 with `WWW-Authenticate: Bearer error=\"invalid_token\", error_description=\"…\", resource_metadata=\"https://www.swaps.app/.well-known/oauth-protected-resource/api/mcp-claude\", scope=\"openid\"`. Tool outcomes, refusals included, are HTTP 200 with the card in `result.structuredContent` (see `ClaudeCheckCard`) and the address in `result._meta.walletScreen`, never in `structuredContent` or the text.",
        "security": [
          {},
          {
            "claudeOAuth": ["openid"]
          }
        ],
        "parameters": [
          {
            "in": "header",
            "name": "MCP-Protocol-Version",
            "description": "The version agreed in `initialize`.",
            "schema": {
              "type": "string"
            },
            "example": "2025-11-25"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/McpMessage"
              },
              "examples": {
                "listTools": {
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "tools/list",
                    "params": {}
                  }
                },
                "screenAddress": {
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 2,
                    "method": "tools/call",
                    "params": {
                      "name": "screen_wallet_address",
                      "arguments": {
                        "address": "0x1234567890123456789012345678901234567890",
                        "chain": "Ethereum"
                      }
                    }
                  }
                },
                "runCheck": {
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 3,
                    "method": "tools/call",
                    "params": {
                      "name": "run_wallet_screen",
                      "arguments": {
                        "address": "0x1234567890123456789012345678901234567890",
                        "chain": "Ethereum",
                        "expected_charge": "credit"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response (JSON or one server-sent event).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "202": {
            "description": "Accepted a JSON-RPC notification. The response is empty."
          },
          "400": {
            "description": "`batch_not_supported`, or an invalid JSON-RPC message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GateError"
                }
              }
            }
          },
          "401": {
            "description": "`invalid_token`: a `tools/call` without a valid, live connector token (missing, malformed, expired, wrong issuer, audience or role, no `client_id`, bad signature, or a revoked session). Re-run the OAuth flow from the `resource_metadata` URL.",
            "headers": {
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                },
                "description": "`Bearer error=\"invalid_token\", error_description=\"…\", resource_metadata=\"https://www.swaps.app/.well-known/oauth-protected-resource/api/mcp-claude\", scope=\"openid\"`"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GateError"
                }
              }
            }
          },
          "405": {
            "description": "`method_not_allowed`: POST only (OPTIONS answers 204)."
          },
          "429": {
            "description": "`rate_limit_exceeded`: too many requests that are not a tool call (`initialize`, `tools/list`, `resources/*`, notifications) from this address. A tool call over its limit gets a 200 card with reason `busy` instead.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GateError"
                }
              }
            }
          },
          "503": {
            "description": "`auth_unavailable`: the sign-in could not be checked (Auth's key set or `userinfo` unreachable, timed out, or unreadable). Not the token's fault: retry after `Retry-After` seconds; never a pass.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "example": 5
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GateError"
                }
              }
            }
          },
          "500": {
            "description": "`mcp_request_failed`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GateError"
                }
              }
            }
          }
        },
        "x-swaps-mcp-tools": [
          {
            "name": "screen_wallet_address",
            "title": "Check a public wallet address",
            "inputSchema": {
              "$ref": "#/components/schemas/ScreenWalletAddressInput"
            },
            "structuredContent": {
              "$ref": "#/components/schemas/ClaudeCheckCard"
            },
            "annotations": {
              "readOnlyHint": true,
              "destructiveHint": false,
              "openWorldHint": true
            },
            "_meta": {
              "ui": {
                "resourceUri": "ui://wallet-screen-claude/result-v6.html",
                "visibility": ["model"]
              }
            },
            "x-swaps-spends": "nothing: it reads the price (Guard `guard.preview`) and returns a `ready` card, or a refusal."
          },
          {
            "name": "run_wallet_screen",
            "title": "Run the priced check",
            "inputSchema": {
              "$ref": "#/components/schemas/RunWalletScreenInput"
            },
            "structuredContent": {
              "$ref": "#/components/schemas/ClaudeCheckCard"
            },
            "annotations": {
              "readOnlyHint": false,
              "destructiveHint": false,
              "openWorldHint": true
            },
            "_meta": {
              "ui": {
                "resourceUri": "ui://wallet-screen-claude/result-v6.html",
                "visibility": ["app"]
              }
            },
            "x-swaps-spends": "at most the price the button named (`expected_charge`): Guard `guard.search` answers 409 `price_changed` instead of charging more; a saved report of the last 30 days for this account, address and network is served free."
          }
        ],
        "x-swaps-mcp-resources": {
          "current": "ui://wallet-screen-claude/result-v6.html",
          "stillServed": [
            "ui://wallet-screen-claude/result-v5.html",
            "ui://wallet-screen-claude/result-v4.html",
            "ui://wallet-screen-claude/result-v3.html",
            "ui://wallet-screen-claude/result-v2.html",
            "ui://wallet-screen-claude/result-v1.html"
          ],
          "mimeType": "text/html;profile=mcp-app",
          "domain": "c11e3d80932b9f94647d949dc1924e54.claudemcpcontent.com"
        },
        "x-swaps-guard-answers": [
          {
            "guard": "2xx with a `flags` list, or Guard's no-activity report (`error: address_not_found`, no `flags`)",
            "card": "result"
          },
          {
            "guard": "2xx unreadable or without `flags` (and not the no-activity report); network error after the request was sent",
            "card": "refused / result_lost"
          },
          {
            "guard": "402 `insufficient_credits`",
            "card": "refused / no_credits (action `buy_credits`)"
          },
          {
            "guard": "409 `price_changed`",
            "card": "ready, with the new price and a `notice`; nothing was charged"
          },
          {
            "guard": "400 `chain_address_mismatch` (also checked locally before Guard, by Guard's own rule for the named network)",
            "card": "refused / network_mismatch"
          },
          {
            "guard": "400 `unsupported_chain`; 400 `expected_charge_required`",
            "card": "refused / unavailable"
          },
          {
            "guard": "400, any other reason",
            "card": "refused / invalid_address"
          },
          {
            "guard": "401",
            "card": "refused / signed_out"
          },
          {
            "guard": "403 `oauth_client_not_allowed`",
            "card": "refused / refused_by_swaps"
          },
          {
            "guard": "429 `client_daily_cap` from a Guard deployed before the daily cap was removed (compatibility, one release)",
            "card": "refused / busy"
          },
          {
            "guard": "other 429; 5xx; no answer to the price read",
            "card": "refused / unavailable"
          },
          {
            "guard": "429 on the price read; the connector's own per-account limit",
            "card": "refused / busy"
          }
        ]
      }
    },
    "/.well-known/oauth-protected-resource/api/mcp-claude": {
      "get": {
        "operationId": "claudeConnectorProtectedResourceMetadata",
        "summary": "Read the connector's protected resource metadata",
        "description": "RFC 9728 metadata on `www.swaps.app` only. `authorization_servers` names the Supabase Auth issuer (`…/auth/v1`), whose OAuth 2.1 server does dynamic client registration and the authorization code flow with PKCE; its consent page is `https://www.swaps.app/oauth/consent`.",
        "security": [],
        "responses": {
          "200": {
            "description": "The metadata (cached 5 minutes).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProtectedResourceMetadata"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "claudeOAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "An access token from Supabase Auth's OAuth 2.1 server (authorization code with PKCE; the client registers dynamically). Discover it from the protected resource metadata. Scope: `openid`. The token reaches only this connector's two checks and the person's own sign-in record (Supabase Auth `GET /user`, `/oauth/userinfo`). Swaps' edge functions answer it `403 oauth_client_not_allowed`, the Data API `insufficient_privilege`, and Storage and Realtime return nothing."
      }
    },
    "schemas": {
      "ClaudeChain": {
        "type": "string",
        "enum": [
          "Ethereum",
          "Base",
          "Arbitrum",
          "Polygon",
          "BNB Chain",
          "Optimism",
          "Avalanche",
          "Bitcoin",
          "Solana",
          "Tron",
          "XRP Ledger",
          "TON",
          "Cardano",
          "Cosmos"
        ],
        "description": "Blockchain network the user explicitly named or confirmed for this address."
      },
      "ScreenWalletAddressInput": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Public wallet address, preserving case."
          },
          "chain": {
            "$ref": "#/components/schemas/ClaudeChain"
          }
        },
        "required": ["address", "chain"],
        "additionalProperties": false
      },
      "RunWalletScreenInput": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Public wallet address, preserving case."
          },
          "chain": {
            "$ref": "#/components/schemas/ClaudeChain"
          },
          "expected_charge": {
            "type": "string",
            "enum": ["free", "credit"],
            "description": "The price the pressed button named: the server never charges more than this."
          }
        },
        "required": ["address", "chain", "expected_charge"],
        "additionalProperties": false
      },
      "ClaudeCheckPrice": {
        "type": "object",
        "required": ["state", "expectedCharge", "label"],
        "properties": {
          "state": {
            "type": "string",
            "enum": ["free_first", "credits", "no_credits", "cached"]
          },
          "expectedCharge": {
            "type": ["string", "null"],
            "enum": ["free", "credit", null]
          },
          "label": {
            "type": ["string", "null"],
            "description": "The button's text; null when there is no check button (no credits)."
          }
        }
      },
      "ClaudeSignal": {
        "type": "object",
        "required": ["severity", "message"],
        "properties": {
          "code": {
            "type": "string",
            "description": "Guard's flag code, when it names one."
          },
          "severity": {
            "type": "string",
            "enum": ["danger", "warning", "info"],
            "description": "Guard's high/medium/low (or danger/warning/info); an unknown severity is `warning`."
          },
          "message": {
            "type": "string",
            "maxLength": 240,
            "description": "Guard's own text (its `evidence` or `message`)."
          }
        }
      },
      "ClaudeCheckResult": {
        "type": "object",
        "required": [
          "risk",
          "riskScore",
          "sanctioned",
          "signals",
          "signalCounts",
          "assessedAt",
          "charged",
          "coverage",
          "sources",
          "sanctionsSources",
          "sanctionsFallback",
          "noActivity",
          "noActivityMessage"
        ],
        "properties": {
          "risk": {
            "type": "string",
            "enum": ["low", "medium", "high", "critical", "unknown"]
          },
          "riskScore": {
            "type": ["integer", "null"],
            "minimum": 0,
            "maximum": 100,
            "description": "Shown only with a verdict (the Wallet Screen verdict rule shared with the ChatGPT card). A risk index, not a probability of safety."
          },
          "sanctioned": {
            "type": "boolean"
          },
          "signals": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/ClaudeSignal"
            },
            "description": "Most serious first, Guard's order within a level; cut at 50."
          },
          "signalCounts": {
            "type": "object",
            "required": ["total", "danger", "warning", "info"],
            "properties": {
              "total": {
                "type": "integer"
              },
              "danger": {
                "type": "integer"
              },
              "warning": {
                "type": "integer"
              },
              "info": {
                "type": "integer"
              }
            },
            "description": "Every flag Guard sent, complete even when `signals` is cut."
          },
          "assessedAt": {
            "type": ["string", "null"]
          },
          "charged": {
            "type": ["string", "null"],
            "enum": ["free", "paid", "cached", null],
            "description": "What this press cost, as Guard's ledger answered it."
          },
          "coverage": {
            "type": "string",
            "enum": ["screened", "limited"],
            "description": "`limited` when the level is no verdict: a low risk with no GoPlus answer (every non-EVM network today), or no level. The card shows «Limited data» and «Not enough data for a verdict», with no score."
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["source", "status"],
              "properties": {
                "source": {
                  "type": "string",
                  "enum": ["goplus", "ofac", "chainalysis", "onchain", "threat_intel"]
                },
                "status": {
                  "type": "string",
                  "enum": ["checked", "unavailable", "not_supported"]
                }
              }
            }
          },
          "sanctionsSources": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": ["OFAC", "Chainalysis API", "Chainalysis Oracle"]
            }
          },
          "sanctionsFallback": {
            "type": "boolean",
            "description": "The match rests on Guard's fallback sanctions list: the live list could not be read."
          },
          "noActivity": {
            "type": "boolean",
            "description": "Guard's no-activity report: the network's provider says the account does not exist. A result like any other."
          },
          "noActivityMessage": {
            "type": ["string", "null"],
            "description": "Guard's own sentence on that report, shown as plain text; null otherwise."
          }
        }
      },
      "ClaudeCheckCard": {
        "oneOf": [
          {
            "type": "object",
            "required": ["stage", "chain", "price"],
            "properties": {
              "stage": {
                "const": "ready"
              },
              "chain": {
                "$ref": "#/components/schemas/ClaudeChain"
              },
              "price": {
                "$ref": "#/components/schemas/ClaudeCheckPrice"
              },
              "notice": {
                "type": "string"
              }
            }
          },
          {
            "type": "object",
            "required": ["stage", "chain", "result"],
            "properties": {
              "stage": {
                "const": "result"
              },
              "chain": {
                "$ref": "#/components/schemas/ClaudeChain"
              },
              "result": {
                "$ref": "#/components/schemas/ClaudeCheckResult"
              }
            }
          },
          {
            "type": "object",
            "required": ["stage", "chain", "reason", "message", "action"],
            "properties": {
              "stage": {
                "const": "refused"
              },
              "chain": {
                "$ref": "#/components/schemas/ClaudeChain"
              },
              "reason": {
                "type": "string",
                "enum": [
                  "invalid_address",
                  "network_mismatch",
                  "no_credits",
                  "signed_out",
                  "unavailable",
                  "result_lost",
                  "busy",
                  "refused_by_swaps"
                ]
              },
              "message": {
                "type": "string"
              },
              "action": {
                "type": ["string", "null"],
                "enum": ["buy_credits", null]
              }
            }
          }
        ]
      },
      "McpMessage": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": {
            "const": "2.0"
          },
          "id": {
            "type": ["string", "number"]
          },
          "method": {
            "type": "string"
          },
          "params": {
            "type": "object"
          }
        }
      },
      "McpResponse": {
        "type": "object",
        "required": ["jsonrpc"],
        "properties": {
          "jsonrpc": {
            "const": "2.0"
          },
          "id": {
            "type": ["string", "number", "null"]
          },
          "result": {
            "type": "object"
          },
          "error": {
            "type": "object"
          }
        }
      },
      "GateError": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "batch_not_supported",
              "invalid_token",
              "rate_limit_exceeded",
              "auth_unavailable",
              "mcp_request_failed",
              "method_not_allowed"
            ]
          },
          "error_description": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "requestId": {
            "type": "string"
          }
        }
      },
      "ProtectedResourceMetadata": {
        "type": "object",
        "required": [
          "resource",
          "authorization_servers",
          "bearer_methods_supported",
          "scopes_supported",
          "resource_name"
        ],
        "properties": {
          "resource": {
            "const": "https://www.swaps.app/api/mcp-claude"
          },
          "authorization_servers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 1,
            "maxItems": 1
          },
          "bearer_methods_supported": {
            "const": ["header"]
          },
          "scopes_supported": {
            "const": ["openid"]
          },
          "resource_name": {
            "const": "Swaps Wallet Screen for Claude"
          }
        }
      }
    }
  }
}
