# Wallet Batch API

## Overview

The Wallet Batch API provides endpoints for analyzing multiple Solana wallet addresses in batch. It offers a comprehensive analysis of trading performance, including metrics like PnL (Profit and Loss), trading patterns, and fee analysis.

### Key Features

* **Batch Processing**: Analyze up to 5 wallet addresses simultaneously
* **Asynchronous Processing**: Since batch processing can be time-consuming, we use asynchronous processing to prevent delays and ensure that requests are handled correctly, avoiding timeouts.
* **Comprehensive Analysis**: Detailed metrics including:
  * General trading performance
  * Closed trades analysis
  * Fee analysis
  * Trading venue usage
  * Time-based trading patterns

### Available Endpoints

1. **Process Wallet Batch** (`POST /process_wallet_batch`)
   * Initiates analysis for a batch of wallet addresses
   * Returns a task ID for tracking progress
2. **Check Batch Status** (`GET /batch_status/{task_id}`)
   * Retrieves the status and results of a batch processing task
   * Provides detailed analysis results when processing is complete

### Rate Limits

* Maximum 5 wallet addresses per batch request
* Requests limites are based on the API key tier defined below

## Process Wallet Batch

Process multiple wallet addresses in a single batch request.

### Endpoint

`POST /process_wallet_batch`

### Request Body

```json
{
  "wallet_addresses": ["address1", "address2", "address3"]
}
```

### Response

When request is accepted:

```json
{
  "task_id": "uuid-string",
  "message": "Processing started",
  "status_endpoint": "/batch_status/{task_id}"
}
```

## Check Batch Status

Check the status of a batch processing task.

### Endpoint

`GET /batch_status/{task_id}`

### Response

When processing:

```json
{
  "task_id": "uuid-string",
  "status": "processing"
}
```

When complete with some errors:

```json
{
    "task_id": "uuid-string",
    "status": "completed",
    "created_at": "2024-03-21T15:30:00Z",
    "completed_at": "2024-03-21T15:31:00Z",
    "results": [
        {
            "duration": 30,
            "wallet_address": "wallet-address-1",
            "summary": {
                "general_performance": {
                    "first_trade_timestamp": "2024-03-20T10:00:00Z",
                    "last_trade_timestamp": "2024-03-21T15:30:00Z",
                    "tokens_traded": 10,
                    "trades_closed": 8,
                    "trades_open": 2,
                    "total_sol_spent": 50.12345,
                    "total_sol_received": 55.54321,
                    "net_sol": 5.41976
                },
                "closed_trades_overview": {
                    "winners": 6,
                    "losses": 2,
                    "win_rate_percent": 75.0,
                    "average_trade_size_sol": 6.26543,
                    "mean_pnl_sol": 0.67747,
                    "mean_pnl_percent": 10.8234,
                    "std_pnl_sol": 0.32156,
                    "std_pnl_percent": 5.1234,
                    "min_pnl_sol": -1.23456,
                    "min_pnl_percent": -15.6789,
                    "10th_percentile_pnl_sol": -0.54321,
                    "10th_percentile_pnl_percent": -8.7654,
                    "25th_percentile_pnl_sol": 0.12345,
                    "25th_percentile_pnl_percent": 2.3456,
                    "50th_percentile_pnl_sol": 0.65432,
                    "50th_percentile_pnl_percent": 9.8765,
                    "75th_percentile_pnl_sol": 1.23456,
                    "75th_percentile_pnl_percent": 18.7654,
                    "90th_percentile_pnl_sol": 1.87654,
                    "90th_percentile_pnl_percent": 25.4321,
                    "max_pnl_sol": 2.34567,
                    "max_pnl_percent": 35.6789,
                    "total_pnl_sol": 5.41976,
                    "total_pnl_percent": 86.5432
                },
                "fees": {
                    "total_fee_spent_sol": 0.12345,
                    "avg_fee_per_trade_sol": 0.01543
                },
                "wallet": {
                    "wallet": "wallet-address"
                },
                "venues": {
                    "venues_list": "Jupiter, Raydium, Orca"
                },
                "deltas": {
                    "overall_mean_delta": 3600,
                    "average_trades_per_token": 2.5,
                    "overall_min_delta": 300,
                    "10th_percentile": 600,
                    "25th_percentile": 1800,
                    "50th_percentile": 3600,
                    "75th_percentile": 7200,
                    "90th_percentile": 14400,
                    "overall_max_delta": 86400
                }
            }
        },
        {
            "wallet_address": "wallet-address-2",
            "error": "No swaps found"
        }
    ]
}
```

When all wallets fail:

```json
{
    "task_id": "uuid-string",
    "status": "completed",
    "created_at": "2024-03-21T15:30:00Z",
    "completed_at": "2024-03-21T15:31:00Z",
    "results": [
        {
            "wallet_address": "wallet-address-1",
            "error": "No swaps found"
        },
        {
            "wallet_address": "wallet-address-2",
            "error": "Invalid wallet address"
        }
    ]
}
```

When task not found:

```json
{
  "detail": "Task not found"
}
```

### Common Error Messages

