{
  "openapi": "3.1.0",
  "info": {
    "title": "Swaps Wallet Screen MCP",
    "version": "1.1.0",
    "description": "The dedicated, anonymous Wallet Screen server accepts one public address and an explicit network. It screens the address now, or reuses Guard's own recent screening of it, and reports sanctions matches from live sources and the risk signals found. Coverage varies. A missing signal does not establish safety. Results include a nullable risk index, the screening time, response time and available signal context. Optional locale selects the card language. The card can show private selectable text for sharing; it creates no public link and consumes no credit."
  },
  "servers": [
    {
      "url": "https://www.swaps.app"
    }
  ],
  "paths": {
    "/api/mcp-wallet-screen": {
      "post": {
        "operationId": "walletScreenMcpPost",
        "summary": "Send a Wallet Screen MCP message",
        "description": "Send JSON-RPC over stateless MCP Streamable HTTP with application/json and text/event-stream in Accept. MCP 2026-07-28 supports server/discover. Its requests carry the protocol version and client capabilities in the per-request _meta envelope. Legacy clients use initialize with 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, or 2024-10-07 and send the negotiated MCP-Protocol-Version after initialization. Use tools/list for the tool definition and tools/call for a result in result.structuredContent alongside text content.",
        "security": [],
        "parameters": [
          {
            "in": "header",
            "name": "MCP-Protocol-Version",
            "description": "On 2026-07-28 requests, send 2026-07-28 and match the version in _meta. For legacy clients, send the version agreed in initialize on subsequent requests.",
            "schema": {
              "type": "string"
            },
            "example": "2026-07-28"
          },
          {
            "in": "header",
            "name": "Mcp-Method",
            "description": "Required on 2026-07-28 request POSTs. Match the JSON-RPC method.",
            "schema": {
              "type": "string"
            },
            "example": "server/discover"
          },
          {
            "in": "header",
            "name": "Mcp-Name",
            "description": "Required for named 2026-07-28 requests such as tools/call or resources/read. Match params.name or params.uri, respectively.",
            "schema": {
              "type": "string"
            },
            "example": "screen_wallet_address"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/McpMessage"
              },
              "examples": {
                "discover": {
                  "summary": "Discover MCP 2026-07-28 capabilities",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": "discover-1",
                    "method": "server/discover",
                    "params": {
                      "_meta": {
                        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
                        "io.modelcontextprotocol/clientInfo": {
                          "name": "example-client",
                          "version": "1.0.0"
                        },
                        "io.modelcontextprotocol/clientCapabilities": {}
                      }
                    }
                  }
                },
                "initializeLegacy": {
                  "summary": "Initialize a legacy connection",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": "initialize-1",
                    "method": "initialize",
                    "params": {
                      "protocolVersion": "2025-11-25",
                      "capabilities": {},
                      "clientInfo": {
                        "name": "example-client",
                        "version": "1.0.0"
                      }
                    }
                  }
                },
                "listTools": {
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "tools/list"
                  }
                },
                "screenAddress": {
                  "summary": "Screen a public address after legacy initialization",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 2,
                    "method": "tools/call",
                    "params": {
                      "name": "screen_wallet_address",
                      "arguments": {
                        "address": "0x000000000000000000000000000000000000dEaD",
                        "chain": "Ethereum"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response. A successful server/discover response is JSON and carries the modern version, server capabilities, and identity metadata. Legacy initialize replies in a server-sent event.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpResponse"
                },
                "examples": {
                  "discover": {
                    "value": {
                      "jsonrpc": "2.0",
                      "id": "discover-1",
                      "result": {
                        "resultType": "complete",
                        "supportedVersions": ["2026-07-28"],
                        "capabilities": {
                          "tools": {
                            "listChanged": true
                          },
                          "resources": {
                            "listChanged": true
                          }
                        },
                        "_meta": {
                          "io.modelcontextprotocol/serverInfo": {
                            "name": "swaps-wallet-screen",
                            "version": "1.1.0"
                          }
                        },
                        "instructions": "Check one public blockchain address on a network the user explicitly named for that address. If the network is missing or ambiguous, ask which network to use and wait for the reply before calling the tool. A 0x address, a known address, and prior results are not evidence of the user’s network choice. Pass the conversation language as locale when known. After screening, let the widget carry the result and briefly explain the coverage in the user’s language without repeating the entire card. A score out of 100 is a risk index, not a probability of safety. Share only shows selectable text at the user’s request; it does not publish a page or confirm delivery. Never infer safety, identity, or whether the user should transact.",
                        "ttlMs": 0,
                        "cacheScope": "private"
                      }
                    }
                  }
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                },
                "x-swaps-sse-data-schema": {
                  "$ref": "#/components/schemas/McpResponse"
                }
              }
            }
          },
          "202": {
            "description": "Accepted a JSON-RPC notification. The response is empty."
          },
          "400": {
            "description": "Invalid JSON-RPC message, unsupported protocol version, or missing or mismatched MCP routing headers."
          },
          "406": {
            "description": "The Accept header must allow JSON and server-sent events."
          },
          "415": {
            "description": "The request body must use application/json."
          },
          "429": {
            "description": "The caller exceeded the server's request limit."
          },
          "500": {
            "description": "The MCP server could not handle the request."
          }
        },
        "x-swaps-mcp-tools": [
          {
            "name": "screen_wallet_address",
            "inputSchema": {
              "$ref": "#/components/schemas/WalletScreenInput"
            },
            "outputSchema": {
              "$ref": "#/components/schemas/WalletScreenOutput"
            },
            "annotations": {
              "readOnlyHint": true,
              "destructiveHint": false,
              "openWorldHint": true
            }
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "McpMessage": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": {
            "const": "2.0"
          },
          "id": {
            "type": ["string", "number"]
          },
          "method": {
            "type": "string"
          },
          "params": {
            "type": "object"
          }
        },
        "if": {
          "properties": {
            "method": {
              "const": "tools/call"
            }
          }
        },
        "then": {
          "required": ["id", "params"],
          "properties": {
            "params": {
              "required": ["name", "arguments"],
              "properties": {
                "name": {
                  "const": "screen_wallet_address"
                },
                "arguments": {
                  "$ref": "#/components/schemas/WalletScreenInput"
                }
              }
            }
          }
        }
      },
      "McpResponse": {
        "type": "object",
        "required": ["jsonrpc", "id"],
        "oneOf": [
          {
            "required": ["result"]
          },
          {
            "required": ["error"]
          }
        ],
        "properties": {
          "jsonrpc": {
            "const": "2.0"
          },
          "id": {
            "type": ["string", "number", "null"]
          },
          "result": {
            "type": "object",
            "if": {
              "required": ["supportedVersions"]
            },
            "then": {
              "$ref": "#/components/schemas/McpDiscoverResult"
            },
            "properties": {
              "protocolVersion": {
                "description": "The revision negotiated through legacy initialize.",
                "enum": ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05", "2024-10-07"]
              },
              "structuredContent": {
                "$ref": "#/components/schemas/WalletScreenOutput"
              },
              "content": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              }
            }
          },
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "integer"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "McpDiscoverResult": {
        "type": "object",
        "required": [
          "resultType",
          "supportedVersions",
          "capabilities",
          "_meta",
          "ttlMs",
          "cacheScope"
        ],
        "properties": {
          "resultType": {
            "const": "complete"
          },
          "supportedVersions": {
            "description": "Modern revisions supported by this server. Legacy versions are negotiated separately through initialize.",
            "const": ["2026-07-28"]
          },
          "capabilities": {
            "type": "object",
            "required": ["tools", "resources"],
            "properties": {
              "tools": {
                "type": "object"
              },
              "resources": {
                "type": "object"
              }
            }
          },
          "_meta": {
            "type": "object",
            "required": ["io.modelcontextprotocol/serverInfo"],
            "properties": {
              "io.modelcontextprotocol/serverInfo": {
                "type": "object",
                "required": ["name", "version"],
                "properties": {
                  "name": {
                    "const": "swaps-wallet-screen"
                  },
                  "version": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "instructions": {
            "type": "string"
          },
          "ttlMs": {
            "type": "integer",
            "minimum": 0
          },
          "cacheScope": {
            "enum": ["public", "private"]
          }
        }
      },
      "WalletScreenInput": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Public wallet address, preserving case."
          },
          "chain": {
            "$ref": "#/components/schemas/WalletScreenChain"
          },
          "locale": {
            "type": "string",
            "minLength": 2,
            "maxLength": 35,
            "pattern": "^(?:[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*|x(?:-[A-Za-z0-9]{1,8})+)$",
            "description": "Optional BCP 47 language tag for presentation only; never forwarded to screening providers."
          }
        },
        "required": ["address", "chain"],
        "additionalProperties": false
      },
      "WalletScreenOutput": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": ["checked", "insufficient_data", "invalid_address", "unavailable"]
          },
          "chain": {
            "$ref": "#/components/schemas/WalletScreenChain"
          },
          "risk": {
            "type": "string",
            "enum": ["low", "medium", "high", "critical", "unknown"]
          },
          "coverage": {
            "type": "string",
            "enum": [
              "sanctions_match",
              "live_screening",
              "cached_screening",
              "limited",
              "unavailable"
            ],
            "description": "live_screening: screened for this request. cached_screening: a previous screening of this address. limited/unavailable: no verdict."
          },
          "flags": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "Number of signals Guard reported for this screening; can exceed the reasons listed, which are deduplicated and limited to known codes. Null when not applicable."
          },
          "sanctionsSources": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": ["OFAC", "Chainalysis Oracle", "Chainalysis API"]
            }
          },
          "riskScore": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0,
                "maximum": 100
              },
              {
                "type": "null"
              }
            ],
            "description": "Existing engine score, higher means more risk; not a probability of loss or safety."
          },
          "assessedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
              },
              {
                "type": "null"
              }
            ],
            "description": "Time the screening behind this result was computed, when known; for a previous screening, its original time. Never the response rendering time."
          },
          "responseAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
              },
              {
                "type": "null"
              }
            ],
            "description": "Time Guard reported with this response; not the time the card was rendered, nor when the underlying sources were updated."
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "sanctions_match",
                    "sanctioned",
                    "blacklisted",
                    "mixer",
                    "contract",
                    "threat_intel",
                    "new_address",
                    "data_integrity",
                    "suspicious_pattern",
                    "provider_unavailable",
                    "free_check_used",
                    "free_checks_network_used",
                    "service_busy",
                    "daily_budget_exhausted",
                    "service_degraded",
                    "account_required",
                    "chatgpt_account_unknown"
                  ]
                },
                "severity": {
                  "type": "string",
                  "enum": ["low", "medium", "high"]
                }
              },
              "required": ["code", "severity"],
              "additionalProperties": false
            }
          },
          "sourceCoverage": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "source": {
                  "type": "string",
                  "enum": ["goplus", "ofac", "chainalysis", "onchain", "threat_intel"]
                },
                "status": {
                  "type": "string",
                  "enum": ["checked", "unavailable", "not_supported"]
                }
              },
              "required": ["source", "status"],
              "additionalProperties": false
            },
            "description": "Which sources answered in the screening this result comes from (a previous one for cached_screening). Checked means the source answered; it does not mean no risk was found."
          },
          "summary": {
            "type": "string"
          }
        },
        "required": [
          "status",
          "chain",
          "risk",
          "coverage",
          "flags",
          "sanctionsSources",
          "riskScore",
          "assessedAt",
          "responseAt",
          "reasons",
          "sourceCoverage",
          "summary"
        ],
        "additionalProperties": false
      },
      "WalletScreenChain": {
        "type": "string",
        "enum": [
          "Ethereum",
          "Base",
          "Arbitrum",
          "Polygon",
          "BNB Chain",
          "Optimism",
          "Avalanche",
          "Bitcoin",
          "Solana",
          "Tron",
          "XRP Ledger",
          "TON",
          "Cardano",
          "Cosmos"
        ],
        "description": "Blockchain network explicitly named or confirmed by the user for this address."
      }
    }
  }
}
