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

# Get Started with the ParaLens Transaction API in 5 Minutes

> Send your first POST /analyze request and receive a full TxReport with intent, economics, and actor attribution in minutes. No signup needed.

ParaLens requires no signup or API key today. You POST a JSON body containing a `chain` and a `tx_hash`, and the API returns a full **TxReport** — intent classification, token economics, actor attribution, DeFi position effects, and more. The entire round-trip typically takes a few seconds.

<Note>
  No authentication is required today. Future-compatible clients should be prepared to pass `x-api-key: <api-key>` in request headers when key-based access is introduced.
</Note>

***

<Steps>
  <Step title="Send your first request">
    POST a transaction hash to the `/analyze` endpoint. The body requires two fields: `chain` (always `"ethereum"` for now) and `tx_hash`.

    ```bash theme={null}
    curl -X POST https://paralens-production.up.railway.app/analyze \
      -H 'content-type: application/json' \
      -d '{"chain":"ethereum","tx_hash":"0x48f1494c42c04e0f6243970b1dfab3a2b17b9d27ba65682e68e384c11752cf18"}'
    ```

    You will receive a `TxReport` JSON object in the response body. The top-level sections are `classification`, `economics`, `inventory_deltas`, `motifs`, `attribution`, `position_effects`, and `pipeline_stats`.
  </Step>

  <Step title="Read the classification">
    The `classification` section tells you what the transaction did and how confident the pipeline is.

    ```json theme={null}
    {
      "classification": {
        "intent_kind": "Swap",
        "intent_label": "Token Swap",
        "status": "Proven",
        "confidence": "High",
        "actor": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "actor_matches_signer": true
      }
    }
    ```

    | Field                  | What it means                                                                             |
    | ---------------------- | ----------------------------------------------------------------------------------------- |
    | `intent_kind`          | Machine-readable category (e.g., `Swap`, `Arbitrage`, `Liquidation`)                      |
    | `intent_label`         | Human-readable label suitable for display in a UI                                         |
    | `status`               | `Proven` — strong structural evidence found; `Suspected` — likely but not definitive      |
    | `confidence`           | `High`, `Medium`, or `Low` — how certain the classification is                            |
    | `actor_matches_signer` | `false` means the real economic actor differs from the wallet that signed the transaction |
  </Step>

  <Step title="Read the economics">
    The `economics` section gives you the financial summary: what went in, what came out, net USD value, and gas cost.

    ```json theme={null}
    {
      "economics": {
        "token_in": {
          "asset_label": "USDC",
          "quantity": "5000.00",
          "usd_value": { "text": "$5,000.00", "available": true }
        },
        "token_out": {
          "asset_label": "WETH",
          "quantity": "1.842",
          "usd_value": { "text": "$4,987.34", "available": true }
        },
        "net_usd_before_gas": { "text": "-$12.66", "available": true },
        "fee_usd": { "text": "$4.21", "available": true }
      }
    }
    ```

    | Field                | What it means                                                                 |
    | -------------------- | ----------------------------------------------------------------------------- |
    | `token_in`           | The primary asset spent by the economic actor                                 |
    | `token_out`          | The primary asset received by the economic actor                              |
    | `net_usd_before_gas` | Net USD change excluding gas (can be negative for normal swaps with slippage) |
    | `fee_usd`            | Total gas cost in USD at block-time prices                                    |

    USD values use the `DisplayMoney` shape — always check `available: true` before reading `text`. See [Core Concepts](/docs/core-concepts) for details.
  </Step>

  <Step title="Explore the full TxReport">
    The complete response includes additional sections: `inventory_deltas` (per-subject token flows), `motifs` (structural evidence patterns), `position_effects` (DeFi borrow/repay/liquidity events), `attribution` (protocol and contract labels), and `pipeline_stats` (timing and coverage metadata).

    See the [TxReport schema reference](/docs/api-reference/tx-report) for the full field-by-field breakdown.
  </Step>
</Steps>

***

## Request Examples

<CodeGroup>
  ```bash bash theme={null}
  curl -X POST https://paralens-production.up.railway.app/analyze \
    -H 'content-type: application/json' \
    -d '{"chain":"ethereum","tx_hash":"0x48f1494c42c04e0f6243970b1dfab3a2b17b9d27ba65682e68e384c11752cf18"}'
  ```

  ```ts typescript theme={null}
  async function analyze(txHash: string) {
    const response = await fetch('https://paralens-production.up.railway.app/analyze', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ chain: 'ethereum', tx_hash: txHash }),
    });
    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error ?? 'Analysis failed');
    }
    return response.json();
  }
  ```

  ```python python theme={null}
  import requests

  def analyze(tx_hash: str) -> dict:
      response = requests.post(
          'https://paralens-production.up.railway.app/analyze',
          json={'chain': 'ethereum', 'tx_hash': tx_hash},
      )
      response.raise_for_status()
      return response.json()
  ```
</CodeGroup>

***

## Next Steps

* [Core Concepts](/docs/core-concepts) — understand the TxReport structure, intent kinds, motifs, and valuation model
* [API Reference: /analyze](/docs/api-reference/analyze) — full request/response schema for the analyze endpoint