DefaultBench Transparency API

openapi: 3.2.0
info:
  title: DefaultBench Transparency API
  version: 1.0.0
  summary: Machine-first paid placement and discovery for autonomous agents.
  description: DefaultBench exposes transparent sponsored rankings. Listings are ordered by cumulative verified USDC payment descending, then by the time the current cumulative total was reached ascending. Rank is paid placement, not an endorsement or quality signal. Monetary values are decimal strings containing integer USDC base units (six decimals).
  termsOfService: https://defaultbench.com/terms
  license:
    name: Proprietary service API; public protocol documentation
    url: https://defaultbench.com/terms
servers:
- url: https://defaultbench.com
  description: Configured DefaultBench origin
tags:
- name: Transparency
  description: Verified-payment ledger and aggregates.
paths:
  /api/v1/attribution/transparency:
    get:
      operationId: getPublicAttributionTransparency
      tags:
      - Transparency
      summary: Read safe global and thresholded market aggregates
      description: Publishes daily global counters and only canonical keyword-market rows meeting the configured daily eligible-impression threshold. Rare buckets and request-level keys are never published.
      parameters:
      - name: from
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Daily aggregate-only transparency report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAttributionReport'
        '400':
          description: The request is malformed or a query parameter is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidKeyword:
                  value:
                    error:
                      code: invalid_keyword
                      message: Keyword must normalize to 1–64 valid characters.
                      details: {}
                validationError:
                  value:
                    error:
                      code: validation_error
                      message: Request validation failed.
                      details:
                        fields:
                        - path: limit
                          message: 'Too big: expected number to be <=100'
        '429':
          description: The applicable bounded rate limit is exhausted.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: rate_limit_exceeded
                  message: Rate limit exceeded. Retry after the indicated delay.
                  details: {}
                  retry_after_seconds: 30
        '500':
          description: An unexpected server error occurred; no uncertain payment is credited.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: internal_error
                  message: The request could not be completed.
                  details: {}
        '503':
          description: A dependency is unavailable, one identical request owns the settlement claim, settlement is uncertain, or a confirmed settlement is awaiting atomic ranking credit. These responses never authorize a replacement payment. Retry the identical paid request after Retry-After unless the code says otherwise.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
            PAYMENT-RESPONSE:
              $ref: '#/components/headers/PaymentResponse'
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                dependencyUnavailable:
                  value:
                    error:
                      code: service_unavailable
                      message: A required dependency is temporarily unavailable.
                      details:
                        retryable: true
                settlementInProgress:
                  value:
                    error:
                      code: payment_settlement_in_progress
                      message: An identical settlement attempt is already in progress. Retry this request shortly.
                      details:
                        idempotency_key: bid_01JQ4Z6W2YW1FVD5QAPGMF6M4Q
                        settlement_state: settling
                        transaction_id: null
                        retryable: true
                settlementUncertain:
                  value:
                    error:
                      code: payment_settlement_uncertain
                      message: The settlement outcome is being reconciled and will not be submitted again automatically. Retry this identical request for the durable result.
                      details:
                        idempotency_key: bid_01JQ4Z6W2YW1FVD5QAPGMF6M4Q
                        settlement_state: settlement_uncertain
                        transaction_id: null
                        retryable: true
                settledPendingCredit:
                  value:
                    error:
                      code: payment_settled_pending_credit
                      message: Settlement succeeded, but ranking credit is pending durable recovery. Retry the identical request.
                      details:
                        idempotency_key: bid_01JQ4Z6W2YW1FVD5QAPGMF6M4Q
                        transaction_id: '0x0000000000000000000000000000000000000000000000000000000000000001'
                        retryable: true
                bidConfigurationUnavailable:
                  value:
                    error:
                      code: bid_configuration_unavailable
                      message: Bidding is temporarily unavailable while payment policy configuration is synchronized.
                      details:
                        retryable: true
  /api/v1/activity:
    get:
      operationId: listActivity
      tags:
      - Transparency
      summary: List verified payment activity
      description: Contains settled, credited payments only. Failed or uncertain attempts never appear as successful activity.
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A reverse-chronological stable page of credited payments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityResponse'
        '400':
          description: The request is malformed or a query parameter is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidKeyword:
                  value:
                    error:
                      code: invalid_keyword
                      message: Keyword must normalize to 1–64 valid characters.
                      details: {}
                validationError:
                  value:
                    error:
                      code: validation_error
                      message: Request validation failed.
                      details:
                        fields:
                        - path: limit
                          message: 'Too big: expected number to be <=100'
        '429':
          description: The applicable bounded rate limit is exhausted.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: rate_limit_exceeded
                  message: Rate limit exceeded. Retry after the indicated delay.
                  details: {}
                  retry_after_seconds: 30
        '500':
          description: An unexpected server error occurred; no uncertain payment is credited.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: internal_error
                  message: The request could not be completed.
                  details: {}
        '503':
          description: A dependency is unavailable, one identical request owns the settlement claim, settlement is uncertain, or a confirmed settlement is awaiting atomic ranking credit. These responses never authorize a replacement payment. Retry the identical paid request after Retry-After unless the code says otherwise.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
            PAYMENT-RESPONSE:
              $ref: '#/components/headers/PaymentResponse'
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                dependencyUnavailable:
                  value:
                    error:
                      code: service_unavailable
                      message: A required dependency is temporarily unavailable.
                      details:
                        retryable: true
                settlementInProgress:
                  value:
                    error:
                      code: payment_settlement_in_progress
                      message: An identical settlement attempt is already in progress. Retry this request shortly.
                      details:
                        idempotency_key: bid_01JQ4Z6W2YW1FVD5QAPGMF6M4Q
                        settlement_state: settling
                        transaction_id: null
                        retryable: true
                settlementUncertain:
                  value:
                    error:
                      code: payment_settlement_uncertain
                      message: The settlement outcome is being reconciled and will not be submitted again automatically. Retry this identical request for the durable result.
                      details:
                        idempotency_key: bid_01JQ4Z6W2YW1FVD5QAPGMF6M4Q
                        settlement_state: settlement_uncertain
                        transaction_id: null
                        retryable: true
                settledPendingCredit:
                  value:
                    error:
                      code: payment_settled_pending_credit
                      message: Settlement succeeded, but ranking credit is pending durable recovery. Retry the identical request.
                      details:
                        idempotency_key: bid_01JQ4Z6W2YW1FVD5QAPGMF6M4Q
                        transaction_id: '0x0000000000000000000000000000000000000000000000000000000000000001'
                        retryable: true
                bidConfigurationUnavailable:
                  value:
                    error:
                      code: bid_configuration_unavailable
                      message: Bidding is temporarily unavailable while payment policy configuration is synchronized.
                      details:
                        retryable: true
  /api/v1/stats:
    get:
      operationId: getStats
      tags:
      - Transparency
      summary: Get aggregate verified-payment statistics
      description: All money fields include verified, atomically credited activity from this deployment environment only.
      responses:
        '200':
          description: Public aggregate statistics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsResponse'
        '429':
          description: The applicable bounded rate limit is exhausted.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: rate_limit_exceeded
                  message: Rate limit exceeded. Retry after the indicated delay.
                  details: {}
                  retry_after_seconds: 30
        '500':
          description: An unexpected server error occurred; no uncertain payment is credited.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: internal_error
                  message: The request could not be completed.
                  details: {}
        '503':
          description: A dependency is unavailable, one identical request owns the settlement claim, settlement is uncertain, or a confirmed settlement is awaiting atomic ranking credit. These responses never authorize a replacement payment. Retry the identical paid request after Retry-After unless the code says otherwise.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
            PAYMENT-RESPONSE:
              $ref: '#/components/headers/PaymentResponse'
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                dependencyUnavailable:
                  value:
                    error:
                      code: service_unavailable
                      message: A required dependency is temporarily unavailable.
                      details:
                        retryable: true
                settlementInProgress:
                  value:
                    error:
                      code: payment_settlement_in_progress
                      message: An identical settlement attempt is already in progress. Retry this request shortly.
                      details:
                        idempotency_key: bid_01JQ4Z6W2YW1FVD5QAPGMF6M4Q
                        settlement_state: settling
                        transaction_id: null
                        retryable: true
                settlementUncertain:
                  value:
                    error:
                      code: payment_settlement_uncertain
                      message: The settlement outcome is being reconciled and will not be submitted again automatically. Retry this identical request for the durable result.
                      details:
                        idempotency_key: bid_01JQ4Z6W2YW1FVD5QAPGMF6M4Q
                        settlement_state: settlement_uncertain
                        transaction_id: null
                        retryable: true
                settledPendingCredit:
                  value:
                    error:
                      code: payment_settled_pending_credit
                      message: Settlement succeeded, but ranking credit is pending durable recovery. Retry the identical request.
                      details:
                        idempotency_key: bid_01JQ4Z6W2YW1FVD5QAPGMF6M4Q
                        transaction_id: '0x0000000000000000000000000000000000000000000000000000000000000001'
                        retryable: true
                bidConfigurationUnavailable:
                  value:
                    error:
                      code: bid_configuration_unavailable
                      message: Bidding is temporarily unavailable while payment policy configuration is synchronized.
                      details:
                        retryable: true
