Agentic Endpoints X402 API

openapi: 3.2.0
info:
  title: agentic-endpoints X402 API
  version: 1.0.0
  license:
    name: MIT
    identifier: MIT
  description: 'Pay-per-call utilities for autonomous agents. No signup, no API keys, no invoices: every endpoint answers HTTP 402 with a price and serves the request once payment is signed.'
servers:
- url: https://agentic-endpoints.com
tags:
- name: X402
paths:
  /x402/verify:
    post:
      summary: Before paying a stranger's x402 endpoint, read its live payment challenge and…
      description: Before paying a stranger's x402 endpoint, read its live payment challenge and compare it against every previous observation. Flags a changed receiving address, network or asset as critical drift. Reports what the endpoint declares; it does not certify the operator.. Costs $0.010, paid per call with x402 (USDC on Base), or debited from a prepaid balance by sending an X-Credit-Token header.
      operationId: x402_verify
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: Public HTTP(S) URL of the paid endpoint. Private and loopback addresses are refused, not fetched.
                method:
                  type: string
                  description: 'Method used to provoke the challenge: POST (default), GET or HEAD'
                expect:
                  type: object
                  description: Optional. What you believe to be true, typically from a directory listing. Mismatches are reported so you can trust the live challenge over the listing.
                  properties:
                    pay_to:
                      type: string
                      description: Address you expect to pay
                    network:
                      type: string
                      description: Chain you expect. A name like 'base' and its CAIP-2 form 'eip155:8453' are treated as the same chain.
                    asset:
                      type: string
                      description: Token contract address
                    max_price_usd:
                      type: number
                      description: Refuse-above threshold in USD
              required:
              - url
            example:
              url: https://example.com/api/thing
              expect:
                pay_to: 0x...
                max_price_usd: 0.01
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                status: ok
                url: https://example.com/api/thing
                reachable: true
                charges:
                  pay_to: '0x0000000000000000000000000000000000000000'
                  amount: '10000'
                  asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                  network: eip155:8453
                  scheme: exact
                  price_usd: '0.01'
                first_seen: '2025-01-01T00:00:00.000Z'
                last_seen: '2025-01-08T00:00:00.000Z'
                times_seen: 14
                first_observation: false
                drift: []
                advice: This reports only what the endpoint declares about itself. It is not a judgement that the operator will deliver anything.
        '402':
          description: Payment required. The body names the price and all three ways to pay, including the free trial that needs no wallet. The `payment-required` response header carries the same challenge base64-encoded, which is where x402 v2 clients read it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
        '429':
          description: Rate limited.
      security:
      - creditToken: []
      - x402Payment: []
      - {}
      tags:
      - X402
components:
  schemas:
    PaymentRequired:
      type: object
      description: Body of a 402. Every field is derived from the same challenge the caller is asked to sign, so it cannot quote a different price or recipient.
      properties:
        error:
          type: string
          const: payment_required
        price:
          type: string
          description: List price in dollars, e.g. $0.005
        resource:
          type: string
          description: The URL being charged for
        ways_to_pay:
          type: object
          description: The three routes in, cheapest first. free_trial needs no wallet, no signature, no account and no email.
          properties:
            free_trial:
              type: object
            prepaid_credit:
              type: object
            per_call_x402:
              type: object
        accepts:
          type: array
          description: The x402 challenge, echoed here for v1 clients that read it from the body rather than the payment-required header.
          items:
            type: object
        x402Version:
          type: number
      required:
      - error
      - ways_to_pay
  securitySchemes:
    creditToken:
      type: apiKey
      in: header
      name: X-Credit-Token
      description: A prepaid or trial balance. Get one free with no wallet and no account at POST https://agentic-endpoints.com/credits/trial, or buy credit at POST https://agentic-endpoints.com/credits/buy. Each call is debited at the route's list price and nothing is signed per request.
    x402Payment:
      type: apiKey
      in: header
      name: X-PAYMENT
      description: A signed x402 payment authorising this one call, built from the challenge returned with HTTP 402. Requires a funded wallet on Base; the credit token does not.