> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nikiwa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# analyze_transaction

> Decode and classify a single transaction (participants, value flow, risk flags).

## Reading the result

The response example uses made-up values and shows selected fields. Fields vary by network and available data.

* `data` contains a network-specific transaction analysis. In the EVM example, `sender_info` and `receiver_info` identify the addresses and any available risk findings.

* `logs_info` contains decoded log details. `gas_info` includes gas price in wei and gas used and gas limit in gas units.

* Solana, Tron, and Bitcoin return different fields for transfers, fees, or transaction inputs and outputs. Do not treat missing risk data as a clean assessment.


## OpenAPI

````yaml POST /api/tools/analyze_transaction
openapi: 3.0.3
info:
  title: Nikiwa Tools API
  version: 1.0.0
  description: >-
    Curated blockchain, token, and DeFi market-data tools over authenticated
    HTTP/JSON. Authenticate with a developer key (`nkw_live_...`) carrying the
    `api:call` scope as `Authorization: Bearer <key>`. Each tool is a `POST
    /api/tools/<name>` whose JSON body is the tool's arguments.
servers:
  - url: https://pro-api.nikiwa.com
security:
  - bearerAuth: []
paths:
  /api/tools/analyze_transaction:
    post:
      tags:
        - Tools API
      summary: analyze_transaction
      description: >-
        Decode and classify a single transaction (participants, value flow, risk
        flags).
      operationId: invoke_analyze_transaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tx_hash:
                  type: string
                  description: >-
                    Full transaction hash or Solana signature. Include the
                    network to disambiguate.
                network:
                  type: string
                  description: >-
                    Network to query, for example ethereum. See Supported
                    Networks for coverage.
              required:
                - tx_hash
                - network
      responses:
        '200':
          description: >-
            Decode and classify a single transaction (participants, value flow,
            risk flags). Fields vary by network and available data. Check for
            `status: no_data`, `status: error`, or an `error` field even when
            HTTP status is 200. See [Errors & status](/api-reference/errors).
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                description: >-
                  Response fields depend on the network and available data. The
                  example shows selected fields; see Reading the result for
                  details.
              examples:
                illustrative:
                  summary: Illustrative response (selected fields)
                  description: >-
                    Made-up values showing the response structure. Not a live
                    result. Additional fields may be returned.
                  value:
                    data:
                      network: ethereum
                      tx_hash: >-
                        0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
                      timestamp: '1769860800'
                      block_number: 24000000
                      sender_info:
                        address: '0x1111111111111111111111111111111111111111'
                        risk_flags: null
                      receiver_info:
                        address: '0x2222222222222222222222222222222222222222'
                        risk_flags: null
                      logs_info: []
                      gas_info:
                        gas_price: 1000000000
                        gas_used: 21000
                        gas_limit: 21000
                      amount: 0
                      successful: true
        '400':
          $ref: '#/components/responses/BodyReadError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/UnknownTool'
        '422':
          description: >-
            Invalid tool arguments or request-body validation failure. detail is
            a string for argument binding errors or an array for request
            validation errors.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/HttpError'
                  - $ref: '#/components/schemas/RequestValidationError'
              examples:
                arguments:
                  summary: Invalid tool arguments
                  value:
                    detail: Invalid arguments for 'analyze_transaction'.
                invalidJson:
                  summary: Malformed JSON
                  value:
                    detail:
                      - type: json_invalid
                        loc:
                          - body
                          - 1
                        msg: JSON decode error
                        input: {}
                        ctx:
                          error: Expecting property name enclosed in double quotes
        '429':
          $ref: '#/components/responses/ToolUsageLimit'
      security:
        - bearerAuth: []
components:
  responses:
    BodyReadError:
      description: >-
        The server could not read or parse the request body. Malformed JSON
        normally returns 422 instead.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
          examples:
            bodyRead:
              summary: Body parsing failure
              value:
                detail: There was an error parsing the body
    Unauthorized:
      description: Missing, malformed, invalid, revoked, or insufficiently scoped API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
          examples:
            missingHeader:
              summary: Missing or malformed Authorization header
              value:
                detail: Missing or malformed Authorization header
            invalidKey:
              summary: Invalid key or missing API scope
              value:
                detail: Invalid API key
    UnknownTool:
      description: >-
        Unknown or non-public tool name. Check GET /api/tools for available
        names.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
          examples:
            unknownTool:
              summary: Unknown tool
              value:
                detail: Unknown tool 'unknown_tool'
    ToolUsageLimit:
      description: >-
        Per-key request rate or enforced plan quota exceeded. Inspect detail to
        distinguish the cause. Plan identifiers, quotas, and reset times in the
        example are illustrative.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/HttpError'
              - $ref: '#/components/schemas/PlanQuotaError'
          examples:
            rateLimit:
              summary: Per-key rate limit
              value:
                detail: Rate limit exceeded
            planQuota:
              summary: Plan quota exhausted (illustrative values)
              value:
                detail:
                  error_code: PLAN_LIMIT_REACHED
                  meter: api_calls
                  plan_id: example_plan
                  limit: 1000
                  resets_at: '2026-10-01T00:00:00+00:00'
                  message: >-
                    You have reached your plan's usage limit for this feature.
                    Upgrade your plan to continue, or wait until the limit
                    resets.
      headers:
        Retry-After:
          description: >-
            Seconds until the plan quota resets, when its reset time is known.
            Not sent by the per-key rate limiter.
          schema:
            type: string
          example: '3600'
  schemas:
    HttpError:
      type: object
      required:
        - detail
      properties:
        detail:
          type: string
          description: Explanation of the rejected request.
    RequestValidationError:
      type: object
      required:
        - detail
      properties:
        detail:
          type: array
          description: Request validation failures. Available fields depend on the failure.
          items:
            type: object
            required:
              - loc
              - msg
              - type
            properties:
              loc:
                type: array
                items:
                  oneOf:
                    - type: string
                    - type: integer
                description: Location of the invalid value in the request.
              msg:
                type: string
              type:
                type: string
              input:
                description: Rejected input, when included.
              ctx:
                type: object
                additionalProperties: true
                description: Additional validation context, when included.
    PlanQuotaError:
      type: object
      required:
        - detail
      properties:
        detail:
          type: object
          required:
            - error_code
            - meter
            - plan_id
            - limit
            - resets_at
            - message
          properties:
            error_code:
              type: string
              enum:
                - PLAN_LIMIT_REACHED
            meter:
              type: string
              description: >-
                Usage meter that reached its limit. Tools API calls use
                api_calls.
            plan_id:
              type: string
              description: Plan identifier for the key owner.
            limit:
              type: integer
              description: Quota for this meter.
            resets_at:
              type: string
              format: date-time
              nullable: true
              description: Quota reset time, or null if unknown.
            message:
              type: string
              description: Explanation of the quota restriction.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````