timzinin-com G2b Contract Demand Radar API

openapi: 3.2.0
info:
  title: Zinin M2M Hub G2b Contract Demand Radar API
  description: Pay-per-call data & tool APIs
  version: 1.0.0
  x-guidance: 'Zinin M2M Hub — pay-per-call data & tool APIs for AI agents. Each POST /api/{slug} operation below is a distinct paid tool: call GET /api/{slug}/schema first for the exact input shape, then POST with a signed PAYMENT-SIGNATURE header (x402 v2, USDC — see x-payment-info per operation) or omit it to receive a 402 with full payment requirements in the PAYMENT-REQUIRED header. The same catalog is also available as MCP JSON-RPC tool bundles at POST /mcp/{bundle} — see GET /.well-known/x402 for the list of bundles.'
tags:
- name: G2b Contract Demand Radar
paths:
  /api/g2b-contract-demand-radar:
    post:
      summary: Korea G2B Contract Demand Radar
      description: Convert official PPS contract aggregates into buyer-agency demand priorities. Unofficial, independent Actor; not affiliated with or endorsed by any named source publisher.
      operationId: call_g2b_contract_demand_radar
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.050000'
        protocols:
        - x402: {}
        network: eip155:8453
        payTo: '0x409D32aD39C02BC9B23a8b2d447532ed801b12dE'
        asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              schemaVersion: 1
              title: G2B Contract Demand Radar input
              description: Produces one whole paid batch of 20–40 explainable buyer-agency demand signals from an official annual PPS report.
              type: object
              additionalProperties: false
              properties:
                requestId:
                  title: Request ID
                  description: A new stable idempotency key for this exact analysis. Reusing it with different criteria is rejected.
                  sectionCaption: 1. Identify the decision batch
                  sectionDescription: Choose a unique non-personal request ID and one complete report year.
                  type: string
                  pattern: ^[A-Za-z0-9_-]{8,64}$
                  example: g2b-demand-2025-balanced-001
                  editor: textfield
                year:
                  title: Contract year
                  description: A complete or current PPS report year. Runtime rejects future years even though the schema leaves room for later releases.
                  type: integer
                  minimum: 2008
                  maximum: 2030
                  default: 2025
                  example: 2025
                  editor: number
                objective:
                  title: Supplier-priority objective
                  description: Controls transparent peer-percentile weights for spend, frequency, and average contract ticket.
                  sectionCaption: 2. Define useful demand
                  sectionDescription: Select the ranking objective, optional thresholds, and optional agency-name watch terms. No opaque AI score is used.
                  type: string
                  enum:
                  - balanced
                  - spend_volume
                  - contract_frequency
                  - average_ticket
                  enumTitles:
                  - Balanced demand
                  - Spend volume
                  - Contract frequency
                  - Average contract ticket
                  default: balanced
                  editor: select
                minimumContractCount:
                  title: Minimum annual contract count
                  description: Agencies below this customer threshold remain visible but receive a monitor-below-threshold action.
                  type: integer
                  minimum: 1
                  maximum: 10000000
                  default: 1000
                  example: 1000
                  editor: number
                minimumContractAmountKrw:
                  title: Minimum annual contract amount (KRW)
                  description: Agencies below this aggregate annual-spend threshold remain visible with an explicit threshold result.
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                  default: 100000000000
                  example: 100000000000
                  editor: number
                watchAgencyNameContains:
                  title: Agency-name watch terms
                  description: Up to ten non-sensitive substrings. A matching agency receives a disclosed five-point watch boost; matching never changes source facts.
                  type: array
                  minItems: 0
                  maxItems: 10
                  uniqueItems: true
                  default: []
                  example:
                  - 화성시
                  - 안동시
                  editor: stringList
                  items:
                    type: string
                    minLength: 1
                    maxLength: 80
                resultLimit:
                  title: Signals in the paid batch
                  description: Twenty to forty ranked signals. The Actor never starts source work unless the complete requested batch is affordable.
                  sectionCaption: 3. Bound output and spend
                  sectionDescription: The source is a browser-rendered official report, so its cost is amortized over at least twenty useful decisions.
                  type: integer
                  minimum: 20
                  maximum: 40
                  default: 20
                  example: 20
                  editor: number
                maxTotalChargeUsd:
                  title: Customer charge cap
                  description: Must cover Actor start plus the entire requested signal batch. Partial paid batches are not started.
                  type: number
                  minimum: 0.61
                  maximum: 100
                  default: 0.61
                  example: 0.61
                  editor: number
              required:
              - requestId
              - year
              - objective
              - minimumContractCount
              - minimumContractAmountKrw
              - watchAgencyNameContains
              - resultLimit
              - maxTotalChargeUsd
      responses:
        '200':
          description: Actor run succeeded and payment settled
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                    description: Actor output items — shape is actor-specific (varies per tool); see this operation's own requestBody schema/description for what the underlying actor produces.
                  meta:
                    type: object
                    properties:
                      run_ms:
                        type: integer
                        description: Actor run duration in milliseconds
                      item_count:
                        type: integer
                        description: len(results)
                      settled:
                        type: boolean
                        description: Whether the x402 payment was confirmed settled by the facilitator
                      transaction:
                        type:
                        - string
                        - 'null'
                        description: On-chain settlement transaction hash, null if unsettled
                    required:
                    - run_ms
                    - item_count
                    - settled
                    - transaction
                required:
                - results
                - meta
        '400':
          description: Malformed PAYMENT-SIGNATURE header or request body
        '402':
          description: Payment required or invalid — see PAYMENT-REQUIRED header
        '409':
          description: Payment payload already used
        '502':
          description: Actor run failed
        '504':
          description: Actor run timed out
      tags:
      - G2b Contract Demand Radar