managing-apps/src/Managing.Web3Proxy/POSITION_HISTORY_CURL_EXAMPLES.md

# GMX Position History API - cURL Examples

## Endpoint
```
GET /api/gmx/position-history
```

## Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `account` | string | Yes | Wallet address |
| `pageIndex` | integer | No | Page index for pagination (default: 0) |
| `pageSize` | integer | No | Items per page (default: 20) |
| `ticker` | string | No | Filter by specific ticker (e.g., "BTC", "ETH", "HYPE") |
| `fromDateTime` | string | No | Start date in ISO 8601 format (e.g., "2024-10-17T00:00:00.000Z") |
| `toDateTime` | string | No | End date in ISO 8601 format (e.g., "2024-10-24T23:59:59.999Z") |

## Response Format

```json
{
  "success": true,
  "positions": [
    {
      "ticker": "BTC",
      "direction": "Long",
      "price": 67500.00,
      "quantity": 0.1,
      "leverage": 5,
      "status": "Finished",
      "pnl": 125.50,
      "UiFees": 2.30,
      "GasFees": 0.50,
      "date": "2024-10-20T15:30:00.000Z",
      "ProfitAndLoss": {
        "realized": 125.50,
        "net": 122.70
      }
    }
  ],
  "pageIndex": 0,
  "pageSize": 20,
  "count": 1
}
```

## cURL Examples

### Example 1: Basic - Get All Positions

```bash
curl -X GET "http://localhost:4111/api/gmx/position-history?account=0xb54a2f65D79bDeD20F9cBd9a1F85C3855EC3c210&pageIndex=0&pageSize=20" \
  -H "Content-Type: application/json"
```

### Example 2: Filter by Date Range (Last 7 Days)

```bash
# Set date variables
FROM_DATE="2024-10-17T00:00:00.000Z"
TO_DATE="2024-10-24T23:59:59.999Z"

curl -X GET "http://localhost:4111/api/gmx/position-history?account=0xb54a2f65D79bDeD20F9cBd9a1F85C3855EC3c210&pageIndex=0&pageSize=10&fromDateTime=${FROM_DATE}&toDateTime=${TO_DATE}" \
  -H "Content-Type: application/json"
```

**URL Encoded Version:**
```bash
curl -X GET "http://localhost:4111/api/gmx/position-history?account=0xb54a2f65D79bDeD20F9cBd9a1F85C3855EC3c210&pageIndex=0&pageSize=10&fromDateTime=2024-10-17T00%3A00%3A00.000Z&toDateTime=2024-10-24T23%3A59%3A59.999Z" \
  -H "Content-Type: application/json"
```

### Example 3: Filter by Ticker

```bash
curl -X GET "http://localhost:4111/api/gmx/position-history?account=0xb54a2f65D79bDeD20F9cBd9a1F85C3855EC3c210&pageIndex=0&pageSize=10&ticker=HYPE" \
  -H "Content-Type: application/json"
```

### Example 4: Filter by Date Range AND Ticker

```bash
FROM_DATE="2024-10-17T00:00:00.000Z"
TO_DATE="2024-10-24T23:59:59.999Z"

curl -X GET "http://localhost:4111/api/gmx/position-history?account=0xb54a2f65D79bDeD20F9cBd9a1F85C3855EC3c210&pageIndex=0&pageSize=10&ticker=HYPE&fromDateTime=${FROM_DATE}&toDateTime=${TO_DATE}" \
  -H "Content-Type: application/json"
```

### Example 5: Using jq for Pretty Output

```bash
curl -X GET "http://localhost:4111/api/gmx/position-history?account=0xb54a2f65D79bDeD20F9cBd9a1F85C3855EC3c210&pageIndex=0&pageSize=20" \
  -H "Content-Type: application/json" \
  | jq '.'
```

### Example 6: Extract Specific Fields with jq