| Error Message             | Description                                                |
| ------------------------- | ---------------------------------------------------------- |
| "No swaps found"          | The wallet has no swap transactions in the analyzed period |
| "Invalid wallet address"  | The provided address is not a valid Solana address         |
| "Error processing wallet" | Generic error occurred while processing the wallet         |

### Error Responses

* `400 Bad Request`: When more than 5 wallet addresses are provided

```json
{
  "detail": "Maximum of 5 wallet addresses allowed per batch"
}
```

* `500 Internal Server Error`: When an error occurs during processing

## Summary Fields Documentation

### General Performance

These fields provide an overview of the wallet's trading activity:

| Field                   | Type         | Description                                                       |
| ----------------------- | ------------ | ----------------------------------------------------------------- |
| `first_trade_timestamp` | ISO datetime | Date and time of the wallet's first trade in the analyzed period  |
| `last_trade_timestamp`  | ISO datetime | Date and time of the wallet's most recent trade                   |
| `tokens_traded`         | integer      | Total number of unique tokens traded                              |
| `trades_closed`         | integer      | Number of completed trading positions                             |
| `trades_open`           | integer      | Number of currently open positions                                |
| `total_sol_spent`       | float        | Total amount of SOL used for purchases                            |
| `total_sol_received`    | float        | Total amount of SOL received from sales                           |
| `net_sol`               | float        | Net profit/loss in SOL (total\_sol\_received - total\_sol\_spent) |

### Closed Trades Overview

These fields analyze the performance of completed trades:

| Field                    | Type    | Description                                                        |
| ------------------------ | ------- | ------------------------------------------------------------------ |
| `winners`                | integer | Number of trades that resulted in profit                           |
| `losses`                 | integer | Number of trades that resulted in loss                             |
| `win_rate_percent`       | float   | Percentage of winning trades (winners / (winners + losses) \* 100) |
| `average_trade_size_sol` | float   | Average amount of SOL used per trade                               |
| `mean_pnl_sol`           | float   | Average profit/loss per trade in SOL                               |
| `mean_pnl_percent`       | float   | Average profit/loss per trade as a percentage                      |
| `std_pnl_sol`            | float   | Standard deviation of profit/loss in SOL (volatility measure)      |
| `std_pnl_percent`        | float   | Standard deviation of profit/loss percentage                       |
| `min_pnl_sol`            | float   | Largest loss in SOL                                                |
| `min_pnl_percent`        | float   | Largest loss as a percentage                                       |
| `max_pnl_sol`            | float   | Largest profit in SOL                                              |
| `max_pnl_percent`        | float   | Largest profit as a percentage                                     |
| `total_pnl_sol`          | float   | Total profit/loss in SOL                                           |
| `total_pnl_percent`      | float   | Total profit/loss as a percentage                                  |

#### Percentile Metrics

These fields show the distribution of profits/losses:

| Field                         | Type  | Description                                        |
| ----------------------------- | ----- | -------------------------------------------------- |
| `10th_percentile_pnl_sol`     | float | 10% of trades performed worse than this SOL value  |
| `10th_percentile_pnl_percent` | float | 10% of trades performed worse than this percentage |
| `25th_percentile_pnl_sol`     | float | 25% of trades performed worse than this SOL value  |
| `25th_percentile_pnl_percent` | float | 25% of trades performed worse than this percentage |
| `50th_percentile_pnl_sol`     | float | Median profit/loss in SOL                          |
| `50th_percentile_pnl_percent` | float | Median profit/loss percentage                      |
| `75th_percentile_pnl_sol`     | float | 75% of trades performed worse than this SOL value  |
| `75th_percentile_pnl_percent` | float | 75% of trades performed worse than this percentage |
| `90th_percentile_pnl_sol`     | float | 90% of trades performed worse than this SOL value  |
| `90th_percentile_pnl_percent` | float | 90% of trades performed worse than this percentage |

### Fees

Information about transaction fees:

| Field                   | Type  | Description                                   |
| ----------------------- | ----- | --------------------------------------------- |
| `total_fee_spent_sol`   | float | Total amount spent on transaction fees in SOL |
| `avg_fee_per_trade_sol` | float | Average fee per trade in SOL                  |

### Wallet

Wallet identification:

| Field    | Type   | Description                       |
| -------- | ------ | --------------------------------- |
| `wallet` | string | The wallet address being analyzed |

### Venues

Trading venue information:

| Field         | Type   | Description                                                                     |
| ------------- | ------ | ------------------------------------------------------------------------------- |
| `venues_list` | string | Comma-separated list of trading platforms used (e.g., "Jupiter, Raydium, Orca") |

### Deltas

Time-based analysis of trading patterns:

| Field                      | Type    | Description                                            |
| -------------------------- | ------- | ------------------------------------------------------ |
| `overall_mean_delta`       | integer | Average time between trades in seconds                 |
| `average_trades_per_token` | float   | Average number of trades performed per unique token    |
| `overall_min_delta`        | integer | Shortest time between any two trades in seconds        |
| `overall_max_delta`        | integer | Longest time between any two trades in seconds         |
| `10th_percentile`          | integer | 10% of trade intervals are shorter than this (seconds) |
| `25th_percentile`          | integer | 25% of trade intervals are shorter than this (seconds) |
| `50th_percentile`          | integer | Median time between trades in seconds                  |
| `75th_percentile`          | integer | 75% of trade intervals are shorter than this (seconds) |
| `90th_percentile`          | integer | 90% of trade intervals are shorter than this (seconds) |

