{ "openapi": "3.1.0", "info": { "title": "PG1 Sovereign Threat Intelligence API", "version": "1.15.0", "contact": { "email": "gikewun@gmail.com" }, "description": "REST endpoints for PG1 Sovereign Threat Intelligence. This document only covers the plain HTTP endpoints below (GET/POST /api/ioc and GET /api/health); the full tool catalog is also available over two JSON-RPC transports, which are not representable as REST paths:\n\n- MCP (Model Context Protocol, Streamable HTTP JSON-RPC): https://pg1-ai-agent.vercel.app/api/mcp \n- A2A (Agent2Agent, JSON-RPC 2.0): https://pg1-ai-agent.vercel.app/api/a2a — agent card at https://pg1-ai-agent.vercel.app/.well-known/agent-card.json \n\n/api/ioc is gated by one of: a Gumroad licence key (x-api-key header), a per-call x402 v2 micropayment (PAYMENT-SIGNATURE header), or the opt-in free tier (x-free-tier: 1 header, 5 calls/day per IP).", "x-guidance": "To get threat indicators, send GET /api/ioc with optional query parameters (since, type, min_score, limit); an unpaid request returns HTTP 402 with an x402 v2 PaymentRequired challenge, so pay $0.01 per call in USDC on Base (eip155:8453) by retrying with the signed payment in the PAYMENT-SIGNATURE header, and you get back a STIX 2.1 bundle (application/stix+json) of matching indicators. GET /api/health is free and needs no payment." }, "externalDocs": { "description": "Integration guide: an alert bot that screens wallets with PG1's free checks.", "url": "https://pg1-ai-agent.vercel.app/docs/crypto-alert-bot" }, "servers": [ { "url": "https://pg1-ai-agent.vercel.app" } ], "paths": { "/api/ioc": { "get": { "operationId": "getThreatIndicators", "summary": "STIX 2.1 threat indicator feed", "description": "Returns a STIX 2.1 bundle of threat indicators. Requires a Gumroad licence key, a settled x402 v2 payment, or an opt-in free-tier request (subject to the 5 calls/day per IP limit).", "parameters": [ { "name": "since", "in": "query", "required": false, "description": "ISO timestamp (e.g. 2026-09-20T00:00:00Z). Only indicators last seen after this time are returned.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Exact-match indicator type filter against the stored value.", "schema": { "type": "string", "enum": ["IPv4", "IPv6", "domain", "hostname", "URL", "FileHash-MD5", "FileHash-SHA1", "FileHash-SHA256", "CVE"] } }, { "name": "min_score", "in": "query", "required": false, "description": "Minimum confidence score, inclusive.", "schema": { "type": "integer", "minimum": 0, "maximum": 100, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of STIX objects to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } }, { "name": "x-free-tier", "in": "header", "required": false, "description": "Opt in to the free tier: set to \"1\" to be considered for a free, unauthenticated, unpaid request. Limited to 5 calls/day per IP. Ignored if a licence key or payment is also present.", "schema": { "type": "string", "enum": ["1"] } } ], "security": [ { "X402Payment": [] }, { "ApiKeyAuth": [] } ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }, "protocols": [{ "x402": {} }] }, "responses": { "200": { "description": "STIX 2.1 bundle of matching threat indicators.", "content": { "application/stix+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "bundle" }, "id": { "type": "string", "description": "STIX bundle id, bundle--." }, "objects": { "type": "array", "items": { "oneOf": [ { "type": "object", "description": "STIX 2.1 Indicator (IPv4, IPv6, domain, hostname, URL and file-hash records).", "properties": { "type": { "type": "string", "const": "indicator" }, "spec_version": { "type": "string", "const": "2.1" }, "id": { "type": "string" }, "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "description": { "type": "string" }, "indicator_types": { "type": "array", "items": { "type": "string" } }, "pattern": { "type": "string", "description": "STIX pattern, e.g. [ipv4-addr:value = '198.51.100.23']." }, "pattern_type": { "type": "string", "const": "stix" }, "valid_from": { "type": "string", "format": "date-time" }, "confidence": { "type": "integer", "minimum": 0, "maximum": 100 }, "external_references": { "type": "array", "items": { "type": "object", "properties": { "source_name": { "type": "string" }, "description": { "type": "string" } } } } }, "required": [ "type", "spec_version", "id", "created", "modified", "pattern", "pattern_type", "valid_from" ] }, { "type": "object", "description": "STIX 2.1 Vulnerability (CVE records).", "properties": { "type": { "type": "string", "const": "vulnerability" }, "spec_version": { "type": "string", "const": "2.1" }, "id": { "type": "string" }, "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" }, "name": { "type": "string", "description": "CVE id, e.g. CVE-2026-12345." }, "description": { "type": "string" }, "external_references": { "type": "array", "items": { "type": "object", "properties": { "source_name": { "type": "string" }, "external_id": { "type": "string" } } } } }, "required": [ "type", "spec_version", "id", "created", "modified", "name" ] } ] } } }, "required": [ "type", "id", "objects" ] } } } }, "402": { "description": "Payment required. An unauthenticated request with no payment gets the x402 v2 PaymentRequired challenge (also base64-encoded in the PAYMENT-REQUIRED header): accepts[] offers one exact-scheme USDC payment on Base (eip155:8453), amount \"10000\" atomic units = $0.01. The same challenge is returned when a supplied payment fails verification or settlement. A plain error object is returned instead if the x402 facilitator is unreachable or x402 is not configured on the deployment.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64-encoded x402 v2 PaymentRequired JSON object. Present when the x402 middleware issues the challenge.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "x402 v2 PaymentRequired object.", "properties": { "x402Version": { "type": "integer", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" } } }, "accepts": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "scheme": { "type": "string", "const": "exact" }, "network": { "type": "string", "const": "eip155:8453" }, "amount": { "type": "string", "description": "Price in USDC atomic units (6 decimals): \"10000\" = $0.01." }, "asset": { "type": "string", "description": "USDC contract on Base." }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer" }, "extra": { "type": "object" } }, "required": [ "scheme", "network", "amount", "asset", "payTo" ] } }, "extensions": { "type": "object" } }, "required": [ "x402Version", "accepts" ] }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } ] } } } }, "403": { "description": "Forbidden: the supplied licence key is invalid, expired, or refunded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "405": { "description": "Method Not Allowed. /api/ioc only serves GET, POST, HEAD, and OPTIONS.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal Server Error while building or serving the STIX bundle.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Threat data or licence verification is temporarily unavailable; retry shortly.", "headers": { "Retry-After": { "description": "Present when licence verification is temporarily unavailable. Value in seconds.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "post": { "operationId": "postThreatIndicators", "summary": "STIX 2.1 threat indicator feed (POST alias of GET)", "description": "Identical to GET /api/ioc: same optional query parameters (no request body is read), same gate and price, same STIX 2.1 bundle response. Documented because the endpoint answers POST with the same x402 challenge.", "parameters": [ { "name": "since", "in": "query", "required": false, "description": "ISO timestamp (e.g. 2026-09-20T00:00:00Z). Only indicators last seen after this time are returned.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Exact-match indicator type filter against the stored value.", "schema": { "type": "string", "enum": [ "IPv4", "IPv6", "domain", "hostname", "URL", "FileHash-MD5", "FileHash-SHA1", "FileHash-SHA256", "CVE" ] } }, { "name": "min_score", "in": "query", "required": false, "description": "Minimum confidence score, inclusive.", "schema": { "type": "integer", "minimum": 0, "maximum": 100, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of STIX objects to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } }, { "name": "x-free-tier", "in": "header", "required": false, "description": "Opt in to the free tier: set to \"1\" to be considered for a free, unauthenticated, unpaid request. Limited to 5 calls/day per IP. Ignored if a licence key or payment is also present.", "schema": { "type": "string", "enum": [ "1" ] } } ], "security": [ { "X402Payment": [] }, { "ApiKeyAuth": [] } ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }, "protocols": [ { "x402": {} } ] }, "responses": { "200": { "description": "STIX 2.1 bundle of matching threat indicators.", "content": { "application/stix+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "bundle" }, "id": { "type": "string", "description": "STIX bundle id, bundle--." }, "objects": { "type": "array", "items": { "oneOf": [ { "type": "object", "description": "STIX 2.1 Indicator (IPv4, IPv6, domain, hostname, URL and file-hash records).", "properties": { "type": { "type": "string", "const": "indicator" }, "spec_version": { "type": "string", "const": "2.1" }, "id": { "type": "string" }, "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "description": { "type": "string" }, "indicator_types": { "type": "array", "items": { "type": "string" } }, "pattern": { "type": "string", "description": "STIX pattern, e.g. [ipv4-addr:value = '198.51.100.23']." }, "pattern_type": { "type": "string", "const": "stix" }, "valid_from": { "type": "string", "format": "date-time" }, "confidence": { "type": "integer", "minimum": 0, "maximum": 100 }, "external_references": { "type": "array", "items": { "type": "object", "properties": { "source_name": { "type": "string" }, "description": { "type": "string" } } } } }, "required": [ "type", "spec_version", "id", "created", "modified", "pattern", "pattern_type", "valid_from" ] }, { "type": "object", "description": "STIX 2.1 Vulnerability (CVE records).", "properties": { "type": { "type": "string", "const": "vulnerability" }, "spec_version": { "type": "string", "const": "2.1" }, "id": { "type": "string" }, "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" }, "name": { "type": "string", "description": "CVE id, e.g. CVE-2026-12345." }, "description": { "type": "string" }, "external_references": { "type": "array", "items": { "type": "object", "properties": { "source_name": { "type": "string" }, "external_id": { "type": "string" } } } } }, "required": [ "type", "spec_version", "id", "created", "modified", "name" ] } ] } } }, "required": [ "type", "id", "objects" ] } } } }, "402": { "description": "Payment required. An unauthenticated request with no payment gets the x402 v2 PaymentRequired challenge (also base64-encoded in the PAYMENT-REQUIRED header): accepts[] offers one exact-scheme USDC payment on Base (eip155:8453), amount \"10000\" atomic units = $0.01. The same challenge is returned when a supplied payment fails verification or settlement. A plain error object is returned instead if the x402 facilitator is unreachable or x402 is not configured on the deployment.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64-encoded x402 v2 PaymentRequired JSON object. Present when the x402 middleware issues the challenge.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "x402 v2 PaymentRequired object.", "properties": { "x402Version": { "type": "integer", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" } } }, "accepts": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "scheme": { "type": "string", "const": "exact" }, "network": { "type": "string", "const": "eip155:8453" }, "amount": { "type": "string", "description": "Price in USDC atomic units (6 decimals): \"10000\" = $0.01." }, "asset": { "type": "string", "description": "USDC contract on Base." }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer" }, "extra": { "type": "object" } }, "required": [ "scheme", "network", "amount", "asset", "payTo" ] } }, "extensions": { "type": "object" } }, "required": [ "x402Version", "accepts" ] }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } ] } } } }, "403": { "description": "Forbidden: the supplied licence key is invalid, expired, or refunded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "405": { "description": "Method Not Allowed. /api/ioc only serves GET, POST, HEAD, and OPTIONS.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal Server Error while building or serving the STIX bundle.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Threat data or licence verification is temporarily unavailable; retry shortly.", "headers": { "Retry-After": { "description": "Present when licence verification is temporarily unavailable. Value in seconds.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/api/health": { "get": { "operationId": "getHealth", "summary": "Health check", "description": "Public, ungated uptime check. Never consumes free-tier quota. Result is cached in memory for up to 30 seconds.", "security": [], "responses": { "200": { "description": "Service is healthy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "checks": { "type": "object", "properties": { "supabase": { "type": "string", "const": "ok" } } }, "time": { "type": "string", "format": "date-time" } }, "required": ["status", "checks", "time"] } } } }, "503": { "description": "Service is degraded (Supabase reachability check failed).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "degraded" }, "checks": { "type": "object", "properties": { "supabase": { "type": "string", "const": "unavailable" } } }, "time": { "type": "string", "format": "date-time" } }, "required": ["status", "checks", "time"] } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Gumroad licence key. A Bearer token in the Authorization header is also accepted as an alternative." }, "X402Payment": { "type": "apiKey", "in": "header", "name": "PAYMENT-SIGNATURE", "description": "Signed x402 v2 payment payload for a $0.01 per-call micropayment on Base (eip155:8453). The X-Payment header name is also accepted." } } } }