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

# Transaction Graph

> Visualize ERC-20 token transfer relationships as a node/edge graph

## Overview

Generates a transaction graph for any Ethereum address, showing ERC-20 token transfer relationships as nodes and edges. The graph is a tripartite structure: wallets connect to tokens, which connect to other wallets.

<Info>
  Results are cached for **10 minutes**. First requests typically take 2-5 seconds; cached responses return in under 100ms.
</Info>

## Authentication

This endpoint supports two authentication methods:

| Method       | Header                               | Cost         |
| ------------ | ------------------------------------ | ------------ |
| API Token    | `Authorization: Bearer YOUR_API_KEY` | 5 Cred Units |
| x402 Payment | `X-PAYMENT: <signed_payment>`        | \$0.05 USDC  |

<Tip>
  **x402 payments** allow instant, accountless access. Pay per request with USDC on Base - no signup required.
  [Try it live →](https://credprotocol.com/try)
</Tip>

## Path Parameters

<ParamField path="address" type="string" required>
  Ethereum address or ENS name (e.g., `vitalik.eth` or `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045`)
</ParamField>

## Query Parameters

<ParamField query="chain_id" type="integer" default="1">
  Chain ID of the blockchain network to analyze. Defaults to Ethereum Mainnet.
</ParamField>

## Supported Networks

| Chain               | Chain ID |
| ------------------- | -------- |
| Ethereum Mainnet    | `1`      |
| Optimism            | `10`     |
| Binance Smart Chain | `56`     |
| Polygon             | `137`    |
| Base                | `8453`   |
| Arbitrum            | `42161`  |
| Avalanche           | `43114`  |
| Scroll              | `534352` |
| Linea               | `59144`  |

## Response

<ResponseField name="address" type="string">
  The resolved Ethereum address (checksummed)
</ResponseField>

<ResponseField name="chain_id" type="integer">
  The chain ID that was queried
</ResponseField>

<ResponseField name="chain_name" type="string">
  Human-readable name of the blockchain network
</ResponseField>

<ResponseField name="total_transactions" type="integer">
  Total number of ERC-20 token transfers found for this address on the specified chain
</ResponseField>

<ResponseField name="nodes" type="array">
  Array of graph nodes representing wallets and tokens.

  <Expandable title="Node properties">
    <ResponseField name="id" type="string">
      Unique identifier — wallet address or token symbol
    </ResponseField>

    <ResponseField name="label" type="string">
      Display label for the node
    </ResponseField>

    <ResponseField name="group" type="string">
      Node type: `wallet` or `token`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="edges" type="array">
  Array of graph edges representing token transfer relationships.

  <Expandable title="Edge properties">
    <ResponseField name="from" type="string">
      Source node ID
    </ResponseField>

    <ResponseField name="to" type="string">
      Target node ID
    </ResponseField>

    <ResponseField name="label" type="string">
      Transfer direction: `SENT` or `RECEIVED`
    </ResponseField>
  </Expandable>
</ResponseField>

## Graph Structure

The graph uses a **tripartite structure** to represent token transfers:

```
Wallet A  --SENT-->  TOKEN  --RECEIVED-->  Wallet B
```

* **Wallet nodes** represent Ethereum addresses involved in transfers
* **Token nodes** represent ERC-20 tokens that were transferred
* **Edges** connect wallets to tokens with a direction (`SENT` or `RECEIVED`)

This structure makes it easy to identify which tokens flow between which counterparties.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.credprotocol.com/api/v2/graph/address/vitalik.eth?chain_id=1" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.credprotocol.com/api/v2/graph/address/vitalik.eth?chain_id=1',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const graph = await response.json();
  console.log(`Nodes: ${graph.nodes.length}`);
  console.log(`Edges: ${graph.edges.length}`);
  console.log(`Total Transactions: ${graph.total_transactions}`);
  ```

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

  response = requests.get(
      "https://api.credprotocol.com/api/v2/graph/address/vitalik.eth",
      params={"chain_id": 1},
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )

  graph = response.json()
  print(f"Nodes: {len(graph['nodes'])}")
  print(f"Edges: {len(graph['edges'])}")
  print(f"Total Transactions: {graph['total_transactions']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "chain_id": 1,
    "chain_name": "Ethereum Mainnet",
    "total_transactions": 150,
    "nodes": [
      { "id": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "label": "0xd8dA...6045", "group": "wallet" },
      { "id": "USDC", "label": "USDC", "group": "token" },
      { "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F", "label": "0x71C7...976F", "group": "wallet" }
    ],
    "edges": [
      { "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "to": "USDC", "label": "SENT" },
      { "from": "USDC", "to": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F", "label": "RECEIVED" }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "detail": "Invalid Ethereum address"
  }
  ```

  ```json 401 theme={null}
  {
    "detail": "Invalid or expired API token. Please create a new API token in /dashboard/console."
  }
  ```

  ```json 402 theme={null}
  {
    "error": "authentication_required",
    "message": "This endpoint requires authentication.",
    "cred_units": 5,
    "options": [
      { "method": "api_token", "cost": "5 Cred Units" },
      { "method": "x402_payment", "price": "$0.05", "currency": "USDC" }
    ]
  }
  ```
</ResponseExample>

## Use Cases

<AccordionGroup>
  <Accordion title="Counterparty Analysis">
    Identify the major counterparties for a wallet — who they transact with most and through which tokens.
  </Accordion>

  <Accordion title="Wash Trading Detection">
    Spot circular transfer patterns where tokens flow between a small set of wallets, indicating potential wash trading.
  </Accordion>

  <Accordion title="Fund Flow Tracking">
    Trace how funds move through a network of addresses to understand capital flows and identify intermediary wallets.
  </Accordion>

  <Accordion title="Network Visualization">
    Build interactive graph visualizations to explore transaction relationships in dApps, dashboards, or compliance tools.
  </Accordion>
</AccordionGroup>

## Performance

* **Response Time**: 2-5 seconds (uncached), under 100ms (cached)
* **Caching**: Results cached for 10 minutes per address/chain combination
* **Data Source**: Etherscan API V2 (ERC-20 token transfers only)
* **Scope**: All historical token transfers for the address on the specified chain