timzinin-com Panama Canal Queue Transit Imbalance API

openapi: 3.2.0
info:
  title: Zinin M2M Hub Panama Canal Queue Transit Imbalance 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: Panama Canal Queue Transit Imbalance
paths:
  /api/panama-canal-queue-transit-imbalance:
    post:
      summary: Panama Canal Queue & Transit Imbalance Monitor
      description: Compare aggregate commercial-vessel pressure across two fixed Panama Canal approach zones. Get side imbalance, movement, observed dwell, baseline change, freshness, confidence, gaps, and a human review action without exposing raw vessel identities or claiming official Canal queues.
      operationId: call_panama_canal_queue_transit_imbalance
      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: Panama Canal Queue & Transit Imbalance Monitor input
              description: Use demo for a synthetic Dataset row with no $0.05 result-found fee; the $0.005 start charge still applies. Datalastic provides live aggregate AIS evidence with your own key. The Actor uses fixed approach zones and does not accept custom coordinates.
              type: object
              schemaVersion: 1
              additionalProperties: false
              required:
              - schemaVersion
              - requestId
              - watchId
              - sourceMode
              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
                  pattern: ^(auto|[a-z0-9][a-z0-9._-]{2,63})$
                  default: auto
                  prefill: auto
                  editor: textfield
                  description: Use auto for a trusted-run-derived id or provide an explicit idempotency value. The returned requestId is an irreversible SHA-256-derived identifier.
                watchId:
                  title: Watch ID
                  type: string
                  pattern: ^[a-z0-9][a-z0-9._-]{2,63}$
                  default: panama-canal-main
                  prefill: panama-canal-main
                  editor: textfield
                  description: Stable lower-case identity for the queue history. It is irreversibly derived before lock, state, ledger, and output use.
                sourceMode:
                  title: Source mode
                  type: string
                  enum:
                  - demo
                  - datalastic
                  default: demo
                  prefill: demo
                  editor: select
                  description: Demo writes one synthetic row with no $0.05 result-found fee; the $0.005 start charge applies. Datalastic uses your own API key.
                datalasticApiKey:
                  title: Datalastic API key
                  type: string
                  isSecret: true
                  editor: textfield
                  description: Required only for datalastic mode. Runtime validation requires a printable 8-256 character secret. Never returned in output.
                identitySalt:
                  title: Identity salt
                  type: string
                  isSecret: true
                  editor: textfield
                  description: Optional HMAC salt for datalastic mode. Runtime validation requires a printable 8-256 character secret. Never returned in output.
                baselineDays:
                  title: Baseline days
                  description: Number of stored observations used for the queue baseline.
                  type: integer
                  minimum: 7
                  maximum: 365
                  default: 30
                  prefill: 30
                  editor: number
                maxVessels:
                  title: Maximum vessels per side
                  description: Maximum bounded provider rows accepted for each fixed approach. The live-safe default of 500 avoids truncating dense approach snapshots.
                  type: integer
                  minimum: 1
                  maximum: 500
                  default: 500
                  prefill: 500
                  editor: number
                maxProviderRequests:
                  title: Provider request cap
                  description: 'Fixed exact cap: /stat plus the two Panama approach zones.'
                  type: integer
                  minimum: 3
                  maximum: 3
                  default: 3
                  prefill: 3
                  editor: number
                timeoutMs:
                  title: Provider timeout (ms)
                  description: Timeout for each bounded provider request.
                  type: integer
                  minimum: 1000
                  maximum: 30000
                  default: 10000
                  prefill: 10000
                  editor: number
                maxTotalChargeUsd:
                  title: Maximum total charge (USD)
                  description: Buyer-side cap checked before the paid report event.
                  type: number
                  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:
      - Panama Canal Queue Transit Imbalance