Trading Endpoints

The Trading APIs allow you to place buy and sell orders, schedule trades, and monitor execution status. These endpoints are available for Trading Accounts only.

Place Trade

Endpoint: POST /trade

Description: Place a trading order (immediate or scheduled)

Request Body

// BUY Order (requires amount)
{
  "ticker": "AAPL",
  "orderSide": "BUY",
  "amount": 1000,
  "executeAt": "2025-01-15T09:30:00" // Optional: Schedule for EST/EDT time
}

// SELL Order (requires quantity)
{
  "ticker": "AAPL",
  "orderSide": "SELL",
  "quantity": 10,
  "executeAt": "2025-01-15T15:45:00" // Optional: Schedule for EST/EDT time
}

Parameters

Parameter	Type	Required	Description
`ticker`	string	Yes	Stock ticker symbol (e.g., `AAPL`, `GOOGL`)
`orderSide`	string	Yes	Order direction: `BUY` or `SELL`
`amount`	number	Conditional	Dollar amount for BUY orders (required for BUY)
`quantity`	number	Conditional	Number of shares for SELL orders (required for SELL)
`executeAt`	string	No	ISO 8601 timestamp in Eastern Time for scheduled execution

Important Notes

BUY Orders: Specify amount (dollar value), not quantity
SELL Orders: Specify quantity (number of shares), not amount
Scheduled Trades: Only one scheduled trade per ticker per partner is allowed
Time Zone: executeAt must be in Eastern Time (EST/EDT)
Time Zone: executeAt must be a future date/time
Market Hours: Trades execute during market hours (9:30 AM - 4:00 PM ET)

cURL Examples

# Immediate BUY Order
curl -X POST {{BASE_URL}}/trade \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ticker": "AAPL",
    "orderSide": "BUY",
    "amount": 1000
  }'

# Immediate SELL Order
curl -X POST {{BASE_URL}}/trade \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ticker": "AAPL",
    "orderSide": "SELL",
    "quantity": 10
  }'

# Scheduled BUY Order
curl -X POST {{BASE_URL}}/trade \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ticker": "MSFT",
    "orderSide": "BUY",
    "amount": 2500,
    "executeAt": "2025-01-15T09:30:00"
  }'

# Scheduled SELL Order
curl -X POST {{BASE_URL}}/trade \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ticker": "GOOGL",
    "orderSide": "SELL",
    "quantity": 5,
    "executeAt": "2025-01-15T15:45:00"
  }'

Node.js Examples

const axios = require("axios");

async function placeTrade(token, tradeData) {
  try {
    const response = await axios.post(
      "{{BASE_URL}}/trade",
      tradeData,
      {
        headers: {
          Authorization: `Bearer ${token}`,
          "Content-Type": "application/json",
        },
      },
    );
    return response.data;
  } catch (error) {
    console.error("Error placing trade:", error.response?.data);
    throw error;
  }
}

// Immediate BUY Order
const buyOrder = await placeTrade(token, {
  ticker: "AAPL",
  orderSide: "BUY",
  amount: 1000,
});
console.log("Buy Order Placed:", buyOrder);

// Immediate SELL Order
const sellOrder = await placeTrade(token, {
  ticker: "AAPL",
  orderSide: "SELL",
  quantity: 10,
});
console.log("Sell Order Placed:", sellOrder);

// Scheduled BUY Order
const scheduledBuy = await placeTrade(token, {
  ticker: "MSFT",
  orderSide: "BUY",
  amount: 2500,
  executeAt: "2025-01-15T09:30:00",
});
console.log("Scheduled Buy Order:", scheduledBuy);

Response

Immediate Trade Response (200 OK):

