logicnodes-io Deals and disputes API

openapi: 3.2.0
info:
  title: LogicNodes Deals and disputes API
  version: 1.0.0
  description: 'Blockchain and finance tools AI agents can trust: exact answers or typed errors, never a plausible guess. 40+ tools for EVM chains and Aptos (balances, token amounts, transaction status and receipts, contract and calldata decoding, payment verification, gas on 14 chains), exact finance math, and ERC-8004 agent reputation. Every answer carries a receipt timestamped into Bitcoin. Free tier; pay per call in USDC via x402 on 13 networks, no API key.'
  x-guidance: 'How to use LogicNodes: 1) GET /v1/tools lists every tool with its JSON Schema. 2) POST /v1/tools/<name> with a JSON body, e.g. POST /v1/tools/evm_balance {"chain":"eip155:8453","address":"0x..."} or POST /v1/tools/token_amount_convert {"chain":"eip155:8453","asset":"<token address>","amount":"1.5","direction":"toBase"}. 3) Read "ok": true with "value", or "ok": false with a typed error: INVALID_INPUT (fix the field named), AMBIGUOUS_INPUT (pick one of the options listed and call again), NOT_FOUND, UPSTREAM_ERROR (retry). Chains are CAIP-2 ids (eip155:8453 Base, eip155:1 Ethereum, aptos:1); names like "base" are refused. Amounts are decimal strings, never floats. Pricing: free tools are unlimited; priced tools are free for 25 calls per day per IP, then the same URL returns 402 with x402 terms (USDC on Base, Solana, Polygon, Arbitrum and more: /v1/payments/methods); pay and retry. A failed call is never charged. MCP: /mcp/v2. Full guide: /agent-guide.'
  contact:
    email: denneyconner5@gmail.com
servers:
- url: https://logicnodes.io
tags:
- name: Deals and disputes
paths:
  /paid/v1/tools/deal_dispute_review:
    post:
      summary: Advisory ruling on a notarized deal (dispute review) ($1.00 per call)
      description: 'For a deal recorded by the LogicNodes deal notary: verifies the signed, hash-chained record and gives an ADVISORY ruling from fixed rules (R0, R1, R2, R3, R4, R5, R6: settled, delivered and checked, failed check, uncheckable, never delivered, never agreed). Returns the facts it used (with event hashes), the rule applied, and a ruling digest that goes into the Bitcoin-timestamped daily root. Advisory only: not a legal judgment and not enforced.'
      operationId: paid_deal_dispute_review
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                dealId:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{64}$
              required:
              - dealId
              additionalProperties: false
            example:
              dealId: '0xabababababababababababababababababababababababababababababababab'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResponse'
        '400':
          description: Error. Same ToolResponse shape with ok:false and a typed error.code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResponse'
        '402':
          description: 'Payment Required: terms are in the base64 PAYMENT-REQUIRED response header'
        '404':
          description: Error. Same ToolResponse shape with ok:false and a typed error.code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResponse'
        '422':
          description: Error. Same ToolResponse shape with ok:false and a typed error.code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResponse'
        '501':
          description: Error. Same ToolResponse shape with ok:false and a typed error.code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResponse'
        '502':
          description: Error. Same ToolResponse shape with ok:false and a typed error.code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResponse'
        '503':
          description: Error. Same ToolResponse shape with ok:false and a typed error.code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResponse'
      tags:
      - Deals and disputes
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '1.00'
        protocols:
        - x402: {}
        x-logicnodes:
          asset: USDC
          scheme: exact
          methods: https://logicnodes.io/v1/payments/methods
          terms: base64 PAYMENT-REQUIRED response header
components:
  schemas:
    ToolResponse:
      type: object
      properties:
        tool:
          type: string
        ok:
          type: boolean
        value:
          description: present when ok
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - INVALID_INPUT
              - AMBIGUOUS_INPUT
              - UNSUPPORTED_CHAIN
              - UNSUPPORTED_CAPABILITY
              - NOT_FOUND
              - STALE_DATA
              - NO_DATA
              - UPSTREAM_ERROR
            message:
              type: string
            field:
              type: string
            options:
              type: array
              items: {}
          required:
          - code
          - message
        provenance:
          type: object
          description: source, CAIP-2 chain, ledger position, fetchedAt
        receipt:
          type: object
          properties:
            version:
              type: integer
            algorithm:
              type: string
            tool:
              type: string
            digest:
              type: string
      required:
      - tool
      - ok
      - receipt