Agent Positions

View and manage open trading positions for agents.

Endpoints Overview

Method	Endpoint	Description
`GET`	`/api/v1/agent-positions/:agentId`	List positions for an agent
`POST`	`/api/v1/agent-positions/:agentId/:positionId/close`	Close a position

All position endpoints require JWT authentication. Positions can also be accessed via /api/v1/agents/:id/positions.

List Positions

Get all open positions for an agent with enriched market data.

GET /api/v1/agent-positions/:agentId

Path Parameters

Parameter	Type	Description
`agentId`	UUID	Agent ID

Query Parameters

Parameter	Type	Required	Description
`walletAddress`	string	No	Filter by specific wallet

Response

Success (200)

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "agentId": "123e4567-e89b-12d3-a456-426614174000",
    "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "tokenAddress": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    "tokenSymbol": "BONK",
    "purchase": {
      "priceNative": 0.00000234,
      "priceUsd": 0.000234,
      "amount": 1000000,
      "transaction": {
        "id": "abc123",
        "hash": "5vG3...",
        "time": "2025-01-20T08:00:00.000Z"
      }
    },
    "current": {
      "priceNative": 0.00000256,
      "priceUsd": 0.000256,
      "valueNative": 2.56,
      "valueUsd": 256.00
    },
    "profitLoss": {
      "native": 0.22,
      "usd": 22.00,
      "percent": 9.4,
      "priceChangePercent": 9.4
    },
    "stopLoss": {
      "percentage": 25,
      "peakPrice": 0.00000260
    },
    "createdAt": "2025-01-20T08:00:00.000Z",
    "updatedAt": "2025-01-20T10:30:00.000Z"
  }
]

Response Structure

Field	Type	Description
`id`	UUID	Position ID
`agentId`	UUID	Agent ID
`walletAddress`	string	Wallet holding the position
`tokenAddress`	string	Token mint address
`tokenSymbol`	string	Token ticker symbol
`purchase`	object	Purchase details
`purchase.priceNative`	number	Purchase price in SOL
`purchase.priceUsd`	number	Purchase price in USD
`purchase.amount`	number	Token amount purchased
`purchase.transaction`	object	Purchase transaction details
`current`	object	Current market data
`current.priceNative`	number	Current price in SOL
`current.priceUsd`	number	Current price in USD
`current.valueNative`	number	Position value in SOL
`current.valueUsd`	number	Position value in USD
`profitLoss`	object	P/L metrics
`profitLoss.native`	number	P/L in SOL
`profitLoss.usd`	number	P/L in USD
`profitLoss.percent`	number	P/L percentage
`stopLoss`	object	Stop loss configuration
`stopLoss.percentage`	number	Stop loss percentage from peak
`stopLoss.peakPrice`	number	Highest price seen

Example

curl -X GET "https://your-instance.com/api/v1/agent-positions/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer <access_token>"

Close Position

Manually close an open position by executing a sell trade.

POST /api/v1/agent-positions/:agentId/:positionId/close

Path Parameters

Parameter	Type	Description
`agentId`	UUID	Agent ID
`positionId`	UUID	Position ID

Request

{
  "reason": "manual"
}

Field	Type	Required	Description
`reason`	string	No	Close reason: `manual` (default) or `stop_loss`

Response

Success (200)

{
  "success": true,
  "transactionId": "abc123",
  "historicalSwapId": "def456",
  "profitLossSol": 0.22,
  "profitLossUsd": 22.00,
  "changePercent": 9.4,
  "transactionHash": "5vG3..."
}

Field	Type	Description
`success`	boolean	Whether the close was successful
`transactionId`	string	Sale transaction ID
`historicalSwapId`	string	Historical swap record ID
`profitLossSol`	number	Realized P/L in SOL
`profitLossUsd`	number	Realized P/L in USD
`changePercent`	number	Price change percentage
`transactionHash`	string	On-chain transaction hash

Error Responses

Position Not Found (404)

{
  "error": "Position not found"
}

Insufficient Balance (400)

{
  "error": "Insufficient token balance"
}

Example

curl -X POST "https://your-instance.com/api/v1/agent-positions/123e.../abc.../close" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"reason": "manual"}'

⚠️

Closing a position executes a real trade. In live mode, this sells tokens on-chain via Jupiter.

Related Endpoints

Agents - Manage agents
Historical Swaps - View closed positions
Trading Signals - Send signals

Agent Balances Agent Transactions