{
  "openapi": "3.1.0",
  "info": {
    "title": "x402 Social Stats API",
    "version": "1.0.0",
    "description": "The first x402 native social media analytics API, by FindClout. Live views, likes, comments, shares, and follower counts for public Instagram, TikTok, and X posts, looked up by URL. No API key, no account: each paid request carries $0.01 in USDC on Base via the x402 payment protocol (v2, exact scheme). An unpaid request to a paid endpoint returns HTTP 402 with an accepts[] array describing the payment terms; x402 client libraries such as @x402/fetch handle payment automatically. 4xx responses are never charged. YouTube support is coming soon. Built by FindClout, the biggest independently owned American meme page network, spanning sports, finance, entrepreneurship, movies, TV, and music: findclout.com.",
    "contact": {
      "name": "FindClout",
      "url": "https://findclout.com"
    }
  },
  "servers": [
    { "url": "https://x402.findclout.com" }
  ],
  "paths": {
    "/api/v1/post": {
      "get": {
        "operationId": "getPostStats",
        "summary": "Universal post stats by URL (Instagram, TikTok, or X)",
        "description": "Detects the platform from the URL hostname (instagram.com, tiktok.com, twitter.com or x.com) and returns live stats. Costs $0.01, paid via x402. The followers field is included when the platform provides it on post lookups (TikTok and X).",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "Full public post URL from Instagram, TikTok, or X",
            "schema": { "type": "string", "format": "uri" }
          }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/PostStats200" },
          "400": { "$ref": "#/components/responses/BadRequest400" },
          "402": { "$ref": "#/components/responses/PaymentRequired402" },
          "502": { "$ref": "#/components/responses/UpstreamError502" }
        }
      }
    },
    "/api/v1/instagram/post": {
      "get": {
        "operationId": "getInstagramPostStats",
        "summary": "Instagram post, reel, or IGTV stats",
        "description": "Returns views, likes, and comments for a public Instagram post. Provide either url or code. Photo posts return views: null. shares is always 0 on Instagram. Costs $0.01, paid via x402.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": false,
            "description": "Instagram URL containing /p/, /reel/, /reels/, or /tv/",
            "schema": { "type": "string", "format": "uri" }
          },
          {
            "name": "code",
            "in": "query",
            "required": false,
            "description": "The Instagram shortcode directly, e.g. DLmR4kXtQ2a",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/PostStats200" },
          "400": { "$ref": "#/components/responses/BadRequest400" },
          "402": { "$ref": "#/components/responses/PaymentRequired402" },
          "502": { "$ref": "#/components/responses/UpstreamError502" }
        }
      }
    },
    "/api/v1/instagram/user": {
      "get": {
        "operationId": "getInstagramUser",
        "summary": "Instagram public profile by username",
        "description": "Returns the full public profile: followers, following, post count, verification, privacy flag, biography, and profile picture URL. Costs $0.01, paid via x402.",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "description": "Instagram handle without the @",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Profile stats. Charged $0.01. May also be a charged not_found result when the lookup ran but the user does not exist or is private.",
            "headers": {
              "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/InstagramUser" },
                    { "$ref": "#/components/schemas/NotFound" }
                  ]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest400" },
          "402": { "$ref": "#/components/responses/PaymentRequired402" },
          "502": { "$ref": "#/components/responses/UpstreamError502" }
        }
      }
    },
    "/api/v1/tiktok/post": {
      "get": {
        "operationId": "getTiktokPostStats",
        "summary": "TikTok video stats with author follower count",
        "description": "Returns views, likes, comments, shares, the author handle, and the author's follower count for a public TikTok video. Costs $0.01, paid via x402.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "Full TikTok video URL",
            "schema": { "type": "string", "format": "uri" }
          }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/PostStats200" },
          "400": { "$ref": "#/components/responses/BadRequest400" },
          "402": { "$ref": "#/components/responses/PaymentRequired402" },
          "502": { "$ref": "#/components/responses/UpstreamError502" }
        }
      }
    },
    "/api/v1/x/post": {
      "get": {
        "operationId": "getXPostStats",
        "summary": "X (Twitter) post stats with author follower count",
        "description": "Returns views, likes, comments (replies), shares (retweets), the author handle, and the author's follower count for a public X post. Provide either url or id. Costs $0.01, paid via x402.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": false,
            "description": "Full status URL on x.com or twitter.com",
            "schema": { "type": "string", "format": "uri" }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "The numeric tweet ID directly",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/PostStats200" },
          "400": { "$ref": "#/components/responses/BadRequest400" },
          "402": { "$ref": "#/components/responses/PaymentRequired402" },
          "502": { "$ref": "#/components/responses/UpstreamError502" }
        }
      }
    },
    "/api/v1/pricing": {
      "get": {
        "operationId": "getPricing",
        "summary": "Pricing and payment details (free)",
        "description": "Free JSON describing the paid endpoints, price, network, payment address, facilitator, and USDC asset address.",
        "responses": {
          "200": {
            "description": "Pricing information",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Pricing" }
              }
            }
          }
        }
      }
    },
    "/healthz": {
      "get": {
        "operationId": "getHealth",
        "summary": "Liveness check (free)",
        "responses": {
          "200": {
            "description": "Service is up",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Health" },
                "example": { "ok": true, "service": "x402-social-api", "network": "eip155:8453" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "PaymentRequired": {
        "description": "x402 payment challenge header accompanying the 402 response",
        "schema": { "type": "string" }
      },
      "PaymentResponse": {
        "description": "x402 settlement receipt for the payment that funded this request, including the transaction reference on Base",
        "schema": { "type": "string" }
      }
    },
    "responses": {
      "PostStats200": {
        "description": "Post stats. Charged $0.01. May also be a charged not_found result when the lookup ran but the post does not exist or is private.",
        "headers": {
          "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" }
        },
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                { "$ref": "#/components/schemas/PostStats" },
                { "$ref": "#/components/schemas/NotFound" }
              ]
            },
            "example": {
              "success": true,
              "platform": "tiktok",
              "fetchedAt": "2026-07-19T14:05:56.000Z",
              "url": "https://www.tiktok.com/@nflstreetmoments/video/7401882236711",
              "username": "nflstreetmoments",
              "views": 4102338,
              "likes": 512004,
              "comments": 3912,
              "shares": 21480,
              "followers": 1306700
            }
          }
        }
      },
      "BadRequest400": {
        "description": "Missing, malformed, or unsupported parameters. Rejected before any lookup runs. Never charged.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "example": { "success": false, "error": "invalid_url" }
          }
        }
      },
      "PaymentRequired402": {
        "description": "No valid x402 payment was attached. This is the payment challenge, not an error, and it is never charged. The accepts array lists acceptable payment terms; sign an EIP-3009 USDC transfer authorization matching one entry and retry the request with the payment attached. Client libraries such as @x402/fetch do this automatically.",
        "headers": {
          "PAYMENT-REQUIRED": { "$ref": "#/components/headers/PaymentRequired" }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/PaymentRequiredBody" },
            "example": {
              "x402Version": 2,
              "error": "Payment required",
              "accepts": [
                {
                  "scheme": "exact",
                  "network": "eip155:8453",
                  "maxAmountRequired": "10000",
                  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                  "payTo": "0xD5997d52769Fc6abd86B0E6d0f0e85F31F118bd8",
                  "resource": "https://x402.findclout.com/api/v1/post",
                  "description": "Social post stats lookup",
                  "mimeType": "application/json",
                  "maxTimeoutSeconds": 60
                }
              ]
            }
          }
        }
      },
      "UpstreamError502": {
        "description": "Our data infrastructure failed or timed out. Never charged. Retry with backoff.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "example": { "success": false, "error": "upstream_error" }
          }
        }
      }
    },
    "schemas": {
      "PostStats": {
        "type": "object",
        "description": "Live stats for a social media post. Numeric fields are integers or null when the platform does not expose the metric.",
        "required": ["success", "platform", "fetchedAt", "url", "username", "views", "likes", "comments", "shares"],
        "properties": {
          "success": { "type": "boolean", "const": true },
          "platform": { "type": "string", "enum": ["instagram", "tiktok", "x"] },
          "fetchedAt": { "type": "string", "format": "date-time", "description": "Timestamp of the live lookup, ISO 8601" },
          "url": { "type": "string", "format": "uri" },
          "username": { "type": ["string", "null"], "description": "Author handle" },
          "views": { "type": ["integer", "null"], "description": "View or play count. Null for Instagram photo posts." },
          "likes": { "type": ["integer", "null"] },
          "comments": { "type": ["integer", "null"], "description": "Comment count. Maps to replies on X." },
          "shares": { "type": ["integer", "null"], "description": "Share count. Maps to retweets on X. Always 0 on Instagram." },
          "followers": { "type": ["integer", "null"], "description": "Author follower count at fetch time. Present for TikTok and X post lookups." }
        }
      },
      "InstagramUser": {
        "type": "object",
        "description": "Public Instagram profile stats.",
        "required": ["success", "platform", "fetchedAt", "username", "followers", "following", "posts", "isVerified", "isPrivate"],
        "properties": {
          "success": { "type": "boolean", "const": true },
          "platform": { "type": "string", "const": "instagram" },
          "fetchedAt": { "type": "string", "format": "date-time" },
          "username": { "type": "string" },
          "fullName": { "type": ["string", "null"] },
          "followers": { "type": ["integer", "null"] },
          "following": { "type": ["integer", "null"] },
          "posts": { "type": ["integer", "null"], "description": "Total media count" },
          "isVerified": { "type": "boolean" },
          "isPrivate": { "type": "boolean" },
          "biography": { "type": ["string", "null"] },
          "profilePicUrl": { "type": ["string", "null"], "format": "uri" }
        }
      },
      "NotFound": {
        "type": "object",
        "description": "The lookup ran but the post or user does not exist or is not publicly visible. This response is charged: the work was performed and this is the answer.",
        "required": ["success", "error"],
        "properties": {
          "success": { "type": "boolean", "const": false },
          "error": { "type": "string", "const": "not_found" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["success", "error"],
        "properties": {
          "success": { "type": "boolean", "const": false },
          "error": { "type": "string" }
        }
      },
      "PaymentRequiredBody": {
        "type": "object",
        "description": "x402 v2 payment challenge body.",
        "required": ["x402Version", "accepts"],
        "properties": {
          "x402Version": { "type": "integer", "const": 2 },
          "error": { "type": "string" },
          "accepts": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/PaymentTerms" }
          }
        }
      },
      "PaymentTerms": {
        "type": "object",
        "description": "One acceptable way to pay for the request.",
        "required": ["scheme", "network", "maxAmountRequired", "asset", "payTo", "resource"],
        "properties": {
          "scheme": { "type": "string", "const": "exact" },
          "network": { "type": "string", "const": "eip155:8453", "description": "Base mainnet, CAIP-2" },
          "maxAmountRequired": { "type": "string", "const": "10000", "description": "Atomic USDC units. 10000 units = $0.01 (USDC has 6 decimals)." },
          "asset": { "type": "string", "const": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "description": "USDC contract on Base" },
          "payTo": { "type": "string", "const": "0xD5997d52769Fc6abd86B0E6d0f0e85F31F118bd8" },
          "resource": { "type": "string", "format": "uri" },
          "description": { "type": "string" },
          "mimeType": { "type": "string" },
          "maxTimeoutSeconds": { "type": "integer" }
        }
      },
      "Pricing": {
        "type": "object",
        "description": "Free pricing and payment metadata.",
        "properties": {
          "price": { "type": "string", "example": "$0.01" },
          "network": { "type": "string", "example": "eip155:8453" },
          "payTo": { "type": "string", "example": "0xD5997d52769Fc6abd86B0E6d0f0e85F31F118bd8" },
          "facilitator": { "type": "string", "example": "https://facilitator.payai.network" },
          "asset": { "type": "string", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
          "endpoints": {
            "type": "array",
            "items": { "type": "string" },
            "example": [
              "/api/v1/post",
              "/api/v1/instagram/post",
              "/api/v1/instagram/user",
              "/api/v1/tiktok/post",
              "/api/v1/x/post"
            ]
          }
        }
      },
      "Health": {
        "type": "object",
        "required": ["ok", "service", "network"],
        "properties": {
          "ok": { "type": "boolean" },
          "service": { "type": "string" },
          "network": { "type": "string" }
        }
      }
    }
  }
}