Historical Swaps

View completed trades (closed positions) with full profit/loss information.

Endpoints Overview

Method	Endpoint	Description
`GET`	`/api/v1/agent-historical-swaps`	List historical swaps
`GET`	`/api/v1/agent-historical-swaps/export`	Export swaps as CSV
`GET`	`/api/v1/agent-historical-swaps/:id`	Get a specific swap
`POST`	`/api/v1/agent-historical-swaps`	Create a swap record
`PUT`	`/api/v1/agent-historical-swaps/:id`	Update a swap
`DELETE`	`/api/v1/agent-historical-swaps/:id`	Delete a swap

All historical swap endpoints require JWT authentication.

List Historical Swaps

Get completed trades for an agent with comprehensive filtering.

GET /api/v1/agent-historical-swaps?agentId=:agentId

Query Parameters

Parameter	Type	Required	Description
`agentId`	UUID	Yes	Agent ID
`walletAddress`	string	No	Filter by wallet
`tokenAddress`	string	No	Filter by token
`tokenSymbol`	string	No	Filter by symbol
`startPurchaseTime`	ISO 8601	No	Purchase date from
`endPurchaseTime`	ISO 8601	No	Purchase date to
`startSaleTime`	ISO 8601	No	Sale date from
`endSaleTime`	ISO 8601	No	Sale date to
`signalId`	integer	No	Filter by signal
`minProfitLossUsd`	number	No	Minimum P/L USD
`maxProfitLossUsd`	number	No	Maximum P/L USD
`limit`	integer	No	Max results (default: 100, max: 1000)
`offset`	integer	No	Skip results (default: 0)

Response

Success (200)

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "agentId": "123e4567-e89b-12d3-a456-426614174000",
    "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "tokenAddress": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    "tokenSymbol": "BONK",
    "amount": "1000000",
    "purchasePrice": "0.00000234",
    "salePrice": "0.00000280",
    "changePercent": "19.66",
    "profitLossUsd": "4.60",
    "profitLossSol": "0.046",
    "purchaseTime": "2025-01-18T10:00:00.000Z",
    "saleTime": "2025-01-20T14:30:00.000Z",
    "purchaseTransactionId": "abc123",
    "saleTransactionId": "def456",
    "signalId": "12345",
    "closeReason": "manual",
    "createdAt": "2025-01-20T14:30:00.000Z"
  }
]

Response Fields

Field	Type	Description
`id`	UUID	Swap record ID
`agentId`	UUID	Agent ID
`walletAddress`	string	Wallet address
`tokenAddress`	string	Token mint address
`tokenSymbol`	string	Token ticker
`amount`	string	Token amount traded
`purchasePrice`	string	Buy price in SOL
`salePrice`	string	Sell price in SOL
`changePercent`	string	Price change percentage
`profitLossUsd`	string	P/L in USD
`profitLossSol`	string	P/L in SOL
`purchaseTime`	ISO 8601	When position was opened
`saleTime`	ISO 8601	When position was closed
`purchaseTransactionId`	string	Buy transaction ID
`saleTransactionId`	string	Sell transaction ID
`signalId`	string	Originating signal ID
`closeReason`	string	Why position was closed

Close Reasons

Reason	Description
`manual`	Manually closed by user
`stop_loss`	Triggered by stop loss
`stale_trade`	Closed due to position age limit

Example

# Get profitable trades
curl -X GET "https://your-instance.com/api/v1/agent-historical-swaps?agentId=123e...&minProfitLossUsd=0" \
  -H "Authorization: Bearer <access_token>"
 
# Get trades for a specific token
curl -X GET "https://your-instance.com/api/v1/agent-historical-swaps?agentId=123e...&tokenSymbol=BONK" \
  -H "Authorization: Bearer <access_token>"

Export Swaps

Export historical swaps as CSV for analysis.

GET /api/v1/agent-historical-swaps/export?agentId=:agentId

Query Parameters

Same as List Historical Swaps.

Response

Returns CSV file with headers:

id, tokenAddress, tokenSymbol, amount
purchasePrice, salePrice, changePercent
profitLossUsd, profitLossSol
purchaseTime, saleTime, closeReason

Example

curl -X GET "https://your-instance.com/api/v1/agent-historical-swaps/export?agentId=123e..." \
  -H "Authorization: Bearer <access_token>" \
  -o trades.csv

Get Historical Swap

Get a specific swap by ID.

GET /api/v1/agent-historical-swaps/:id

Path Parameters

Parameter	Type	Description
`id`	UUID	Swap record ID

Response

Success (200)

Returns the swap object.

Performance Analysis

Use query filters to analyze trading performance:

# This month's trades
curl "...?agentId=123&startSaleTime=2025-01-01T00:00:00Z"
 
# Losing trades (for analysis)
curl "...?agentId=123&maxProfitLossUsd=-0.01"
 
# Stop loss triggered trades
curl "...?agentId=123&closeReason=stop_loss"

Related Endpoints

Agents - Manage agents
Agent Positions - View open positions
Agent Transactions - Raw transaction data

Agent Transactions Trading Signals