X1E Trading Hub Piece

A wrapper API piece for communicating with the Skillful AI Training Hub Python project through ActivePieces.

Overview

This piece provides a bridge between ActivePieces and your Python Training Hub API, enabling you to:

• Start and monitor training jobs
• Execute trading operations asynchronously
• Generate and manage trading signals
• Access account information and positions
• Place orders and manage portfolios

Environment Variables

The following environment variables must be configured in your ActivePieces environment:

AP_SKAI_TRAINING_HUB_URL=http://0.0.0.0:8001

Authentication

This piece uses system-level configuration for authentication with the Training Hub API. User context is automatically handled through ActivePieces sessions. No additional authentication configuration is required for individual users.

Available Actions

Training Operations

• Start Training: Initiate a training job for a trading agent
• Get Training Status: Check the status of a training job

Trading Operations

• Start Trade: Execute trading operations asynchronously
• Get Trade Status: Monitor trading job progress
• Place Order: Place individual buy/sell orders

Signal Operations

• Start Signals Generation: Generate trading signals
• Get Signals Status: Monitor signals generation progress
• Get Trading Signals: Retrieve cached trading signals
• Remove Trading Signal: Delete specific signals

Account Management

• Get Account Snapshot: Retrieve account equity, cash, and positions
• Get Positions: Get current open positions
• Get Orders: Retrieve order history
• Get Equity History: Get historical equity curve data

Portfolio Management

• Rebalance Portfolio: Trim positions above concentration limits

Usage

1. Configure the environment variables in your ActivePieces installation
2. Import this piece into your flow
3. Use the actions with appropriate user_id, agent_id, and connection_id parameters

API Endpoints Mapped

This piece maps to the following Python API endpoints:

• POST /trading/train → Start Training
• GET /trading/train/{job_id}/status → Get Training Status
• POST /trading/trade/async → Start Trade
• GET /trading/trade/{job_id}/status → Get Trade Status
• POST /trading/signals → Start Signals Generation
• GET /trading/signals/{job_id}/status → Get Signals Status
• GET /trading/trade/signals → Get Trading Signals
• DELETE /trading/trade/signals/{signal_id} → Remove Trading Signal
• GET /trading/account/snapshot → Get Account Snapshot
• GET /trading/account/positions → Get Positions
• GET /trading/account/orders → Get Orders
• GET /trading/account/equity → Get Equity History
• POST /trading/trade/order → Place Order
• POST /trading/rebalance → Rebalance Portfolio

Development

To build this piece:

npx nx build pieces-x1e

To publish to npm:

cd dist/packages/pieces/custom/x1e
npm publish --access public

Migration from Previous Version

This version replaces the previous broker-specific implementation with a unified Training Hub API wrapper. The new implementation:

• Connects directly to your Python Training Hub API
• Uses system-level environment configuration
• Supports all the endpoints from your Python API
• Maintains the same piece name (x1e) for compatibility
• Requires user_id, agent_id, and connection_id parameters for most actions

Configuration

Make sure your Python Training Hub API is running and accessible at the configured URL. The API should accept Bearer token authentication using the configured API key.

Action Parameters

Most actions require these common parameters:

• user_id: User identifier from the system
• agent_id: Trading agent identifier
• connection_id: ActivePieces connection ID for broker credentials

Additional parameters vary by action (quantity, ticker, order type, etc.).

Error Handling

The piece includes comprehensive error handling:

• API connectivity issues are reported clearly
• Invalid parameters are validated
• HTTP errors from the Training Hub are captured and formatted
• Timeouts and network issues are handled gracefully

Security

• All API calls use Bearer token authentication
• Credentials are managed through environment variables
• User context is validated through the ActivePieces system
• No sensitive data is logged or exposed in responses