```bash
# Get only ticker, PnL, and date
curl -X GET "http://localhost:4111/api/gmx/position-history?account=0xb54a2f65D79bDeD20F9cBd9a1F85C3855EC3c210&pageIndex=0&pageSize=20" \
  -H "Content-Type: application/json" \
  | jq '.positions[] | {ticker: .ticker, pnl: .pnl, date: .date}'
```

### Example 7: Calculate Total PnL

```bash
curl -X GET "http://localhost:4111/api/gmx/position-history?account=0xb54a2f65D79bDeD20F9cBd9a1F85C3855EC3c210&pageIndex=0&pageSize=500" \
  -H "Content-Type: application/json" \
  | jq '.positions | map(.pnl) | add'
```

## Dynamic Date Calculation (Bash)

### Get positions from last 7 days (macOS)
```bash
FROM_DATE=$(date -u -v-7d +"%Y-%m-%dT%H:%M:%S.000Z")
TO_DATE=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")

curl -X GET "http://localhost:4111/api/gmx/position-history?account=0xb54a2f65D79bDeD20F9cBd9a1F85C3855EC3c210&pageIndex=0&pageSize=10&fromDateTime=${FROM_DATE}&toDateTime=${TO_DATE}" \
  -H "Content-Type: application/json"
```

### Get positions from last 7 days (Linux)
```bash
FROM_DATE=$(date -u -d "7 days ago" +"%Y-%m-%dT%H:%M:%S.000Z")
TO_DATE=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")

curl -X GET "http://localhost:4111/api/gmx/position-history?account=0xb54a2f65D79bDeD20F9cBd9a1F85C3855EC3c210&pageIndex=0&pageSize=10&fromDateTime=${FROM_DATE}&toDateTime=${TO_DATE}" \
  -H "Content-Type: application/json"
```

### Get positions from last 30 days
```bash
# macOS
FROM_DATE=$(date -u -v-30d +"%Y-%m-%dT%H:%M:%S.000Z")
TO_DATE=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")

# Linux
FROM_DATE=$(date -u -d "30 days ago" +"%Y-%m-%dT%H:%M:%S.000Z")
TO_DATE=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")

curl -X GET "http://localhost:4111/api/gmx/position-history?account=0xb54a2f65D79bDeD20F9cBd9a1F85C3855EC3c210&pageIndex=0&pageSize=100&fromDateTime=${FROM_DATE}&toDateTime=${TO_DATE}" \
  -H "Content-Type: application/json"
```

## Production URL

For production, replace `localhost:4111` with your production URL:

```bash
# Example with production URL
PRODUCTION_URL="https://your-production-domain.com"

curl -X GET "${PRODUCTION_URL}/api/gmx/position-history?account=0xb54a2f65D79bDeD20F9cBd9a1F85C3855EC3c210&pageIndex=0&pageSize=20" \
  -H "Content-Type: application/json"
```

## Testing Script

Run the provided test script:

```bash
chmod +x test-position-history-curl.sh
./test-position-history-curl.sh
```

## Notes

1. **ISO 8601 Format**: Dates must be in ISO 8601 format (e.g., `2024-10-24T15:30:00.000Z`)
2. **URL Encoding**: When using dates in URLs, colons (`:`) should be encoded as `%3A`
3. **Pagination**: Use `pageIndex` and `pageSize` for large result sets
4. **Date Range**: Both `fromDateTime` and `toDateTime` are optional; you can use one or both
5. **Ticker Format**: Use the ticker symbol as it appears in GMX (e.g., "BTC", "ETH", "HYPE")

## Troubleshooting

### Empty Results
- Verify the account address has trading history
- Check if the date range includes periods with activity
- Try without date filters first to see if any data exists

### Invalid Date Format Error
- Ensure dates are in ISO 8601 format
- Use `.000Z` for milliseconds and UTC timezone
- Example: `2024-10-24T15:30:00.000Z`

### Connection Refused
- Verify Web3Proxy is running on port 4111
- Check if the service is accessible: `curl http://localhost:4111/health`