**Notes:**

* All SOL values are rounded to 5 decimal places
* Percentages are expressed as floating-point numbers (e.g., 75.0 for 75%)
* Time deltas are in seconds
* Timestamps are in ISO 8601 format
* PnL stands for Profit and Loss

## Example Usage

### Python Example

```python
import requests
import time

# Your API key
API_KEY = "your_api_key_here"

# Headers for authentication
headers = {
    "Content-Type": "application/json",
    "X-API-Key": API_KEY
}

# Start batch processing
batch_request = {
    "wallet_addresses": [
        "wallet1address",
        "wallet2address"
    ]
}

# Make request with API key in headers
response = requests.post(
    "https://api.dedge.pro/process_wallet_batch",
    headers=headers,
    json=batch_request
)
task_id = response.json()["task_id"]

# Poll status until complete
while True:
    status_response = requests.get(
        f"https://api.dedge.pro/batch_status/{task_id}",
        headers=headers
    )
    status_data = status_response.json()
    
    if status_data["status"] == "processing":
        time.sleep(15)  # Wait 15 seconds before checking again
        continue
        
    if status_data["status"] == "completed":
        print("Processing complete!")
        print("Results:", status_data["results"])
        break
        
    if status_data["status"] == "error":
        print("Error occurred:", status_data["error"])
        break

# Handle rate limits and errors
if status_response.status_code == 429:
    print("Rate limit exceeded. Please wait before making more requests.")
elif status_response.status_code == 403:
    print("Invalid API key")
```

### JavaScript/Node.js Example

```javascript
const axios = require('axios');

const API_KEY = 'your_api_key_here';

const headers = {
  'Content-Type': 'application/json',
  'X-API-Key': API_KEY
};

async function analyzeBatch() {
  try {
    // Start batch processing
    const batchResponse = await axios.post('https://api.dedge.pro/process_wallet_batch', {
      wallet_addresses: ['wallet1address', 'wallet2address']
    }, { headers });

    const taskId = batchResponse.data.task_id;

    // Poll status until complete
    while (true) {
      const statusResponse = await axios.get(
        `https://api.dedge.pro/batch_status/${taskId}`,
        { headers }
      );
      
      const statusData = statusResponse.data;
      
      if (statusData.status === 'processing') {
        await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds
        continue;
      }
      
      if (statusData.status === 'completed') {
        console.log('Processing complete!');
        console.log('Results:', statusData.results);
        break;
      }
      
      if (statusData.status === 'error') {
        console.error('Error occurred:', statusData.error);
        break;
      }
    }
  } catch (error) {
    if (error.response) {
      if (error.response.status === 429) {
        console.error('Rate limit exceeded. Please wait before making more requests.');
      } else if (error.response.status === 403) {
        console.error('Invalid API key');
      } else {
        console.error('Error:', error.response.data);
      }
    }
  }
}
```

### cURL Example

```bash
# Start batch processing
curl -X POST "https://api.dedge.pro/process_wallet_batch" \
     -H "Content-Type: application/json" \
     -H "X-API-Key: your_api_key_here" \
     -d '{
           "wallet_addresses": [
             "wallet1address",
             "wallet2address"
           ]
         }'

# Check status (replace {task_id} with the actual task ID from the previous response)
curl "https://api.dedge.pro/batch_status/{task_id}" \
     -H "X-API-Key: your_api_key_here"
```

### Rate Limits and API Keys

Different API key tiers have different rate limits:

| Tier      | Rate Limit | Daily Limit |
| --------- | ---------- | ----------- |
| Ultimate  | 5 req/min  | 100/day     |
| Unlimited | 10 req/min | Unlimited   |

When rate limits are exceeded, the API will return a 429 status code with an error message. It's recommended to implement exponential backoff in your client code to handle rate limiting gracefully.

### Error Handling

Common error responses:

```json
// Rate limit exceeded (HTTP 429)
{
  "detail": "Rate limit exceeded. Maximum 300 requests per minute."
}

// Invalid API key (HTTP 403)
{
  "detail": "Invalid API key"
}

// Daily limit exceeded (HTTP 429)
{
  "detail": "Daily limit exceeded. Maximum 10,000 requests per day."
}
```

### Best Practices

1. **Store API Keys Securely**: Never expose your API key in client-side code or public repositories.
2. **Handle Rate Limits**: Implement proper error handling and backoff strategies for rate limits.
3. **Batch Efficiently**: Group wallet addresses into batches of up to 5 to minimize API calls.
4. **Monitor Usage**: Keep track of your API usage to stay within your tier's limits.
5. **Use Async Endpoints**: The batch processing is asynchronous - always check the task status endpoint for results.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dedge-1.gitbook.io/dedge-sol-analyzer/api-documentation/readme/wallet-batch-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.