{
  "openapi": "3.0.3",
  "info": {
    "title": "AzurSafe x402 API",
    "version": "1.0.0",
    "summary": "Risk screening for agentic wallets and counterparties.",
    "description": "AzurSafe x402 screens wallets and other counterparties before autonomous onchain actions. It returns machine-readable risk results that agents, payment bots, treasury systems, wallets, and exchanges can enforce in policy decisions.",
    "contact": {
      "name": "AzurSafe",
      "url": "https://ai.azursafe.com",
      "email": "contact@azursafe.com"
    }
  },
  "servers": [
    {
      "url": "https://ai.azursafe.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "System",
      "description": "Operational endpoints."
    },
    {
      "name": "Screening",
      "description": "Paid x402 screening endpoints."
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": ["System"],
        "operationId": "getHealth",
        "summary": "Health check",
        "description": "Returns the health status of the API.",
        "responses": {
          "200": {
            "description": "Service is healthy.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                },
                "example": {
                  "ok": true
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "METHOD_NOT_ALLOWED",
                  "message": "Method not allowed"
                }
              }
            }
          }
        }
      }
    },
    "/agent/screen-id": {
      "get": {
        "tags": ["Screening"],
        "operationId": "screenIdentifier",
        "summary": "Screen a wallet or counterparty",
        "description": "Screens a wallet address or other counterparty identifier before an autonomous onchain action. This endpoint is protected by x402 payment flow. Accepted identifier types include wallet addresses, domains, emails, phone numbers, and usernames.",
        "security": [
          {
            "PaymentSignature": []
          },
          {
            "XPayment": []
          }
        ],
        "parameters": [
          {
            "name": "identifier",
            "in": "query",
            "required": true,
            "description": "Counterparty identifier to risk-screen before an agent sends, receives, swaps, bridges, or pays. Supports wallet addresses across 30+ major blockchains and additional identifiers such as domains, emails, phone numbers, and usernames.",
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "examples": {
              "evm": {
                "summary": "EVM wallet",
                "value": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B"
              },
              "tron": {
                "summary": "Tron wallet",
                "value": "TE3mCcPULjPUE7ykX7RArDPAhyahoy3d2j"
              },
              "bitcoin": {
                "summary": "Bitcoin wallet",
                "value": "1PMycacnJaSqwwJqjawXBErnLsZ7RkXUAs"
              },
              "domain": {
                "summary": "Domain",
                "value": "example.org"
              },
              "email": {
                "summary": "Email",
                "value": "ops@example.org"
              },
              "phone": {
                "summary": "Phone number",
                "value": "+14155550123"
              },
              "username": {
                "summary": "Username",
                "value": "treasury_bot"
              },
              "solana": {
                "summary": "Solana wallet",
                "value": "8fjkQpV7L6Wm2nZrYt3aBcD4EfGhJkLmNoPqRsTuVwX"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful screening response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScreenSuccessResponse"
                },
                "examples": {
                  "legit": {
                    "summary": "Legit result",
                    "value": {
                      "ok": true,
                      "endpoint": "screen-id",
                      "identifier": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
                      "data": {
                        "name": "Vb_4e62be",
                        "legitimacyStatus": "legit",
                        "category": "Foundation/Developer",
                        "source": "Public and Online Data",
                        "findings": 4
                      }
                    }
                  },
                  "fraud": {
                    "summary": "Fraud result",
                    "value": {
                      "ok": true,
                      "endpoint": "screen-id",
                      "identifier": "TE3mCcPULjPUE7ykX7RArDPAhyahoy3d2j",
                      "data": {
                        "name": "OFAC_Sanctioned_2b477d",
                        "legitimacyStatus": "fraud",
                        "category": "Phishing/Fraud",
                        "source": "Online and Public Data",
                        "findings": 2
                      }
                    }
                  },
                  "unknown": {
                    "summary": "Unknown result",
                    "value": {
                      "ok": true,
                      "endpoint": "screen-id",
                      "identifier": "1PMycacnJaSqwwJqjawXBErnLsZ7RkXUAs",
                      "data": {
                        "name": null,
                        "legitimacyStatus": "unknown",
                        "category": null,
                        "source": null,
                        "findings": 0
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidRequest": {
                    "value": {
                      "error": "INVALID_REQUEST",
                      "message": "The request is invalid."
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required. Complete the x402 payment flow and retry the request.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment challenge returned by the server.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "METHOD_NOT_ALLOWED",
                  "message": "Method not allowed"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the rate limit resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "RATE_LIMIT_EXCEEDED",
                  "message": "Too many requests. Please try again later.",
                  "retryAfterSeconds": 42
                }
              }
            }
          },
          "502": {
            "description": "Upstream or payment flow failure.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "requestFailed": {
                    "value": {
                      "error": "REQUEST_FAILED",
                      "message": "Unable to process the request at this time."
                    }
                  },
                  "paymentFlowFailed": {
                    "value": {
                      "error": "PAYMENT_FLOW_FAILED",
                      "message": "Unable to process the payment flow."
                    }
                  },
                  "paymentSettlementFailed": {
                    "value": {
                      "error": "PAYMENT_SETTLEMENT_FAILED",
                      "message": "Unable to finalize the paid response."
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PaymentSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 payment proof header."
      },
      "XPayment": {
        "type": "apiKey",
        "in": "header",
        "name": "X-PAYMENT",
        "description": "Backward-compatible x402 payment proof header."
      }
    },
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "ok": {
            "type": "boolean"
          }
        },
        "required": ["ok"]
      },
      "ScreenResultData": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "nullable": true
          },
          "legitimacyStatus": {
            "type": "string",
            "enum": ["legit", "fraud", "unknown"]
          },
          "category": {
            "type": "string",
            "nullable": true
          },
          "source": {
            "type": "string",
            "nullable": true
          },
          "findings": {
            "type": "integer",
            "minimum": 0
          }
        },
        "required": ["name", "legitimacyStatus", "category", "source", "findings"]
      },
      "ScreenSuccessResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "endpoint": {
            "type": "string",
            "enum": ["screen-id"]
          },
          "identifier": {
            "type": "string"
          },
          "data": {
            "$ref": "#/components/schemas/ScreenResultData"
          }
        },
        "required": ["ok", "endpoint", "identifier", "data"]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "retryAfterSeconds": {
            "type": "integer",
            "minimum": 1
          }
        },
        "required": ["error", "message"],
        "additionalProperties": true
      }
    }
  }
}