alpaca-python-trading-coder

name: alpaca-python-trading-coder description: Comprehensive Python programming skill for Alpaca Trading API (alpaca-py SDK + REST OpenAPI). Use when Codex needs to write, review, or refactor Python trading integration code for Alpaca accounts, orders, positions, portfolio history, watchlists, assets, options, corporate actions, account activities, market clock/calendar, crypto funding, or perpetual funding endpoints. Includes typed input parameters, per-API Python examples, output structure types, and SDK-to-REST mapping. This skill is for code authoring and analysis, not autonomous trade execution.

Alpaca Python Trading Coder

Objective

Generate high-quality Python code for Alpaca Trading API integrations with explicit typing for:

• input parameters
• request payload objects
• output response structures

Treat this skill as a programming reference. Do not treat it as permission to execute live trades.

Core Workflow

1. Identify whether the task should use alpaca-py high-level SDK calls or direct REST calls.
2. Resolve typed inputs from request models and enums before writing business logic.
3. Add one concrete Python example per API used in the target code.
4. Validate output parsing against documented response model fields/types.
5. Default examples to paper trading unless the user explicitly requests live environment code.

Reference Navigation

Read files on demand in this order:

1. references/00-sources-and-scope.md Use to confirm source versions and coverage.

2. references/01-python-sdk-tradingclient.md Use for TradingClient and TradingStream method signatures, parameter types, and examples.

3. references/02-python-sdk-request-models.md Use for request object field-level typing and constructor shapes.

4. references/03-python-sdk-response-models.md Use for response object field-level typing and output structure expectations.

5. references/04-python-sdk-enums.md Use when a parameter type is an enum and allowed values must be explicit.

6. references/05-rest-trading-api-reference.md Use for complete endpoint-level REST coverage (including APIs not yet wrapped by high-level SDK methods).

7. references/06-sdk-rest-mapping.md Use to map SDK methods to REST paths and identify gaps requiring raw REST calls.

8. references/openapi/trading-api.json Use as full raw OpenAPI snapshot when deep schema details are needed.

Implementation Rules

• Prefer TradingClient high-level methods first.
• Fall back to TradingClient.get/post/put/patch/delete or requests for unmapped endpoints.
• Keep code strongly typed with explicit request model and enum usage.
• Reflect response typing in return annotations and parsing code.
• Include defensive handling for empty responses, HTTP errors, and optional fields.

Regeneration

When references become stale, regenerate from latest OpenAPI + installed SDK:

python3 scripts/build_references.py

This refreshes all files in references/ and the OpenAPI snapshot.