{
  "openapi": "3.1.0",
"info": {
  "title": "IPIntel.ai x402 API",
  "version": "1.0.0",
  "description": "Machine-payable IP threat intelligence API using x402 payments on Base. The first live resource is a single IP lookup priced at $0.001 USDC per request.",
  "contact": {
    "name": "IPIntel.ai",
    "email": "support@ipintel.ai",
    "url": "https://ipintel.ai/x402-api"
  }
}
  "servers": [
    {
      "url": "https://api.ipintel.ai",
      "description": "IPIntel.ai public API"
    }
  ],
  "paths": {
    "/x402/": {
      "get": {
        "operationId": "x402IpLookup",
        "summary": "Machine-payable IP threat intelligence lookup",
        "description": "Returns structured IP threat intelligence after a valid x402 payment. Initial requests without X-PAYMENT return HTTP 402 with payment requirements.",
        "parameters": [
          {
            "name": "ip",
            "in": "query",
            "required": true,
            "description": "IPv4 or IPv6 address to evaluate.",
            "schema": {
              "type": "string",
              "examples": [
                "8.8.8.8",
                "1.1.1.1",
                "2001:4860:4860::8888"
              ]
            }
          },
          {
            "name": "X-PAYMENT",
            "in": "header",
            "required": false,
            "description": "Signed x402 payment payload. Required after receiving the 402 payment challenge.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful paid IP threat intelligence response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IPThreatResponse"
                },
                "examples": {
                  "paidLookup": {
                    "summary": "Successful x402 IP lookup",
                    "value": {
                      "ip": "8.8.8.8",
                      "country": "United States",
                      "country_code": "US",
                      "isp": "Google LLC",
                      "org": "Google Public DNS",
                      "asn": "AS15169",
                      "as_name": "Google LLC",
                      "reverse_dns": "dns.google",
                      "is_tor_exit": false,
                      "is_proxy": false,
                      "is_hosting": true,
                      "risk_score": 15,
                      "threat_score": "15",
                      "confidence_level": 100,
                      "status": "safe",
                      "badges": [],
                      "verified_bot": false,
                      "response_ms": 5.1,
                      "payment_mode": "x402",
                      "x402": {
                        "paid": true,
                        "network": "base",
                        "currency": "USDC",
                        "amount": "0.001",
                        "pay_to": "0x0550779CFBc832657A8BB46BAC9f359A5ad038B8",
                        "resource": "https://api.ipintel.ai/x402/?ip=8.8.8.8"
                      },
                      "server_response_ms": 6.2
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request, missing or invalid IP parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required. The response contains payment requirements in the accepts array.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/X402PaymentRequired"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "IPThreatResponse": {
        "type": "object",
        "properties": {
          "ip": {
            "type": "string"
          },
          "country": {
            "type": [
              "string",
              "null"
            ]
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "region": {
            "type": [
              "string",
              "null"
            ]
          },
          "region_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "city": {
            "type": [
              "string",
              "null"
            ]
          },
          "isp": {
            "type": [
              "string",
              "null"
            ]
          },
          "org": {
            "type": [
              "string",
              "null"
            ]
          },
          "asn": {
            "type": [
              "string",
              "null"
            ]
          },
          "as_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "latitude": {
            "type": [
              "string",
              "number",
              "null"
            ]
          },
          "longitude": {
            "type": [
              "string",
              "number",
              "null"
            ]
          },
          "timezone": {
            "type": [
              "string",
              "null"
            ]
          },
          "reverse_dns": {
            "type": [
              "string",
              "null"
            ]
          },
          "is_tor_exit": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_proxy": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_hosting": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "risk_score": {
            "type": [
              "integer",
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 100
          },
          "threat_score": {
            "type": [
              "integer",
              "number",
              "string",
              "null"
            ]
          },
          "confidence_level": {
            "type": [
              "integer",
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 100
          },
          "risk_summary": {
            "type": [
              "string",
              "null"
            ]
          },
          "summary": {
            "type": [
              "string",
              "null"
            ]
          },
          "ai_supernet_summary": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "safe",
              "suspicious",
              "dangerous",
              "unknown"
            ]
          },
          "badges": {
            "type": "array",
            "items": {
              "type": [
                "object",
                "string"
              ]
            }
          },
          "javascript_support": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "user_agents": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "verified_bot": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "verified_bot_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "verified_bot_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "response_ms": {
            "type": [
              "integer",
              "number",
              "null"
            ]
          },
          "payment_mode": {
            "type": "string",
            "const": "x402"
          },
          "x402": {
            "$ref": "#/components/schemas/X402Metadata"
          },
          "server_response_ms": {
            "type": [
              "integer",
              "number",
              "null"
            ]
          }
        },
        "required": [
          "ip",
          "payment_mode",
          "x402"
        ],
        "additionalProperties": true
      },
      "X402Metadata": {
        "type": "object",
        "properties": {
          "paid": {
            "type": "boolean"
          },
          "network": {
            "type": "string",
            "examples": [
              "base"
            ]
          },
          "currency": {
            "type": "string",
            "examples": [
              "USDC"
            ]
          },
          "amount": {
            "type": "string",
            "examples": [
              "0.001"
            ]
          },
          "pay_to": {
            "type": "string",
            "examples": [
              "0x0550779CFBc832657A8BB46BAC9f359A5ad038B8"
            ]
          },
          "resource": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "paid",
          "network",
          "currency",
          "amount",
          "resource"
        ],
        "additionalProperties": true
      },
      "X402PaymentRequired": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "examples": [
              "X-PAYMENT header is required"
            ]
          },
          "accepts": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "x402Version": {
            "type": [
              "integer",
              "string"
            ]
          }
        },
        "required": [
          "accepts"
        ],
        "additionalProperties": true
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": true
      }
    }
  },
  "x-ipintel": {
    "x402": {
      "network": "base",
      "currency": "USDC",
      "price": "0.001",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "pay_to": "0x0550779CFBc832657A8BB46BAC9f359A5ad038B8"
    },
    "planned_endpoints": [
      {
        "path": "/x402/subnet",
        "status": "planned"
      },
      {
        "path": "/x402/supernet",
        "status": "planned"
      },
      {
        "path": "/x402/asn",
        "status": "planned"
      }
    ]
  }
}