Trading

Endpoints for opening trading positions, managing existing positions, and viewing portfolio P&L.

Open Trade

Open a new trading position with flexible leg configurations. Supports market buys, limit orders, stop losses, take profits, and quant-based entries/exits.

POST /api/v1/trade/open

Auth: API Key

Examples

Simple Market Buy:

curl -X POST https://api.droyd.ai/api/v1/trade/open \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 123,
    "legs": [
      { "type": "market_buy", "amountUSD": 100 }
    ]
  }'

Buy with Stop Loss and Take Profits:

curl -X POST https://api.droyd.ai/api/v1/trade/open \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contract_address": "So11111111111111111111111111111111111111112",
    "chain": "solana",
    "legs": [
      { "type": "market_buy", "amountUSD": 100 },
      { "type": "stop_loss", "amountUSD": 100, "triggerPercent": 0.10 },
      { "type": "take_profit", "amountUSD": 50, "triggerPercent": 0.25, "positionPercent": 0.5 },
      { "type": "take_profit", "amountUSD": 50, "triggerPercent": 0.50, "positionPercent": 0.5 }
    ]
  }'

Momentum-Based Entry with Exits:

curl -X POST https://api.droyd.ai/api/v1/trade/open \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 456,
    "legs": [
      { "type": "quant_buy", "amountUSD": 200, "triggerPercent": 15 },
      { "type": "quant_sell", "amountUSD": 200, "triggerPercent": -10 },
      { "type": "stop_loss", "amountUSD": 200, "triggerPercent": 0.15 }
    ],
    "rationale": "Entry on momentum breakout with protective stop"
  }'

Response

{
  "success": true,
  "error": null,
  "strategy": {
    "strategy_id": 789,
    "created_at": "2025-01-15T10:30:00Z",
    "legs": [...]
  },
  "metadata": {
    "project_id": 123,
    "project_name": "Example Token",
    "project_symbol": "EXT",
    "legs_created": 4,
    "resolved_from": "project_id"
  }
}

Request Parameters

Parameter	Type	Required	Default	Description
`project_id`	number	Conditional	-	Project ID (use this OR contract_address)
`contract_address`	string	Conditional	-	Contract address (use this OR project_id)
`chain`	string	No	`solana`	Blockchain chain (required if using contract_address)
`legs`	array	Yes	-	Array of trade legs (1-10 items)
`rationale`	string	No	-	Optional rationale for the trade

Leg Parameters

Parameter	Type	Required	Description
`type`	string	Yes	Leg type: `market_buy`, `limit_order`, `stop_loss`, `take_profit`, `quant_buy`, `quant_sell`
`amountUSD`	number	Yes	Amount in USD to trade (min: 1)
`triggerPercent`	number	Conditional	Required for all types except `market_buy`
`positionPercent`	number	No	Portion of position (0-1, default: 1)

Trigger Interpretation by Leg Type

Leg Type	triggerPercent Meaning
`limit_order`	Price drop % (0.05 = buy at 5% below current)
`stop_loss`	Price drop % (0.10 = sell at 10% below entry)
`take_profit`	Price rise % (0.20 = sell at 20% above entry)
`quant_buy`	Momentum score threshold (e.g., 15 = buy when score reaches 15)
`quant_sell`	Momentum score threshold (e.g., -10 = sell when score reaches -10)

Manage Trade

Manage existing trading positions. Close positions, execute additional buys/sells, or modify strategy legs.

POST /api/v1/trade/manage

Auth: API Key

Examples

Close Entire Position:

curl -X POST https://api.droyd.ai/api/v1/trade/manage \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_id": 789,
    "action": "close"
  }'

Execute Additional Buy:

curl -X POST https://api.droyd.ai/api/v1/trade/manage \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_id": 789,
    "action": "buy",
    "amountUSD": 50
  }'

Partial Sell:

curl -X POST https://api.droyd.ai/api/v1/trade/manage \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_id": 789,
    "action": "sell",
    "sellPercent": 0.5
  }'

Update Strategy Legs:

curl -X POST https://api.droyd.ai/api/v1/trade/manage \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_id": 789,
    "action": "update",
    "legs": [
      { "leg_action": "add", "type": "take_profit", "amountUSD": 50, "triggerPercent": 0.30 },
      { "leg_action": "update", "leg_id": 123, "triggerPercent": 0.15 },
      { "leg_action": "remove", "leg_id": 456 }
    ]
  }'

Response

{
  "success": true,
  "error": null,
  "data": {
    "action": "sell",
    "strategy_id": 789,
    "transaction": {
      "tx_signature": "5abc123...",
      "amount_sold": 50.00
    }
  }
}