{
  "success": true,
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

Scheduled Trade Response (200 OK):

{
  "success": true,
  "requestId": "550e8400-e29b-41d4-a716-446655440001",
  "scheduled": true,
  "executeAt": "2025-01-15T09:30:00"
}

Response Fields:

Field	Type	Description
`success`	boolean	Whether the trade was successfully placed
`requestId`	string	Unique UUID identifier for the trade request
`scheduled`	boolean	Whether the trade is scheduled (only for scheduled trades)
`executeAt`	string	Scheduled execution time in ISO 8601 format (only for scheduled trades)

Get Trade Status

Endpoint: GET /trade/status

Description: Check the status of a previously placed trade

Query Parameters

Parameter	Type	Required	Description
`requestId`	string	Yes	The request ID from the trade placement response

cURL Example

curl -X GET "{{BASE_URL}}/trade/status?requestId=trade-uuid-789" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Node.js Example

async function getTradeStatus(token, requestId) {
  try {
    const response = await axios.get(
      "{{BASE_URL}}/trade/status",
      {
        params: { requestId },
        headers: {
          Authorization: `Bearer ${token}`,
        },
      },
    );
    return response.data;
  } catch (error) {
    console.error("Error getting trade status:", error.response?.data);
    throw error;
  }
}

const status = await getTradeStatus(token, "trade-uuid-789");
console.log("Trade Status:", status);

Response

Success Response (200 OK):

{
  "avgPrice": 150.25,
  "status": "SUCCESS"
}

Response Fields:

Field	Type	Description
`avgPrice`	number	Average execution price per share
`status`	string	Trade status (PENDING, SUCCESS, FAILED, PARTIAL)

Trade Status Values

Status	Description
`PENDING`	Trade is waiting to be executed
`SCHEDULED`	Trade is scheduled for future execution
`EXECUTING`	Trade is currently being executed
`SUCCESS`	Trade executed successfully
`PARTIAL`	Trade partially executed
`FAILED`	Trade failed to execute
`CANCELLED`	Trade was cancelled

Order Restrictions

Minimum Order: $100 for BUY orders
Maximum Order: $1,000,000 per order
Scheduled Trades: One per ticker per partner
Market Hours: 9:30 AM - 4:00 PM ET (Monday-Friday)
Supported Symbols: US stocks only

Common Errors

Partner ID Not Found

{
  "message": "Partner ID not found in request context"
}

Solution: Ensure your JWT token is valid and contains partner authentication.

Missing Ticker

{
  "message": "Ticker is required"
}

Solution: Provide a valid ticker symbol in the request.

Invalid Order Side

{
  "message": "Valid orderSide (BUY/SELL) is required"
}

Solution: Use either BUY or SELL for the orderSide parameter.

Missing Amount for BUY Order

{
  "message": "BUY orders require amount"
}

Solution: Provide the amount field (in USD) for BUY orders.

Missing Quantity for SELL Order

{
  "message": "SELL orders require quantity"
}

Solution: Provide the quantity field (number of shares) for SELL orders.

Invalid Execute Time Format

{
  "message": "Invalid executeAt format"
}

Solution: Use ISO 8601 format in Eastern Time: 2025-01-15T09:30:00

Execute Time in Past

{
  "message": "executeAt must be in the future"
}

Solution: Provide a future date/time for scheduled trades.

User Broker Account Not Found

{
  "message": "User broker account not found"
}

Solution: Ensure the user has completed broker profile setup in the PiTrade app.

Ticker Not Found

{
  "message": "Ticker AAPL not found"
}

Solution: Verify the ticker symbol is correct and available for trading.

Ticker Doesn't Support Fractional Investing

{
  "message": "Ticker AAPL doesn't support fractional investing"
}

Solution: Use a ticker that supports fractional shares, or contact support for alternatives.

Ticker Doesn't Support Trading

{
  "message": "Ticker AAPL doesn't support trading"
}

Solution: Verify the ticker is tradeable. Some tickers may have trading restrictions.

Scheduled Trade Already Exists

{
  "message": "A scheduled trade for ticker AAPL already exists"
}

Solution: Cancel the existing scheduled trade before creating a new one for the same ticker and order side.

Trade Execution Failed

{
  "message": "Trade failed: Insufficient funds in account"
}

Solution: Ensure sufficient funds are available. Deposit more funds if needed.

Best Practices

Validate Tickers - Check ticker symbols before placing orders
Check Funds - Verify sufficient balance before BUY orders
Handle Partial Fills - Be prepared for partial order execution
Monitor Status - Regularly check trade status for scheduled orders
Error Handling - Implement proper error handling and retry logic
Time Zones - Always use Eastern Time for scheduled trades

Next Steps

Portfolio Access - Check holdings and balance
Fund Deposits - Add funds to account
Account Management - Manage accounts