openapi: 3.1.0
info:
  title: arXiv MCP (x402)
  version: 0.1.0
  description: |
    Pay-per-call x402 endpoints for arXiv. Full-text metadata search and
    per-id resolution across every STEM preprint. No signup, no API key —
    pay USDC on Base. Each first call returns HTTP 402 with an x402
    envelope; sign X-PAYMENT and retry.
  contact:
    name: Money Tree
    url: https://arxiv-mcp.mtree.workers.dev/agent-discovery
    email: money-tree@mtree.workers.dev
servers:
  - url: https://arxiv-mcp.mtree.workers.dev
x-pricing:
  - path: /v1/papers/search
    method: POST
    price: $0.04
    amount: "0.04"
    asset: USDC
    network: base
  - path: /v1/papers/by_id
    method: POST
    price: $0.05
    amount: "0.05"
    asset: USDC
    network: base
paths:
  /v1/papers/search:
    post:
      operationId: papersSearch
      summary: Full-text metadata search across arXiv preprints
      description: |
        $0.04/call. Search every arXiv preprint by free-text query, title,
        author(s), category, and submitted-date range. Sort by relevance,
        lastUpdatedDate, or submittedDate.
      requestBody:
        required: false
        content:
          application/json:
            example:
              query: "retrieval augmented generation"
              categories: "cs.CL,cs.LG"
              fromDays: 365
              sortBy: "submittedDate"
              sortOrder: "descending"
              limit: 10
            examples:
              agent_request:
                summary: Agent-ready paid request example
                value:
                  query: "retrieval augmented generation"
                  categories: "cs.CL,cs.LG"
                  fromDays: 365
                  sortBy: "submittedDate"
                  sortOrder: "descending"
                  limit: 10
            schema:
              type: object
              additionalProperties: false
              properties:
                query:
                  type: string
                  description: Free-text query (optional if title/authors/categories supplied)
                  example: "transformer architecture attention mechanism"
                title:
                  type: string
                  description: Title-only query (combined with query via AND)
                  example: "retrieval augmented generation"
                authors:
                  type: string
                  description: Comma-separated author names — OR-matched
                  example: "Yoshua Bengio,Yann LeCun"
                categories:
                  type: string
                  description: Comma-separated arXiv categories — OR-matched
                  example: "cs.CL,cs.LG"
                fromDays:
                  type: number
                  description: Look back N days on submittedDate (1–3650)
                  example: 365
                startDate:
                  type: string
                  description: Submitted-date start YYYY-MM-DD (overrides fromDays)
                  example: "2024-01-01"
                endDate:
                  type: string
                  description: Submitted-date end YYYY-MM-DD
                  example: "2024-12-31"
                sortBy:
                  type: string
                  description: relevance | lastUpdatedDate | submittedDate
                  example: "submittedDate"
                sortOrder:
                  type: string
                  description: ascending | descending
                  example: "descending"
                limit:
                  type: number
                  description: Max results (1–50)
                  example: 25
      responses:
        "200":
          description: Search results
          content:
            application/json:
              example:
                ok: true
                service: arxiv-mcp
                endpoint: /v1/papers/search
                count: 1
                papers:
                  - id: "2401.12345"
                    title: Retrieval-Augmented Generation for Example Agents
                    authors: [Ada Lovelace]
                    summary: Abstract text returned from arXiv metadata.
                    categories: [cs.CL]
                    published: "2024-01-15T00:00:00Z"
                    links:
                      abs: https://arxiv.org/abs/2401.12345
                      pdf: https://arxiv.org/pdf/2401.12345
                provenance:
                  source: arxiv.org
                  fetched_at: "2026-05-22T00:00:00Z"
        "402":
          description: x402 payment required
        "502":
          description: arXiv upstream error
  /v1/papers/by_id:
    post:
      operationId: papersById
      summary: Resolve papers by arXiv id
      description: |
        $0.05/call. Resolve one or more arXiv papers by id. Accepts modern
        ("2401.12345", "2401.12345v2") and old-style ("cs.CL/9912001")
        ids; "arXiv:" prefix and full abs/pdf URLs are normalised.
      requestBody:
        required: true
        content:
          application/json:
            example:
              ids: "2401.12345,2310.06825,cs.CL/9912001"
            examples:
              agent_request:
                summary: Agent-ready paid request example
                value:
                  ids: "2401.12345,2310.06825,cs.CL/9912001"
            schema:
              type: object
              additionalProperties: false
              properties:
                id:
                  type: string
                  description: Single arXiv id
                  example: "2401.12345"
                ids:
                  type: string
                  description: Comma-separated list (max 50)
                  example: "2401.12345,2310.06825,cs.CL/9912001"
      responses:
        "200":
          description: Paper metadata
          content:
            application/json:
              example:
                ok: true
                service: arxiv-mcp
                endpoint: /v1/papers/by_id
                papers:
                  - id: "2401.12345"
                    title: Example Research Paper
                    authors: [Ada Lovelace, Alan Turing]
                    summary: Abstract text returned from arXiv metadata.
                    categories: [cs.CL, cs.LG]
                    published: "2024-01-15T00:00:00Z"
                    updated: "2024-02-01T00:00:00Z"
                    links:
                      abs: https://arxiv.org/abs/2401.12345
                      pdf: https://arxiv.org/pdf/2401.12345
                provenance:
                  source: arxiv.org
                  fetched_at: "2026-05-22T00:00:00Z"
        "402":
          description: x402 payment required
        "404":
          description: Id not found
        "502":
          description: arXiv upstream error
components:
  securitySchemes:
    x402:
      type: http
      scheme: x402
      description: |
        Pay-per-call via x402 (USDC on Base). On first request, the API
        returns HTTP 402 with an "accepts" array. Sign and submit X-PAYMENT
        to retry.
security:
  - x402: []
