> ## 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.

# POST /analyze — Analyze an Ethereum Transaction Hash

> POST /analyze accepts an Ethereum tx hash and returns a TxReport with intent classification, token economics, flow attribution, and more.

`POST /analyze` is the core endpoint. Send a JSON body with a transaction hash and receive a versioned `TxReport` containing the complete analysis — intent classification, token economics, flow attribution, and more.

## Request

**URL:** `https://paralens-production.up.railway.app/analyze`\
**Method:** `POST`\
**Content-Type:** `application/json`

### Body Parameters

<ParamField body="tx_hash" type="string" required>
  A 32-byte Ethereum transaction hash with a `0x` prefix. Must be exactly 66 characters total (the `0x` prefix followed by 64 lowercase hex characters).

  Example: `0x48f1494c42c04e0f6243970b1dfab3a2b17b9d27ba65682e68e384c11752cf18`
</ParamField>

<ParamField body="chain" type="string">
  Chain identifier for the network the transaction belongs to. Defaults to `ethereum` if omitted.

  Accepted values: `ethereum`, `mainnet`, `eth`, `1`
</ParamField>

### Example Request

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

## Response

### Success — `200 OK`

Returns a `TxReport` JSON object. See [TxReport Schema](/docs/api-reference/tx-report) for the full field reference.

### Client Error — `400 Bad Request`

Returned when the request body is malformed, the hash is invalid, or the chain is not supported.

```json theme={null}
{ "error": "invalid tx_hash `0xdeadbeef`" }
```

```json theme={null}
{ "error": "unsupported chain `polygon`" }
```

### Upstream Error — `502 Bad Gateway`

Returned when ParaLens is running but the RPC node, trace API, or analysis engine encountered an error.

```json theme={null}
{ "error": "analysis failed: trace endpoint returned empty result" }
```

### Example Response (truncated)

```json theme={null}
{
  "schema_version": 1,
  "chain": { "id": 1, "name": "ethereum" },
  "tx": {
    "hash": "0x48f1494c42c04e0f6243970b1dfab3a2b17b9d27ba65682e68e384c11752cf18",
    "block_number": 25256812,
    "signer": "0x5b43453fce04b92e190f391a83136bfbecedefd1",
    "to": "0xbdb3ba9ffe392549e1f8658dd2630c141fdf47b6",
    "etherscan_url": "https://etherscan.io/tx/0x48f1494c42c04e0f6243970b1dfab3a2b17b9d27ba65682e68e384c11752cf18"
  },
  "classification": {
    "intent_kind": "AggregatedSwap",
    "intent_label": "Swap (via aggregator)",
    "status": "Proven",
    "confidence": "High",
    "actor": "0xbdb3ba9ffe392549e1f8658dd2630c141fdf47b6",
    "actor_matches_signer": false
  },
  "economics": {
    "token_in": "248.358547 DAI, 6789.606592 USDT, 11044.505802 USDC",
    "token_out": "8.238920 WETH",
    "net_usd_before_gas": { "text": "$-77.83", "available": true },
    "fee_usd": { "text": "$3.14", "available": true }
  }
}
```

## Code Examples

<CodeGroup>
  ```ts TypeScript theme={null}
  async function analyze(txHash: string) {
    const res = 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 (!res.ok) {
      const err = await res.json();
      throw new Error(err.error ?? 'Analysis failed');
    }
    return res.json();
  }
  ```

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

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

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

<Note>
  Responses are **not cached server-side**. The same hash can be analyzed multiple times; each call fetches fresh trace data from the RPC node. Because confirmed Ethereum transactions are immutable, consider caching responses on your side — keyed by `tx_hash` — to avoid redundant network round-trips and reduce latency for repeat lookups.
</Note>

For the full breakdown of every field in the response object, see the [TxReport Schema](/docs/api-reference/tx-report) reference.