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

{
  "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

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)

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

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

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

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

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

# 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

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)

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)

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

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

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

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