Worlds / Banking and brokerage

Alpaca API

A local Alpaca brokerage with accounts, orders, positions, fills and a market clock. Test the trading agent that rebalances portfolios and respects buying power and market hours.

Base path: /v2
Auth: APCA-API-KEY-ID and APCA-API-SECRET-KEY headers, the world key
Endpoints: 14
Status: Active today

This reference previews the surface the Alpaca world serves in the closed beta. Paths mirror the public Alpaca API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_ALPACA_URL`	This world's origin followed by `/v2`
`WORLDS_API_KEY`	The world key, accepted wherever Alpaca expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · @alpacahq/alpaca-trade-api

import Alpaca from "@alpacahq/alpaca-trade-api";

const alpaca = new Alpaca({
  keyId: "key",
  secretKey: process.env.WORLDS_API_KEY,
  baseUrl: process.env.WORLDS_ALPACA_URL,
  paper: true,
});

const order = await alpaca.createOrder({
  symbol: "AAPL", qty: 1, side: "buy", type: "market", time_in_force: "day",
});

API reference

14 of 14

Account

Buying power and account status.

GET/v2/accountGet the account
GET/v2/account/activitiesList account activities
GET/v2/account/portfolio/historyGet portfolio history

Fields · 5

`id`	string	Account id
`status`	string	ACTIVE or restricted
`buying_power`	string	Available buying power
`cash`	string	Cash balance
`equity`	string	Total equity

Orders

Buy and sell orders.

POST/v2/ordersPlace an order
GET/v2/ordersList orders
GET/v2/orders/{order_id}Get an order
DELETE/v2/orders/{order_id}Cancel an order
DELETE/v2/ordersCancel all open orders

Fields · 6

`id`	string	Order id
`symbol`	string	Ticker
`qty`	string	Quantity
`side`	string	buy or sell
`type`	string	market, limit, stop
`status`	string	new, filled, canceled and more

Positions

Current holdings.

GET/v2/positionsList positions
GET/v2/positions/{symbol}Get a position
DELETE/v2/positions/{symbol}Close a position

Fields · 5

`symbol`	string	Ticker
`qty`	string	Shares held
`avg_entry_price`	string	Average cost
`market_value`	string	Market value
`unrealized_pl`	string	Unrealized profit or loss

Assets

Tradable instruments.

GET/v2/assetsList assets
GET/v2/assets/{symbol_or_asset_id}Get an asset
GET/v2/calendarGet the market calendar

Fields · 4

`id`	string	Asset id
`symbol`	string	Ticker
`tradable`	boolean	Can be traded
`fractionable`	boolean	Supports fractional shares

Test workflow

Prepare. Select the Alpaca setup for your workflow and review its starting records, including account, orders, positions.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

No sell order exceeds the position quantity
Total buys within buying_power
Stale BND limit order canceled before new orders
Final weights within 2% of target
TSLA stop order untouched

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Alpaca
version: 2
connector: alpaca
seed: alpaca-starter
mode: isolated
policy: >
  Rebalance account PA-221 to 60% VTI and 40% BND using available cash only.
  Do not short anything. Cancel stale limit orders first.
tasks:
  - id: place-orders-to-rebalance-to-target-weights
    prompt: Place orders to rebalance to target weights
  - id: cancel-or-replace-open-orders
    prompt: Cancel or replace open orders
  - id: close-a-position-without-overselling
    prompt: Close a position without overselling
expected:
  - No sell order exceeds the position quantity
  - Total buys within buying_power
  - Stale BND limit order canceled before new orders
  - "Final weights within 2% of target"
  - TSLA stop order untouched
scenarios:
  - insufficient-buying-power
  - market-closed
  - partial-fill

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`insufficient-buying-power`	Order is rejected with 403 insufficient buying power
`market-closed`	Market orders queue until the next session
`partial-fill`	A limit order sits partially_filled at the close
`rate-limited`	API returns 429 past the per-minute limit

Starting data

Start each run from the same records and relationships. The overview below describes the Alpaca starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
accounts	Paper accounts with cash and margin settings
positions	12 holdings across equities and ETFs
orders	40 filled, 5 open, 3 canceled
market clock	Regular session, pre-market and closed states

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Account records

Account

Buying power and account status.

Field	Type	Meaning / relationship
`id`	string	Account id
`status`	string	ACTIVE or restricted
`buying_power`	string	Available buying power
`cash`	string	Cash balance
`equity`	string	Total equity

json · illustrative record shape

{
  "id": "<Account id>",
  "status": "<ACTIVE or restricted>",
  "buying_power": "<Available buying power>",
  "cash": "<Cash balance>",
  "equity": "<Total equity>"
}

See account operations

Orders records

Orders

Buy and sell orders.

Field	Type	Meaning / relationship
`id`	string	Order id
`symbol`	string	Ticker
`qty`	string	Quantity
`side`	string	buy or sell
`type`	string	market, limit, stop
`status`	string	new, filled, canceled and more

json · illustrative record shape

{
  "id": "<Order id>",
  "symbol": "<Ticker>",
  "qty": "<Quantity>",
  "side": "<buy or sell>",
  "type": "<market, limit, stop>",
  "status": "<new, filled, canceled and more>"
}

See orders operations

Positions records

Positions

Current holdings.

Field	Type	Meaning / relationship
`symbol`	string	Ticker
`qty`	string	Shares held
`avg_entry_price`	string	Average cost
`market_value`	string	Market value
`unrealized_pl`	string	Unrealized profit or loss

json · illustrative record shape

{
  "symbol": "<Ticker>",
  "qty": "<Shares held>",
  "avg_entry_price": "<Average cost>",
  "market_value": "<Market value>",
  "unrealized_pl": "<Unrealized profit or loss>"
}

See positions operations

Assets records

Assets

Tradable instruments.

Field	Type	Meaning / relationship
`id`	string	Asset id
`symbol`	string	Ticker
`tradable`	boolean	Can be traded
`fractionable`	boolean	Supports fractional shares

json · illustrative record shape

{
  "id": "<Asset id>",
  "symbol": "<Ticker>",
  "tradable": false,
  "fractionable": false
}

See assets operations

See the Alpaca world in the catalog