logicnodes-io Aptos API

openapi: 3.2.0
info:
  title: LogicNodes Aptos 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: Aptos
paths:
  /paid/v1/tools/aptos_name_resolve:
    post:
      summary: Resolve an Aptos name (.apt) ($0.001 per call)
      description: name -> address, or address -> primary name (give exactly one). A name resolves to its TARGET address, which can differ from its owner; a registered name with no target resolves to nothing (NOT_FOUND) and its owner is never substituted. An address's primary name is returned only if that name resolves forward to the same address, so a spoofed reverse record is never trusted.
      operationId: paid_aptos_name_resolve
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                address:
                  type: string
                chain:
                  description: 'Aptos CAIP-2 id: aptos:1 (mainnet, default) or aptos:2 (testnet)'
                  type: string
              additionalProperties: false
            example:
              name: petra.apt
      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:
      - Aptos
      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/aptos_asset_resolve:
    post:
      summary: Resolve an Aptos asset ($0.001 per call)
      description: Turns a symbol, registry id, fungible-asset address or coin type into one asset, with its on-chain symbol/name/decimals read live. Several different assets share the symbols USDC and USDT (Circle/Tether native vs LayerZero-bridged); those return AMBIGUOUS_INPUT with every candidate, its issuer and how to select it. Assets outside the registry are returned with verified:false, never silently trusted.
      operationId: paid_aptos_asset_resolve
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                chain:
                  description: 'Aptos CAIP-2 id: aptos:1 (mainnet, default) or aptos:2 (testnet)'
                  type: string
                caseSensitive:
                  type: boolean
              required:
              - query
              additionalProperties: false
            example:
              query: APT
      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:
      - Aptos
      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/aptos_balance_get:
    post:
      summary: Aptos balances at a ledger version ($0.002 per call)
      description: 'Balances of an address for APT and fungible assets, all read at ONE ledger version (stated, or the current one pinned). Amounts are exact integer strings plus decimal strings. Default assets: APT and every verified asset; pass `assets` (symbols, ids, addresses, coin types) to choose. An ambiguous symbol fails the whole call. An address with no account and all-zero balances is reported honestly, not as an empty account.'
      operationId: paid_aptos_balance_get
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: string
                assets:
                  minItems: 1
                  maxItems: 20
                  type: array
                  items:
                    type: string
                ledgerVersion:
                  description: 'read the chain exactly as of this ledger version (default: the current one, pinned for consistency)'
                  anyOf:
                  - type: string
                  - type: integer
                    minimum: 0
                    maximum: 9007199254740991
                chain:
                  description: 'Aptos CAIP-2 id: aptos:1 (mainnet, default) or aptos:2 (testnet)'
                  type: string
              required:
              - address
              additionalProperties: false
            example:
              address: '0x1'
              assets:
              - 0x1::aptos_coin::AptosCoin
      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:
      - Aptos
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        protocols:
        - x402: {}
        x-logicnodes:
          asset: USDC
          scheme: exact
          methods: https://logicnodes.io/v1/payments/methods
          terms: base64 PAYMENT-REQUIRED response header
  /paid/v1/tools/aptos_fee_estimate:
    post:
      summary: Aptos fee estimate ($0.005 per call)
      description: 'Gas unit price tiers (deprioritized/regular/prioritized) plus the cost of common transactions in octas, APT and USD. Gas units are MEASURED by simulating real transfers now, not taken from a table. USD comes only from two independent exchanges that agree; otherwise USD is explicitly unavailable. Transaction types: apt_transfer, apt_transfer_new_account; for anything else use aptos_tx_simulate.'
      operationId: paid_aptos_fee_estimate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                txTypes:
                  type: array
                  items:
                    type: string
                chain:
                  description: 'Aptos CAIP-2 id: aptos:1 (mainnet, default) or aptos:2 (testnet)'
                  type: string
              additionalProperties: false
            example: {}
      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:
      - Aptos
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.005'
        protocols:
        - x402: {}
        x-logicnodes:
          asset: USDC
          scheme: exact
          methods: https://logicnodes.io/v1/payments/methods
          terms: base64 PAYMENT-REQUIRED response header
  /paid/v1/tools/aptos_tx_simulate:
    post:
      summary: Simulate an Aptos transaction ($0.005 per call)
      description: Runs an UNSIGNED entry-function transaction through the node's own simulator (no key needed, nothing is submitted) and returns success or the abort decoded in plain English, exact gas and fee, balance changes, and events. Arguments are type-checked against the module ABI first. Balance changes count only the framework's Withdraw/Deposit events, so assets that re-emit them (like USDC) are never double-counted. A simulation runs against the node's current state and cannot be pinned to an older ledger version.
      operationId: paid_aptos_tx_simulate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sender:
                  type: string
                function:
                  type: string
                typeArguments:
                  type: array
                  items:
                    type: string
                arguments:
                  type: array
                  items: {}
                maxGasAmount:
                  anyOf:
                  - type: string
                  - type: integer
                    minimum: 0
                    maximum: 9007199254740991
                gasUnitPrice:
                  anyOf:
                  - type: string
                  - type: integer
                    minimum: 0
                    maximum: 9007199254740991
                sequenceNumber:
                  anyOf:
                  - type: string
                  - type: integer
                    minimum: 0
                    maximum: 9007199254740991
                chain:
                  description: 'Aptos CAIP-2 id: aptos:1 (mainnet, default) or aptos:2 (testnet)'
                  type: string
              required:
              - sender
              - function
              additionalProperties: false
            example:
              sender: '0x1'
              function: 0x1::aptos_account::transfer
              arguments:
              - '0x2'
              - '1'
      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:
      - Aptos
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.005'
        protocols:
        - x402: {}
        x-logicnodes:
          asset: USDC
          scheme: exact
          methods: https://logicnodes.io/v1/payments/methods
          terms: base64 PAYMENT-REQUIRED response header
  /paid/v1/tools/aptos_tx_decode:
    post:
      summary: Decode an Aptos entry-function call ($0.002 per call)
      description: Explains what an entry-function payload would do, in plain English, with every argument type-checked against the module ABI and amounts shown using the asset's live decimals. Known patterns (transfers, batch transfers, key rotation, code publishing) carry a risk flag from a fixed table; no flag means 'not recognised', never 'safe'.
      operationId: paid_aptos_tx_decode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                function:
                  type: string
                typeArguments:
                  type: array
                  items:
                    type: string
                arguments:
                  type: array
                  items: {}
                chain:
                  description: 'Aptos CAIP-2 id: aptos:1 (mainnet, default) or aptos:2 (testnet)'
                  type: string
              required:
              - function
              additionalProperties: false
            example:
              function: 0x1::aptos_account::transfer
              arguments:
              - '0x1'
              - '100000000'
      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:
      - Aptos
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        protocols:
        - x402: {}
        x-logicnodes:
          asset: USDC
          scheme: exact
          methods: https://logicnodes.io/v1/payments/methods
          terms: base64 PAYMENT-REQUIRED response header
  /paid/v1/tools/aptos_tx_status:
    post:
      summary: Aptos transaction status ($0.001 per call)
      description: Committed, failed, pending or not found for a transaction hash, with the VM status explained in plain English (Move aborts decoded to module, error name, code and category; the raw status is always included). Fee is computed from the VM's own fee statement.
      operationId: paid_aptos_tx_status
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                hash:
                  type: string
                chain:
                  description: 'Aptos CAIP-2 id: aptos:1 (mainnet, default) or aptos:2 (testnet)'
                  type: string
              required:
              - hash
              additionalProperties: false
            example:
              hash: '0x0000000000000000000000000000000000000000000000000000000000000000'
      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:
      - Aptos
      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/aptos_view:
    post:
      summary: Call an Aptos view function ($0.002 per call)
      description: 'Calls a Move #[view] function read-only, after checking every type argument and argument against the module''s ABI: u64/u128/u256 must be decimal strings, vector a 0x hex string, Option written {"vec":[]} or {"vec":[value]}, addresses in AIP-40 form. A wrong argument is a specific error from us, never an opaque node error. Optionally reads at a stated ledger version.'
      operationId: paid_aptos_view
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                function:
                  type: string
                typeArguments:
                  type: array
                  items:
                    type: string
                arguments:
                  type: array
                  items: {}
                ledgerVersion:
                  description: 'read the chain exactly as of this ledger version (default: the current one, pinned for consistency)'
                  anyOf:
                  - type: string
                  - type: integer
                    minimum: 0
                    maximum: 9007199254740991
                chain:
                  description: 'Aptos CAIP-2 id: aptos:1 (mainnet, default) or aptos:2 (testnet)'
                  type: string
              required:
              - function
              additionalProperties: false
            example:
              function: 0x1::coin::name
              typeArguments:
              - 0x1::aptos_coin::AptosCoin
              arguments: []
      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:
      - Aptos
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        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