logicnodes-io Safety and trust API

openapi: 3.2.0
info:
  title: LogicNodes Safety and trust 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: Safety and trust
paths:
  /paid/v1/tools/tx_safety_check:
    post:
      summary: Is this transaction safe to sign? (simulate + risk check) ($0.005 per call)
      description: 'Before your agent signs an EVM transaction: simulates it on the current chain state and reports every token and native-coin movement in and out of the sender, decodes what it asks for (ERC-20 approve/permit, Permit2, setApprovalForAll, transfers), checks the counterparty (contract or wallet, sanctions lists) and, if you pass expectedTo, flags look-alike addresses (address poisoning). Verdict: "danger", "caution" or "no_known_risk", with every reason. It never says "safe": a simulation shows what would happen at this block. Chains: eip155:8453, eip155:1, eip155:137, eip155:42161, eip155:10, eip155:43114, eip155:1329, eip155:130, eip155:146, eip155:480, eip155:5042, eip155:999. Priced by the USD value at risk you declare in valueUsd: under $1,000: $0.005; under $10,000: $0.05; under $100,000: $0.50 (deep review); $100k and up: $2.00 (deep review). Deep review adds a second simulation on an independent provider and a counterparty check of every address involved.'
      operationId: paid_tx_safety_check
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                chain:
                  type: string
                  description: CAIP-2 EVM chain id, e.g. eip155:8453
                from:
                  type: string
                  description: the address that would sign
                to:
                  type: string
                  description: the transaction's to address
                data:
                  description: calldata, 0x... (omit for a plain native transfer)
                  type: string
                value:
                  description: native amount in wei (base units)
                  type: string
                  pattern: ^(0|[1-9][0-9]{0,77})$
                expectedTo:
                  description: the recipient or contract you MEANT to interact with; enables the look-alike check
                  type: string
                valueUsd:
                  description: approximate USD value at risk; sets the price tier, and $10,000+ includes the deep review
                  type: number
                  minimum: 0
                  maximum: 1000000000000
              required:
              - chain
              - from
              - to
              additionalProperties: false
            example:
              chain: eip155:8453
              from: '0x78845031f7bCA8fB9F3Ac0cc86678Ef8cE33Ea0e'
              to: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
              data: '0xa9059cbb000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa9604500000000000000000000000000000000000000000000000000000000000003e8'
              expectedTo: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
      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:
      - Safety and trust
      x-payment-info:
        price:
          mode: dynamic
          currency: USD
          min: '0.005'
          max: '2.00'
        protocols:
        - x402: {}
        x-logicnodes:
          asset: USDC
          scheme: exact
          methods: https://logicnodes.io/v1/payments/methods
          terms: base64 PAYMENT-REQUIRED response header
  /paid/v1/tools/sanctions_check:
    post:
      summary: Sanctions screening for a crypto address ($0.001 per call)
      description: 'Checks whether an address appears on public sanctions lists: the US Treasury OFAC SDN digital-currency addresses (EVM, Bitcoin, Solana, Tron, Litecoin, Bitcoin Cash) and, for EVM addresses, Chainalysis'' on-chain sanctions oracle. Returns sanctioned true/false, which sources matched, which were checked or unavailable, and when the list was last updated. This is a list match, not legal advice; no match is not a clearance. If no source can be read you get an error, never a ''clean'' result.'
      operationId: paid_sanctions_check
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: string
                  minLength: 20
                  maxLength: 120
                family:
                  description: auto-detected from the address format when omitted
                  type: string
                  enum:
                  - evm
                  - solana
                  - bitcoin
                  - tron
                  - litecoin
                  - bitcoin_cash
              required:
              - address
              additionalProperties: false
            example:
              address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
      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:
      - Safety and trust
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.001'
        protocols:
        - x402: {}
        x-logicnodes:
          asset: USDC
          scheme: exact
          methods: https://logicnodes.io/v1/payments/methods
          terms: base64 PAYMENT-REQUIRED response header
  /paid/v1/tools/counterparty_check:
    post:
      summary: Can I trust this counterparty?
      description: 'Before paying or delivering to an agent or address: checks sanctions lists, on-chain activity on Base and Ethereum (wallet, contract or EIP-7702 wallet; transaction counts), whether it owns an ERC-8004 agent identity, its record of deals verified by the LogicNodes notary (settled, and deliveries that failed their re-run check) and payments it made to LogicNodes. Returns every component, a 0-100 indicator and the formula: start 50; sanctions match = 0 (do not transact); +10 if 10+ transactions on Base or Ethereum, +10 more if 100+; +15 if it owns an ERC-8004 agent identity; +3 per deal settled through the LogicNodes notary (max +20); +1 per payment it made to LogicNodes (max +5); +10 if a domain operator is verified; -25 per delivery that failed its re-run check; clamped to 0-100. A new address has little history, which is not evidence of bad behaviour.'
      operationId: paid_counterparty_check
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: string
                  description: EVM address of the agent or counterparty
              required:
              - address
              additionalProperties: false
            example:
              address: '0x78845031f7bCA8fB9F3Ac0cc86678Ef8cE33Ea0e'
      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:
      - Safety and trust
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003'
        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