cryptodataapi-com Payments API

openapi: 3.2.0
info:
  title: Crypto Data Payments API
  description: 'Real-time crypto market intelligence API. Built for AI agents: gasless USDC payments via x402 protocol, one-call onboarding, and 180+ endpoints for prices, derivatives, funding, and sentiment.'
  version: '2026-10-28'
servers:
- url: https://cryptodataapi.com
tags:
- name: Payments
  description: Subscription plans, x402 agent subscribe, and invoices.
paths:
  /api/v1/payments/plans:
    get:
      tags:
      - Payments
      summary: Get Plans
      description: Return plan pricing and supported networks. No auth required.
      operationId: get_plans_api_v1_payments_plans_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlansResponse'
  /api/v1/payments/subscribe:
    post:
      tags:
      - Payments
      summary: Subscribe
      description: 'Subscribe to a pro plan via x402 payment.


        Flow:

        1. If active subscription with >7 days remaining → return it (no charge).

        2. If no x-payment header → return 402 with payment options.

        3. If x-payment header → verify, settle, upgrade key, create subscription + invoice.'
      operationId: subscribe_api_v1_payments_subscribe_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscribeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /api/v1/payments/subscription:
    get:
      tags:
      - Payments
      summary: Get Subscription
      description: Return current subscription status.
      operationId: get_subscription_api_v1_payments_subscription_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionStatusResponse'
      security:
      - APIKeyHeader: []
  /api/v1/payments/invoices:
    get:
      tags:
      - Payments
      summary: List Invoices
      description: List all invoices for this API key's email.
      operationId: list_invoices_api_v1_payments_invoices_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceListResponse'
      security:
      - APIKeyHeader: []
  /api/v1/payments/invoices/{number}:
    get:
      tags:
      - Payments
      summary: Get Invoice
      description: Get a single invoice. JSON by default, ?format=html for printable, ?format=pdf for download.
      operationId: get_invoice_api_v1_payments_invoices__number__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: number
        in: path
        required: true
        schema:
          type: string
          title: Number
        example: INV-000001
      - name: format
        in: query
        required: false
        schema:
          type: string
          pattern: ^(json|html|pdf)$
          default: json
          title: Format
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-account-scoped: true
  /api/v1/payments/validate-code:
    post:
      tags:
      - Payments
      summary: Validate Code
      description: 'Validate a discount code and return what the first payment costs per plan.


        Codes apply to card and dashboard crypto checkout only — never to x402

        purchases. A bounded code is "percent_off for duration_months months": a

        monthly plan takes the full percentage on each of those months, and an

        annual plan takes those months'' share of it off the first year.


        Public (checkout UIs call it pre-auth). Every anonymous failure mode returns

        the identical `{"valid": false}` — unknown, inactive, expired, and exhausted

        are indistinguishable, and email binding is never revealed here (it

        surfaces only at pay time) — so codes can''t be enumerated or probed.


        With an `X-API-Key` header the answer is for that key''s account: `prices`

        and `duration_months` reflect the discounted months it has left, and a code

        its email or wallet has already used up returns `valid: false` with

        `reason: "already_used"`. The dashboard calls this right before an EVM

        wallet transfer, which is sent before the server ever sees the payment.

        Rate-limited per IP.'
      operationId: validate_code_api_v1_payments_validate_code_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateCodeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateCodeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/payments/agent-subscribe:
    post:
      tags:
      - Payments
      summary: Agent Subscribe (x402 Gasless Payment)
      description: 'Gasless one-shot onboarding for AI agents. Pay with USDC on Base via x402 -- no ETH gas needed.


        **How it works (2 HTTP calls):**


        1. **Call with no payment header** -- receive 402 with payment options (facilitator URL, price, networks).

        2. **Sign the USDC payment with your wallet** (off-chain EIP-712 signature, zero gas).

        3. **Call again with `x-payment` header** -- facilitator settles on-chain, you get an API key + PRO subscription.


        **Supported networks:** Base (USDC), Ethereum (USDC), Solana (USDC).

        Recommended: **Base** for lowest settlement cost.


        **Plans:**

        - Pro: monthly (real-time data, derivatives, on-chain analytics)

        - Pro Plus: monthly (adds quant/regime engine, historical data & Parquet downloads)

        Current pricing: the 402 response carries the exact USDC amount, or see https://cryptodataapi.com/pricing

        Always list price: discount codes are not accepted here (400) — they apply only to

        card or crypto checkout from the logged-in dashboard.


        **Key resolution on repeat calls:**

        - Include `X-API-Key` header to renew that key''s subscription.

        - No key header: looks up existing key by your wallet address, or creates a new one.

        - New API keys are returned **once** -- save it immediately.'
      operationId: agent_subscribe_api_v1_payments_agent_subscribe_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentSubscribeRequest'
        required: true
      responses:
        '200':
          description: API key and PRO subscription details
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/payments/stripe/checkout:
    post:
      tags:
      - Payments
      summary: Create Checkout
      description: Start a recurring card subscription. Returns a Stripe Checkout URL to redirect to.
      operationId: create_checkout_api_v1_payments_stripe_checkout_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StripeCheckoutRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StripeCheckoutResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /api/v1/payments/stripe/portal:
    post:
      tags:
      - Payments
      summary: Create Portal
      description: Open the Stripe Billing Portal (cancel / update card / invoice history).
      operationId: create_portal_api_v1_payments_stripe_portal_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StripePortalResponse'
      security:
      - APIKeyHeader: []