Request Parameters

Parameter	Type	Required	Default	Description
`strategy_id`	number	Yes	-	Strategy ID to manage
`action`	string	Yes	-	Action: `close`, `buy`, `sell`, `update`
`amountUSD`	number	Conditional	-	Amount in USD (required for `buy`)
`portfolio_percent`	number	No	-	Portfolio percent for buy (0-100)
`sellPercent`	number	Conditional	-	Portion to sell 0-1 (required for `sell`)
`project_id`	number	No	-	Override project for buy/sell
`legs`	array	Conditional	-	Leg modifications (required for `update`)

Leg Modification Parameters (for `update` action)

Parameter	Type	Required	Description
`leg_action`	string	Yes	`add`, `update`, or `remove`
`leg_id`	number	Conditional	Required for `update` and `remove`
`type`	string	Conditional	Required for `add`
`amountUSD`	number	Conditional	Required for `add`
`triggerPercent`	number	Conditional	Required for `add` (except market_buy)
`positionPercent`	number	No	Portion of position (0-1)

Get Positions

Retrieve active trading positions and wallet holdings for the authenticated user.

GET /api/v1/trade/positions

Auth: API Key

Examples

Get Active Positions:

curl -X GET "https://api.droyd.ai/api/v1/trade/positions" \
  -H "x-droyd-api-key: YOUR_API_KEY"

Get All Positions (including completed):

curl -X GET "https://api.droyd.ai/api/v1/trade/positions?leg_status=all" \
  -H "x-droyd-api-key: YOUR_API_KEY"

Response

{
  "success": true,
  "error": null,
  "data": {
    "strategies": [
      {
        "strategy_id": 789,
        "created_at": "2025-01-15T10:30:00Z",
        "reasoning": "Momentum play on emerging AI token",
        "portfolio_percent": 5,
        "projects": [
          {
            "project_id": 123,
            "name": "Example Token",
            "symbol": "EXT",
            "price": 0.0045,
            "momentum_score_4h": 15,
            "momentum_score_24h": 22
          }
        ],
        "legs": [
          {
            "type": "market_buy",
            "status": "executed",
            "amountUSD": 100,
            "buy_or_sell": "buy",
            "positionPercent": 1
          },
          {
            "type": "stop_loss",
            "status": "pending",
            "amountUSD": 100,
            "buy_or_sell": "sell",
            "positionPercent": 1
          }
        ],
        "swaps": [
          {
            "swap_id": 456,
            "project_id": 123,
            "buy_or_sell": "buy",
            "amountNative": 22222.22,
            "amountUSD": 100,
            "reasoning": "Market buy executed",
            "date": "2025-01-15T10:30:05Z"
          }
        ],
        "pnl_summary": {
          "total_pnl_usd": 12.50,
          "total_pnl_pct": 12.5,
          "realized_pnl_usd": 0,
          "unrealized_pnl_usd": 12.50,
          "unrealized_pnl_pct": 12.5,
          "position_usd_open": 100,
          "position_usd_mark": 112.50,
          "cost_usd_bought": 100,
          "proceeds_usd_sold": 0,
          "last_updated": "2025-01-15T12:00:00Z"
        }
      }
    ],
    "overall_balance": 1500.00,
    "wallet_holdings": [
      {
        "card_type": "project",
        "balance_native": 50000,
        "balance_usd": 225.00,
        "portfolio_percent": 15,
        "network": "solana",
        "token_address": "So111...",
        "project_id": 123,
        "project_name": "Example Token",
        "project_symbol": "EXT",
        "current_price_usd": 0.0045
      }
    ],
    "summary": {
      "total_strategies": 3,
      "total_pnl_usd": 250.50,
      "total_pnl_pct": 12.5,
      "total_position_value": 1200.00
    }
  }
}

Query Parameters

Parameter	Type	Default	Description
`leg_status`	string	`active`	Filter: `active` (pending legs only) or `all` (include executed)

Tips

Use positionPercent to take partial profits (e.g., 0.5 = 50%)
Combine multiple take profit legs at different levels for scaled exits
Use project_id when you know the Droyd project ID (faster), or contract_address + chain for direct token lookup
Typical stop loss: 10-20% below entry (triggerPercent: 0.10 to 0.20)

Trading

Trading

Open Trade

Examples

Response

Request Parameters

Leg Parameters

Trigger Interpretation by Leg Type

Manage Trade

Examples

Response

Request Parameters

Leg Modification Parameters (for update action)

Get Positions

Examples

Response

Query Parameters

Tips

Leg Modification Parameters (for `update` action)