{
  "openapi": "3.1.0",
  "info": {
    "title": "Crypt0's News agent API, x402 paywall",
    "version": "1.0.0",
    "description": "Pay-per-call crypto data API. AI agents pay per endpoint in USDC on Base through the x402 protocol: 402 challenge, sign, retry with X-PAYMENT, facilitator verifies and settles, server returns JSON with a receipt. Buyer to treasury, zero human friction, no account required. Human overview at /agents.html, discovery at /.well-known/x402.json."
  },
  "servers": [
    {
      "url": "https://crypt0snews.com"
    }
  ],
  "paths": {
    "/api/x402/archive": {
      "get": {
        "summary": "Archive index, public video catalogue, JSON",
        "description": "Archive index, public video catalogue, JSON. Machine-payable: call unpaid to receive HTTP 402 with x402 payment requirements, pay 0.10 USDC on Base (6 decimals, amount 100000) and retry with the X-PAYMENT header. No account, no signup, no human anywhere.",
        "x-x402-payment": {
          "scheme": "exact",
          "asset": "USDC",
          "network": "base",
          "amount": "100000",
          "amountUsd": "0.10"
        },
        "responses": {
          "200": {
            "description": "Paid resource payload (JSON)"
          },
          "402": {
            "description": "Payment required, x402 settlement instructions in response headers"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            },
            "description": "Unknown path under /api/x402/*. Fix the URL; do not pay."
          }
        }
      }
    },
    "/api/x402/brief": {
      "get": {
        "summary": "Daily brief feed \u2014 the 3 latest published stories, JSON",
        "description": "Daily brief feed \u2014 the 3 latest published stories, JSON. Machine-payable: call unpaid to receive HTTP 402 with x402 payment requirements, pay 0.02 USDC on Base (6 decimals, amount 20000) and retry with the X-PAYMENT header. No account, no signup, no human anywhere.",
        "x-x402-payment": {
          "scheme": "exact",
          "asset": "USDC",
          "network": "base",
          "amount": "20000",
          "amountUsd": "0.02"
        },
        "responses": {
          "200": {
            "description": "Paid resource payload (JSON)"
          },
          "402": {
            "description": "Payment required, x402 settlement instructions in response headers"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            },
            "description": "Unknown path under /api/x402/*. Fix the URL; do not pay."
          }
        }
      }
    },
    "/api/x402/search-index": {
      "get": {
        "summary": "Full site search index, JSON",
        "description": "Full site search index, JSON. Machine-payable: call unpaid to receive HTTP 402 with x402 payment requirements, pay 0.05 USDC on Base (6 decimals, amount 50000) and retry with the X-PAYMENT header. No account, no signup, no human anywhere.",
        "x-x402-payment": {
          "scheme": "exact",
          "asset": "USDC",
          "network": "base",
          "amount": "50000",
          "amountUsd": "0.05"
        },
        "responses": {
          "200": {
            "description": "Paid resource payload (JSON)"
          },
          "402": {
            "description": "Payment required, x402 settlement instructions in response headers"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            },
            "description": "Unknown path under /api/x402/*. Fix the URL; do not pay."
          }
        }
      }
    },
    "/api/x402/headlines": {
      "get": {
        "description": "Today's headlines teaser, free, JSON. No payment, no account, no X-PAYMENT header. Titles and sections only, never full story bodies; the same stories, order, and day as the paid brief feed it points to. Use it to confirm the feed is real before paying. Paid upgrade: GET /api/x402/headlines-full ($0.01) adds sections, counts, urls, and dates; GET /api/x402/brief ($0.02) is the full brief.",
        "responses": {
          "200": {
            "description": "Free teaser payload (JSON): source, date, headlines array of {section, title}, fullBrief pointer ($0.02 brief with endpoint, priceAtomic 20000, payTo), otherCalls pointers, discovery pointer to /.well-known/x402.json"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            },
            "description": "Unknown path under /api/x402/*. Fix the URL; do not pay. The free teaser never returns 402."
          },
          "502": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceUnavailableError"
                }
              }
            },
            "description": "The free teaser could not be built because fetching /api/v1/news.json failed or the teaser build returned nothing. Retry later; never pay for the teaser, it takes no payment."
          }
        },
        "summary": "Today's headlines teaser, free, JSON"
      }
    },
    "/api/x402/headlines-full": {
      "get": {
        "description": "Full day's headlines, JSON. Machine-payable: call unpaid to receive HTTP 402 with x402 payment requirements, pay 0.01 USDC on Base (6 decimals, amount 10000) and retry with the X-PAYMENT header. No account, no signup, no human anywhere. One price, no query parameters: the whole day's headlines in one call.",
        "responses": {
          "200": {
            "description": "Paid resource payload (JSON) with receipt: headlines array of {title, section (crypto, finance, ai, singularity, gaming), url, published date}, counts per section, next pointers to paid upgrades (brief $0.02, topic-brief $0.02, search $0.03), paid block and 50/50 split block with txHash and payer"
          },
          "402": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/X402ErrorField"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Payment required, x402 settlement instructions in response headers"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            },
            "description": "Unknown path under /api/x402/*. Fix the URL; do not pay."
          }
        },
        "summary": "Full day's headlines, JSON",
        "x-x402-payment": {
          "amount": "10000",
          "amountUsd": "0.01",
          "asset": "USDC",
          "network": "base",
          "scheme": "exact"
        }
      }
    },
    "/api/x402/legend-brief": {
      "get": {
        "responses": {
          "402": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/X402ErrorField"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Payment required, or the presented payment / query failed. Query failures surface here as 402, never 400: a missing ?legend= returns error 'missing_query: ?legend= is required'. Other failures use the X402ErrorField examples."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            },
            "description": "Unknown path under /api/x402/*. Fix the URL; do not pay."
          }
        }
      }
    },
    "/api/x402/on-this-day": {
      "get": {
        "responses": {
          "402": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/X402ErrorField"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Payment required, or the presented payment / resource failed. No on-this-day feed file ships yet, so paid calls currently fail closed with error 'resource_unavailable' and nothing is settled. Other failures use the X402ErrorField examples."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            },
            "description": "Unknown path under /api/x402/*. Fix the URL; do not pay."
          }
        }
      }
    },
    "/api/x402/search": {
      "get": {
        "responses": {
          "402": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/X402ErrorField"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Payment required, or the presented payment / query failed. Query failures surface here as 402, never 400: a missing ?q= returns error 'missing_query: ?q= is required'. Other failures use the X402ErrorField examples."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            },
            "description": "Unknown path under /api/x402/*. Fix the URL; do not pay."
          }
        }
      }
    },
    "/api/x402/topic-brief": {
      "get": {
        "responses": {
          "402": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/X402ErrorField"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Payment required, or the presented payment / query failed. Query failures surface here as 402, never 400: a missing or out-of-enum ?topic= returns error 'invalid_topic: topic must be one of crypto, finance, ai, singularity, gaming'. Other failures use the X402ErrorField examples."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            },
            "description": "Unknown path under /api/x402/*. Fix the URL; do not pay."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ArchiveIndexResource": {
        "description": "Archive index as built by agent_refresh.py: public video catalogue envelope.",
        "properties": {
          "count": {
            "type": "integer"
          },
          "entries": {
            "items": {
              "properties": {
                "duration": {
                  "type": "string"
                },
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "watch_url": {
                  "format": "uri",
                  "type": "string"
                }
              },
              "required": [
                "id",
                "title"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "source": {
            "type": "string"
          }
        },
        "required": [
          "source",
          "count",
          "entries"
        ],
        "type": "object"
      },
      "BriefFeedResource": {
        "description": "Daily Brief feed envelope as built by build_api_feed.py: versioned, newest first.",
        "properties": {
          "articles": {
            "items": {
              "properties": {
                "category": {
                  "type": "string"
                },
                "published": {
                  "type": "string"
                },
                "summary": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "url": {
                  "format": "uri",
                  "type": "string"
                }
              },
              "required": [
                "title",
                "url"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "count": {
            "type": "integer"
          },
          "docs": {
            "format": "uri",
            "type": "string"
          },
          "generated_at": {
            "format": "date-time",
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "version": {
            "example": "v1",
            "type": "string"
          }
        },
        "required": [
          "version",
          "generated_at",
          "count",
          "articles"
        ],
        "type": "object"
      },
      "NotFoundError": {
        "description": "Body returned with HTTP 404 for any /api/x402/* path the function does not route: a single string field, exactly 'not_found'. No payment is involved and no 402 precedes it; fix the URL, do not pay. Applies to all nine documented routes as the unmatched-path response.",
        "properties": {
          "error": {
            "const": "not_found",
            "type": "string"
          }
        },
        "required": [
          "error"
        ],
        "type": "object"
      },
      "ResourceUnavailableError": {
        "description": "Body returned with HTTP 502 ONLY on the free headlines teaser GET /api/x402/headlines, when fetching /api/v1/news.json fails or the teaser cannot be built: a single string field, exactly 'resource_unavailable'. The teaser is free, so a 502 never implies a payment problem; retry later. Paid routes never return 502: a resource failure on a paid route is a 402 whose error field is 'resource_unavailable' instead, so the payment is never settled without a payload.",
        "properties": {
          "error": {
            "const": "resource_unavailable",
            "type": "string"
          }
        },
        "required": [
          "error"
        ],
        "type": "object"
      },
      "SearchIndexResource": {
        "description": "Full site search index as built by build_search.py: a flat array, one entry per guide, term, FAQ, timeline event, whitepaper, article, and page.",
        "items": {
          "properties": {
            "t": {
              "description": "Entry kind: Guide, Term, FAQ, Timeline, Whitepaper, Article, or Page.",
              "type": "string"
            },
            "text": {
              "type": "string"
            },
            "title": {
              "type": "string"
            },
            "url": {
              "format": "uri",
              "type": "string"
            }
          },
          "required": [
            "t",
            "title",
            "url",
            "text"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "X402Challenge": {
        "description": "HTTP 402 challenge body as produced by x402-api-v2.js challenge(). The same challenge is also carried base64-encoded in the PAYMENT-REQUIRED response header as the x402 v2 envelope, with PAYMENT-CHANNEL: x402.",
        "properties": {
          "accepts": {
            "items": {
              "properties": {
                "asset": {
                  "description": "USDC contract on Base.",
                  "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "extra": {
                  "properties": {
                    "name": {
                      "example": "USDC",
                      "type": "string"
                    },
                    "version": {
                      "example": "2",
                      "type": "string"
                    }
                  },
                  "type": "object"
                },
                "maxAmountRequired": {
                  "type": "string"
                },
                "maxTimeoutSeconds": {
                  "example": 300,
                  "type": "integer"
                },
                "mimeType": {
                  "example": "application/json",
                  "type": "string"
                },
                "network": {
                  "example": "eip155:8453",
                  "type": "string"
                },
                "payTo": {
                  "example": "0xcA351D97d085762E62535942A1B2E6E52eEA0968",
                  "type": "string"
                },
                "resource": {
                  "format": "uri",
                  "type": "string"
                },
                "scheme": {
                  "example": "exact",
                  "type": "string"
                }
              },
              "required": [
                "scheme",
                "network",
                "maxAmountRequired",
                "resource",
                "description",
                "mimeType",
                "payTo",
                "maxTimeoutSeconds",
                "asset"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "error": {
            "description": "Present only when the challenge carries a failure reason, for example wrong_payee, underpaid, invalid_topic, missing_query, resource_unavailable, or a facilitator verify/settle failure. Unpaid first calls carry no error field.",
            "type": "string"
          },
          "resource": {
            "format": "uri",
            "type": "string"
          },
          "x402Version": {
            "example": 2,
            "type": "integer"
          }
        },
        "required": [
          "x402Version",
          "resource",
          "accepts"
        ],
        "type": "object"
      },
      "X402ErrorField": {
        "description": "The `error` field of a 402 challenge body, as produced by the live x402-api.js challenge(). It is a single string: a stable reason prefix, a colon, and a human-readable detail. The prefix is the machine-readable code; the detail after the colon varies per call (for example underpaid carries the amounts). An unpaid first call carries NO error field at all; the field appears only when a presented payment, a query, or a downstream step failed. No payment is taken on any 402: verify and settle run only after the local checks pass, and a 402 means nothing was settled. Retry guidance per prefix: fix-and-resign (new X-PAYMENT) for malformed_payment_header, wrong_payee, wrong_asset, underpaid, invalid_topic, missing_query; sign a NEW payment for already_settled (the presented payment was already consumed by an earlier call that returned its 200, so re-presenting it can never succeed); retry later with a fresh authorization for verify_unavailable, payment_rejected, resource_unavailable, settle_unavailable, settlement_failed, handler_error.",
        "examples": [
          "malformed_payment_header: not base64 JSON",
          "malformed_payment_header: missing authorization or signature",
          "malformed_payment_header: bad authorization.to",
          "wrong_payee: authorization.to is not the treasury payTo",
          "wrong_asset: payment is not USDC on Base",
          "underpaid: 1000 < 20000 atomic",
          "invalid_topic: topic must be one of crypto, finance, ai, singularity, gaming",
          "missing_query: ?q= is required",
          "missing_query: ?legend= is required",
          "already_settled: this payment was already used",
          "verify_unavailable: facilitator unreachable",
          "payment_rejected: facilitator /verify failed",
          "resource_unavailable",
          "settle_unavailable: facilitator unreachable",
          "settlement_failed: no transaction hash",
          "handler_error: fail closed"
        ],
        "type": "string"
      },
      "X402Receipt": {
        "description": "Settlement receipt carried in every paid 200 body, as built by the x402 function record: the 50/50 treasury split is payerShareUsd and auroraShareUsd, each half of the endpoint price.",
        "properties": {
          "asset": {
            "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
            "type": "string"
          },
          "atomic": {
            "type": "string"
          },
          "auroraShareUsd": {
            "type": "number"
          },
          "description": {
            "type": "string"
          },
          "endpoint": {
            "type": "string"
          },
          "network": {
            "example": "eip155:8453",
            "type": "string"
          },
          "payTo": {
            "example": "0xcA351D97d085762E62535942A1B2E6E52eEA0968",
            "type": "string"
          },
          "payer": {
            "description": "Paying wallet address, or null when unavailable.",
            "type": [
              "string",
              "null"
            ]
          },
          "payerShareUsd": {
            "type": "number"
          },
          "rail": {
            "example": "x402-api-micropayments",
            "type": "string"
          },
          "txHash": {
            "type": "string"
          },
          "usd": {
            "type": "number"
          }
        },
        "required": [
          "rail",
          "endpoint",
          "usd",
          "atomic",
          "asset",
          "network",
          "payTo",
          "txHash",
          "payerShareUsd",
          "auroraShareUsd"
        ],
        "type": "object"
      }
    }
  }
}