components:
  schemas:
    StripePortalResponse:
      properties:
        portal_url:
          type: string
          title: Portal Url
      type: object
      required:
      - portal_url
      title: StripePortalResponse
    SubscriptionStatusResponse:
      properties:
        status:
          type: string
          title: Status
        plan:
          title: Plan
          type:
          - string
          - 'null'
        expires_at:
          title: Expires At
          type:
          - string
          - 'null'
          format: date-time
        days_remaining:
          title: Days Remaining
          type:
          - integer
          - 'null'
        cancels_at:
          title: Cancels At
          type:
          - string
          - 'null'
          format: date-time
        renews_at:
          title: Renews At
          type:
          - string
          - 'null'
          format: date-time
        auto_renew:
          title: Auto Renew
          type:
          - boolean
          - 'null'
        payment_status:
          title: Payment Status
          type:
          - string
          - 'null'
      type: object
      required:
      - status
      title: SubscriptionStatusResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    InvoiceListResponse:
      properties:
        invoices:
          items:
            $ref: '#/components/schemas/InvoiceResponse'
          type: array
          title: Invoices
      type: object
      required:
      - invoices
      title: InvoiceListResponse
    ValidateCodeRequest:
      properties:
        code:
          type: string
          title: Code
      type: object
      required:
      - code
      title: ValidateCodeRequest
    StripeCheckoutResponse:
      properties:
        checkout_url:
          type: string
          title: Checkout Url
      type: object
      required:
      - checkout_url
      title: StripeCheckoutResponse
    InvoiceResponse:
      properties:
        invoice_number:
          type: string
          title: Invoice Number
        plan:
          type: string
          title: Plan
        amount_usd:
          type: number
          title: Amount Usd
        amount_usdc:
          type: number
          title: Amount Usdc
        network:
          type: string
          title: Network
        tx_hash:
          type: string
          title: Tx Hash
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - invoice_number
      - plan
      - amount_usd
      - amount_usdc
      - network
      - tx_hash
      - created_at
      title: InvoiceResponse
    StripeCheckoutRequest:
      properties:
        plan:
          type: string
          enum:
          - monthly
          - monthly_plus
          - annual
          - annual_plus
          title: Plan
        discount_code:
          title: Discount Code
          type:
          - string
          - 'null'
      type: object
      required:
      - plan
      title: StripeCheckoutRequest
      description: Start a Stripe Checkout session for a recurring card subscription.
    AgentSubscribeRequest:
      properties:
        plan:
          type: string
          enum:
          - monthly
          - monthly_plus
          - annual
          - annual_plus
          - pass_1h
          - pass_1d
          - pass_7d
          - pass_1h_plus
          - pass_1d_plus
          - pass_7d_plus
          title: Plan
        discount_code:
          title: Discount Code
          type:
          - string
          - 'null'
      type: object
      required:
      - plan
      title: AgentSubscribeRequest
      description: Request body for agent subscription (no API key required).
    SubscribeRequest:
      properties:
        plan:
          type: string
          enum:
          - monthly
          - monthly_plus
          - annual
          - annual_plus
          - pass_1h
          - pass_1d
          - pass_7d
          - pass_1h_plus
          - pass_1d_plus
          - pass_7d_plus
          title: Plan
        discount_code:
          title: Discount Code
          type:
          - string
          - 'null'
      type: object
      required:
      - plan
      title: SubscribeRequest
      description: Request body for subscribing to a plan.
    ValidateCodeResponse:
      properties:
        valid:
          type: boolean
          title: Valid
        percent_off:
          title: Percent Off
          type:
          - integer
          - 'null'
        duration_months:
          title: Duration Months
          type:
          - integer
          - 'null'
        prices:
          title: Prices
          additionalProperties:
            type: number
          type:
          - object
          - 'null'
        reason:
          title: Reason
          type:
          - string
          - 'null'
      type: object
      required:
      - valid
      title: ValidateCodeResponse
      description: 'Public validate response. Uniform {valid: false} for EVERY failure mode

        (unknown/inactive/expired/exhausted) so codes can''t be enumerated;

        for_email is never exposed — binding surfaces only at pay time.'
    PlansResponse:
      properties:
        plans:
          additionalProperties:
            $ref: '#/components/schemas/PlanInfo'
          type: object
          title: Plans
        networks:
          items:
            type: string
          type: array
          title: Networks
        token:
          type: string
          title: Token
          default: USDC
      type: object
      required:
      - plans
      - networks
      title: PlansResponse
    PlanInfo:
      properties:
        price_usd:
          type: number
          title: Price Usd
        price_usdc:
          type: string
          title: Price Usdc
        savings:
          title: Savings
          type:
          - string
          - 'null'
        tier:
          title: Tier
          type:
          - string
          - 'null'
      type: object
      required:
      - price_usd
      - price_usdc
      title: PlanInfo
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key