openapi: 3.0.3
info:
  title: 54ch10 Brief API
  description: 'Pre-interact JSON briefs for EVM addresses, tokens, and URLs (phishing/scam/wallet/URL-reputation
    heuristics). Analytics-only — not financial, legal, or investment advice. Canonical GET /v1/brief
    returns HTTP 402 + x402 PAYMENT-REQUIRED (USDC $0.01 Base preferred) unless Bearer 54k_ or PAYMENT-SIGNATURE.
    Demo free: X-54ch10-Free: 1 or GET /v1/brief/free (20/day/IP). Discovery: GET /.well-known/x402.'
  version: 0.4.1
  contact:
    name: 54ch10
    url: https://54ch10.uk
    email: brainpowerux@gmail.com
  license:
    name: Proprietary
    url: https://54ch10.uk/LEGAL_DISCLAIMER.txt
  x-apisguru-categories:
  - security
  - cryptocurrency
  x-logo:
    url: https://54ch10.uk/favicon.ico
  x-x402:
    discovery: https://54ch10.uk/.well-known/x402
    priceUsd: '0.01'
    networks:
    - eip155:8453
    - solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
    payToEvm: '0xF9eb0Caa13B78f92E2850bf5961eB9736354aA3d'
    payToSolana: EcGUGSda9VNzYgUmYA8mTg88MhNYeyA5tgaCgwzxfFNs
    facilitator: https://facilitator.payai.network
servers:
- url: https://54ch10.uk
  description: Production
paths:
  /v1/brief:
    get:
      operationId: getBrief
      summary: Pre-interact risk brief
      description: 'Returns score (0–100, higher = more concerning), band, flags, summary, and sources[].
        Live signals may include OpenPhish (URLs) and eth_getCode (EVM). Not clearance. Unauthenticated
        requests return HTTP 402 with x402 PAYMENT-REQUIRED (USDC $0.01). Paid retry: PAYMENT-SIGNATURE.
        Stripe: Bearer 54k_. Demo free: X-54ch10-Free: 1 or use /v1/brief/free.'
      parameters:
      - name: type
        in: query
        required: true
        schema:
          type: string
          enum:
          - address
          - token
          - url
      - name: q
        in: query
        required: true
        schema:
          type: string
          maxLength: 2048
        description: Address, token id, or URL to brief
      - name: X-54ch10-Pay
        in: header
        required: false
        schema:
          type: string
          enum:
          - x402
        description: Legacy force-challenge header (canonical /v1/brief already returns 402 unauthenticated)
      - name: X-54ch10-Free
        in: header
        required: false
        schema:
          type: string
          enum:
          - '1'
        description: Explicit human/demo free tier opt-in (20/UTC-day/IP). Indexers must NOT send this.
      - name: PAYMENT-SIGNATURE
        in: header
        required: false
        schema:
          type: string
        description: Base64-encoded x402 v2 PaymentPayload after client signs USDC authorization
      responses:
        '200':
          description: Brief JSON
          headers:
            PAYMENT-RESPONSE:
              description: Present when request was settled via x402
              schema:
                type: string
            X-54ch10-Tier:
              schema:
                type: string
                enum:
                - free
                - pro
                - x402
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  type:
                    type: string
                  q:
                    type: string
                  score:
                    type: number
                  band:
                    type: string
                    enum:
                    - clear
                    - caution
                    - elevated
                    - critical
                    - unknown
                  flags:
                    type: array
                    items:
                      type: string
                  summary:
                    type: string
                  sources:
                    type: array
                    items:
                      type: object
                  tier:
                    type: string
                    enum:
                    - free
                    - pro
                    - x402
                  disclaimer:
                    type: string
        '401':
          description: Invalid API key
        '402':
          description: 'Payment Required (x402) — default for unauthenticated /v1/brief. Decode PAYMENT-REQUIRED
            (base64 JSON) for accepts[] and extensions.bazaar. Or Bearer 54k_ / X-54ch10-Free: 1 / /v1/brief/free.'
          headers:
            PAYMENT-REQUIRED:
              description: Base64-encoded x402 v2 PaymentRequired
              schema:
                type: string
        '429':
          description: Free tier rate limited (only if x402 disabled)
      security:
      - {}
      - bearerAuth: []
  /v1/brief/free:
    get:
      operationId: getBriefFree
      summary: Demo free pre-interact risk brief
      description: Same brief JSON as /v1/brief but on the explicit free path (20/UTC-day/IP). Not for
        agent discovery — indexers must use GET /v1/brief which returns 402.
      parameters:
      - name: type
        in: query
        required: true
        schema:
          type: string
          enum:
          - address
          - token
          - url
      - name: q
        in: query
        required: true
        schema:
          type: string
          maxLength: 2048
      responses:
        '200':
          description: Brief JSON (free tier)
        '402':
          description: Free quota exhausted — pay via x402 on /v1/brief or subscribe
        '429':
          description: Rate limited when x402 disabled
  /.well-known/x402:
    get:
      operationId: getX402Discovery
      summary: x402 service discovery manifest
      description: 'Machine-readable x402 manifest for agent402.tools / bazaar indexers. Alias: /.well-known/x402.json'
      responses:
        '200':
          description: Discovery JSON
          content:
            application/json:
              schema:
                type: object
  /health:
    get:
      operationId: getHealth
      summary: Health check
      responses:
        '200':
          description: OK
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: 54k_
      description: Optional paid API key (54k_…). Alternatively pay per call with x402 USDC.