components:
  schemas:
    ActivityResponse:
      type: object
      additionalProperties: false
      required:
      - activity
      - pagination
      properties:
        activity:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/ActivityRecord'
        pagination:
          $ref: '#/components/schemas/Pagination'
      examples:
      - activity: []
        pagination:
          next_cursor: null
    StatsResponse:
      type: object
      additionalProperties: false
      required:
      - lifetime_verified_payment_base_units
      - verified_payment_count
      - unique_paying_wallets
      - keyword_count
      - active_listing_count
      - generated_at
      properties:
        lifetime_verified_payment_base_units:
          $ref: '#/components/schemas/BaseUnitAmount'
        verified_payment_count:
          type: integer
          minimum: 0
        unique_paying_wallets:
          type: integer
          minimum: 0
        keyword_count:
          type: integer
          minimum: 0
        active_listing_count:
          type: integer
          minimum: 0
        generated_at:
          type: string
          format: date-time
      examples:
      - lifetime_verified_payment_base_units: '0'
        verified_payment_count: 0
        unique_paying_wallets: 0
        keyword_count: 0
        active_listing_count: 0
        generated_at: '2000-01-01T00:00:00Z'
    Pagination:
      type: object
      additionalProperties: false
      required:
      - next_cursor
      properties:
        next_cursor:
          oneOf:
          - type: string
            minLength: 1
          - type: 'null'
          description: Opaque cursor for the next page, or null at the end.
    KeywordSlug:
      type: string
      minLength: 1
      maxLength: 64
      pattern: ^[\p{L}\p{N}]+(?:-[\p{L}\p{N}]+)*$
      examples:
      - research
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
      - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
          - code
          - message
          - details
          properties:
            code:
              type: string
              pattern: ^[a-z][a-z0-9_]*$
              description: Stable machine-readable code.
            message:
              type: string
              description: Human-readable, non-stable explanation.
            details:
              $ref: '#/components/schemas/ErrorDetail'
            retry_after_seconds:
              type: integer
              minimum: 1
    ActivityRecord:
      type: object
      additionalProperties: false
      required:
      - id
      - payment_id
      - transaction_id
      - listing_id
      - listing_name
      - keyword
      - payer_wallet
      - recipient_wallet
      - amount_base_units
      - cumulative_payment_base_units
      - resulting_rank
      - network
      - token_address
      - token_symbol
      - settled_at
      - block_number
      properties:
        id:
          type: string
          format: uuid
        payment_id:
          type: string
          minLength: 1
          maxLength: 255
        transaction_id:
          oneOf:
          - type: string
            pattern: ^0x[0-9a-f]{64}$
          - type: 'null'
        listing_id:
          type: string
          format: uuid
        listing_name:
          type: string
          minLength: 1
          maxLength: 80
        keyword:
          $ref: '#/components/schemas/KeywordSlug'
        payer_wallet:
          $ref: '#/components/schemas/WalletAddress'
        recipient_wallet:
          $ref: '#/components/schemas/WalletAddress'
        amount_base_units:
          $ref: '#/components/schemas/BaseUnitAmount'
        cumulative_payment_base_units:
          $ref: '#/components/schemas/BaseUnitAmount'
        resulting_rank:
          oneOf:
          - type: integer
            minimum: 1
          - type: 'null'
          description: Resulting sponsored rank, or null when the credited listing was already hidden.
        network:
          type: string
          description: CAIP-2 network identifier.
          examples:
          - eip155:8453
        token_address:
          type: string
          examples:
          - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        token_symbol:
          type: string
          const: USDC
        settled_at:
          type: string
          format: date-time
        block_number:
          oneOf:
          - type: string
            pattern: ^(0|[1-9][0-9]*)$
          - type: 'null'
    ErrorDetail:
      type: object
      description: Code-specific bounded details; clients must branch on error.code, not message text.
      additionalProperties: true
    WalletAddress:
      type: string
      pattern: ^0x[0-9a-fA-F]{40}$
      description: EVM address. Comparisons use its canonical byte value, not display casing.
      examples:
      - '0x1111111111111111111111111111111111111111'
    BaseUnitAmount:
      type: string
      pattern: ^(0|[1-9][0-9]*)$
      description: Unsigned integer number of USDC base units. USDC has six decimals; never parse as float.
      examples:
      - '10000'
    PublicAttributionRow:
      type: object
      additionalProperties: false
      required:
      - metric_date
      - keyword_bucket
      - eligible_impressions
      - eligible_market_requests
      - sponsored_impressions
      - organic_impressions
      - detail_views
      - referrals
      - declared_conversions
      properties:
        metric_date:
          type: string
          format: date
        keyword_bucket:
          oneOf:
          - $ref: '#/components/schemas/KeywordSlug'
          - type: 'null'
        eligible_impressions:
          $ref: '#/components/schemas/CountString'
        eligible_market_requests:
          $ref: '#/components/schemas/CountString'
        sponsored_impressions:
          $ref: '#/components/schemas/CountString'
        organic_impressions:
          $ref: '#/components/schemas/CountString'
        detail_views:
          $ref: '#/components/schemas/CountString'
        referrals:
          $ref: '#/components/schemas/CountString'
        declared_conversions:
          $ref: '#/components/schemas/CountString'
    PublicAttributionReport:
      type: object
      additionalProperties: false
      required:
      - from
      - to
      - bucket
      - minimum_publication_volume
      - global
      - published_markets
      - rare_markets_suppressed
      - measurement_classes
      properties:
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        bucket:
          type: string
          const: day
        minimum_publication_volume:
          type: integer
          minimum: 10
        global:
          type: array
          items:
            $ref: '#/components/schemas/PublicAttributionRow'
        published_markets:
          type: array
          items:
            $ref: '#/components/schemas/PublicAttributionRow'
        rare_markets_suppressed:
          type: boolean
          const: true
        measurement_classes:
          type: object
          additionalProperties:
            type: string
            enum:
            - measured
            - inferred
            - provider_declared
    CountString:
      type: string
      pattern: ^(0|[1-9][0-9]*)$
      description: Exact non-negative aggregate count encoded as a decimal integer string.
  headers:
    RateLimitRemaining:
      description: Requests remaining in the current policy window.
      schema:
        type: integer
        minimum: 0
    RateLimitLimit:
      description: Maximum requests in the current policy window.
      schema:
        type: integer
        minimum: 1
    PaymentResponse:
      description: Base64-encoded JSON x402 v2 settlement response/receipt. It may also be present on a non-200 facilitator failure or uncertain response; header presence alone is never evidence of success or ranking credit.
      schema:
        type: string
        contentEncoding: base64
    RetryAfter:
      description: Seconds until the caller should retry.
      schema:
        type: integer
        minimum: 1
    RateLimitReset:
      description: Unix epoch timestamp in seconds when the current policy window resets.
      schema:
        type: integer
        minimum: 0
    RequestId:
      description: Opaque request correlation identifier; safe to include in an incident report.
      schema:
        type: string
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum items to return.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    Cursor:
      name: cursor
      in: query
      required: false
      description: Opaque cursor returned by the previous page. Do not inspect or modify it. Omitting it starts a new snapshot traversal.
      schema:
        type: string
        minLength: 1
        maxLength: 512
  securitySchemes:
    x402Payment:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: Base64-encoded x402 v2 payment payload. It is intentionally absent on the initial request that obtains HTTP 402 requirements.
    sellerAnalyticsBearer:
      type: http
      scheme: bearer
      bearerFormat: DefaultBench signed token
      description: Five-minute token issued only after consuming a listing-bound, origin-bound EIP-712 wallet challenge.
    operatorBearer:
      type: http
      scheme: bearer
      description: Operator secret for private revenue and purchase-funnel metrics.
externalDocs:
  description: Full autonomous-client instructions
  url: https://defaultbench.com/llms-full.txt
x-defaultbench-payment:
  protocol: x402
  version: 2
  sdkVersion: 2.24.0
  scheme: exact
  network: eip155:8453
  networkLabel: Base mainnet
  asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
  symbol: USDC
  decimals: 6
  minimumBidBaseUnits: '10000'
  requestHeader: PAYMENT-SIGNATURE
  challengeHeader: PAYMENT-REQUIRED
  settlementHeader: PAYMENT-RESPONSE
x-defaultbench-ranking:
  primary: cumulative verified payment descending
  tieBreaker: timestamp current cumulative total was reached ascending
  qualitySignal: false
x-defaultbench-examples: Synthetic documentation examples; never production activity.