timzinin-com Singapore Bunker Tanker Divergence API

openapi: 3.2.0
info:
  title: Zinin M2M Hub Singapore Bunker Tanker Divergence 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: Singapore Bunker Tanker Divergence
paths:
  /api/singapore-bunker-tanker-divergence:
    post:
      summary: Singapore Bunker Demand & Tanker Flow Divergence
      description: Compare official monthly Singapore bunker demand, tanker arrivals, fuel mix, and vessel calls in one evidence report. Add optional bounded BYOK tanker pressure, with publication lag, freshness, confidence, null reasons, provenance, gaps, and human review.
      operationId: call_singapore_bunker_tanker_divergence
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.020000'
        protocols:
        - x402: {}
        network: eip155:8453
        payTo: '0x409D32aD39C02BC9B23a8b2d447532ed801b12dE'
        asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Singapore Bunker Demand & Tanker Flow Divergence input
              description: Compare official monthly Singapore vessel and bunker data, with optional two-request BYOK tanker pressure. Demo is synthetic, has no $0.05 result-found fee, and never emits result-found; the $0.005 actor-start charge still applies.
              type: object
              schemaVersion: 1
              additionalProperties: false
              required:
              - schemaVersion
              properties:
                schemaVersion:
                  title: Schema version
                  description: Contract version for this Actor input.
                  type: string
                  enum:
                  - '1.0'
                  default: '1.0'
                  prefill: '1.0'
                  editor: select
                requestId:
                  title: Request ID
                  type: string
                  description: Use auto for a Task-safe run identity.
                  pattern: ^(auto|[A-Za-z0-9][A-Za-z0-9._:-]{0,127})$
                  default: auto
                  prefill: auto
                  editor: textfield
                watchId:
                  title: Watch ID
                  type: string
                  description: Stable identity for the Singapore baseline.
                  minLength: 3
                  maxLength: 64
                  pattern: ^[a-z0-9][a-z0-9._-]{2,63}$
                  default: singapore-bunker-main
                  prefill: singapore-bunker-main
                  editor: textfield
                sourceMode:
                  title: Source mode
                  type: string
                  description: 'Demo is synthetic; open uses data.gov.sg; open_plus_byok adds two bounded Datalastic provider requests: /stat plus Singapore.'
                  enum:
                  - demo
                  - open
                  - open_plus_byok
                  default: open
                  prefill: open
                  editor: select
                datalasticApiKey:
                  title: Datalastic API key
                  type: string
                  description: Only valid with sourceMode=open_plus_byok; runtime validation requires a printable 8-256 character secret, rejects it in demo/open, and never returns it.
                  isSecret: true
                  editor: textfield
                baselineMonths:
                  title: Baseline months
                  type: integer
                  description: Historical window used for 3-month and 12-month comparisons.
                  minimum: 3
                  maximum: 12
                  default: 12
                  prefill: 12
                  editor: number
                maxRows:
                  title: Rows per official source
                  type: integer
                  description: One bounded page per official source; 240 covers the observed 13-month window and up to 500 is allowed.
                  minimum: 240
                  maximum: 500
                  default: 240
                  prefill: 240
                  editor: number
                maxProviderRequests:
                  title: Maximum provider requests
                  type: integer
                  description: 'Exactly two requests are permitted for BYOK: /stat plus the Singapore zone.'
                  minimum: 2
                  maximum: 2
                  default: 2
                  prefill: 2
                  editor: number
                maxTotalChargeUsd:
                  title: Maximum total charge (USD)
                  type: number
                  description: Buyer cap checked before the paid result event.
                  minimum: 0.005
                  maximum: 100
                  default: 0.055
                  prefill: 0.055
                  editor: number
      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:
      - Singapore Bunker Tanker Divergence