logicnodes-io Monitoring (subscriptions) API

openapi: 3.2.0
info:
  title: LogicNodes Monitoring (subscriptions) 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: Monitoring (subscriptions)
paths:
  /paid/v1/tools/wallet_watch_create:
    post:
      summary: Watch a wallet for 30 days (signed webhooks) ($5.00 per call)
      description: 'Subscribes for 30 days: LogicNodes watches one EVM address and POSTs a signed webhook (X-LogicNodes-Signature: sha256=HMAC of the body with your secret) when tokens arrive (incoming) or leave (outgoing), when it grants a token or NFT approval (approval), or when its sanctions status changes (sanctions). Returns the watch id and a secret shown only once. Native-coin transfers are not watched. The webhook must be a public https URL. Chains: eip155:84532, eip155:8453, eip155:1, eip155:137, eip155:42161, eip155:10, eip155:43114, eip155:1329, eip155:130, eip155:146, eip155:480, eip155:5042, eip155:999.'
      operationId: paid_wallet_watch_create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: string
                network:
                  type: string
                  description: CAIP-2 EVM chain id
                webhookUrl:
                  type: string
                  maxLength: 500
                  description: public https URL that receives the events
                events:
                  description: 'default: all four'
                  minItems: 1
                  maxItems: 4
                  type: array
                  items:
                    type: string
                    enum:
                    - incoming
                    - outgoing
                    - approval
                    - sanctions
              required:
              - address
              - network
              - webhookUrl
              additionalProperties: false
            example:
              address: '0x78845031f7bCA8fB9F3Ac0cc86678Ef8cE33Ea0e'
              network: eip155:8453
              webhookUrl: https://example.com/logicnodes-webhook
              events:
              - incoming
              - outgoing
      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:
      - Monitoring (subscriptions)
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '5.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