You're on your way to building an awesome developer hub! Here's some of the things you'll want to check out.

Step 1 — Create your Tradecraft account and connect Alpaca

Sign up at usetradecraft.io. Once logged in, you will be prompted to connect your Alpaca account.

You will need:

• An Alpaca Markets account (free to create)
• Your Alpaca API Key and Secret Key from the Alpaca dashboard under Your Account → API Keys
• Choose Paper Trading to start — no real money involved

Enter your Alpaca credentials in the Tradecraft dashboard. They are encrypted and stored securely. Tradecraft uses them to execute trades on your behalf.

Paper vs Live: Always start with paper trading. Paper trading uses simulated money so you can test your strategies safely before going live.

Step 2 — Generate an API key

In the Tradecraft dashboard, go to Settings → API Keys and click Generate Key. Give it a label (e.g. my trading bot ).

Your key will be shown once. Copy it and store it somewhere safe — a password manager or environment variable.

Keys are never stored in plaintext. If you lose yours, revoke it in the dashboard and generate a new one.

Step 3 — Create an agent

An agent is a named, funded sub-account that executes a trading strategy. Create one by calling POST /v1/agents with a name and a cash allocation.

The cash_allocation is drawn from your connected Alpaca account balance. It cannot exceed your available (unallocated) balance.

Request:

curl -X POST https://api.usetradecraft.io/v1/agents \
  -H "Authorization: Bearer $TRADECRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-agent",
    "cash_allocation": 1000
  }'

Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "my-first-agent",
  "status": "active",
  "allocated_cash": 1000.0,
  "reserved_cash": 0.0,
  "created_at": "2025-04-19T14:22:00Z"
}

Agent names must be lowercase with no spaces. Use hyphens as separators (e.g. momentum-trader, mean-reversion-v2). The name is used as the identifier in all subsequent API calls.

Step 4 — Submit your first trade

With your agent created, you are ready to execute a trade. Call POST /v1/agents/name/orders with the symbol, side, and quantity.

Before the order reaches Alpaca, Tradecraft’s fund checker validates:

• The agent is active
• It has enough available cash for a buy
• It holds the shares being sold

If any check fails, you get a 422 with a clear error — the order is rejected before touching Alpaca.

Request:

curl -X POST https://api.usetradecraft.io/v1/agents/my-first-agent/orders \
  -H "Authorization: Bearer $TRADECRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "AAPL",
    "side": "buy",
    "qty": 1,
    "order_type": "market",
    "reasoning": "Initial position in AAPL"
  }'

Response:

{
  "order_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "alpaca_order_id": "7e8f9a0b-c1d2-3456-efab-7890cdef1234",
  "symbol": "AAPL",
  "side": "buy",
  "qty": 1.0,
  "estimated_cost": 191.20
}

That’s it. Your agent just executed a trade. 🎉

What’s Next?

Now that you have the basics working, here is what to explore next:

See your agent’s positions, P&L, and available cash:

curl https://api.usetradecraft.io/v1/agents/my-first-agent/portfolio \
  -H "Authorization: Bearer $TRADECRAFT_API_KEY

Deploy a hosted agent:

Want the agent to trade on its own without having your agents submitting orders manually? Deploy it as a hosted agent with a strategy prompt and a cron schedule. Tradecraft runs it autonomously — see POST /v1/agents/name/deploy.

Run multiple strategies:

Create additional agents with different names and allocations. Each agent manages its own book independently.

Review trade history:

curl https://api.usetradecraft.io/v1/agents/my-first-agent/orders \
  -H "Authorization: Bearer $TRADECRAFT_API_KEY"

Two Ways to Use Tradecraft

You can mix both modes. Use API-driven for strategies you’ve already coded, and hosted agents for autonomous strategies you want to describe in plain English.

We're excited you're here! 💙