Connect Alpaca to Nyria

By the end you will have an Alpaca account (paper or live) connected to Nyria via API key, a bot wired to a strategy, and a verified test order — stock or up to a four-leg options structure.

Prerequisites

• A Nyria account with onboarding completed. New here? Start at the Quick Start.
• An Alpaca account. Sign up free at alpaca.markets — paper accounts come pre-provisioned with $100,000 of simulated cash.
• A Nyria strategy you can attach a bot to. The Strategies guide walks through creating one.
• For options testing: your Alpaca paper account must have options trading enabled at the level you intend to use (Alpaca paper supports up to Options Level 3, which covers the four-leg structures below). Toggle this in Alpaca's account settings before connecting.

Step 1: Open the broker connection modal

Step 2: Generate an API key in Alpaca

Step 3: Paste the key into Nyria

Step 4: Confirm the connection in Nyria

After the key validates, the Connection successful modal opens.

If you don't see the expected account, click Refresh accounts on the integration row. Nyria re-queries Alpaca's /v2/account endpoint and updates the list.

Step 5: Create a bot on the connection

A connection alone does not trade. You need a bot — the link between a strategy and an account.

Step 6: Fire a stock test order

The fastest end-to-end check is a market order on a liquid US equity. Replace <tokenHash> with your strategy's webhook token (Integration tab → Copy Webhook URL).

curl -X POST https://trades.nyria.io/webhooks/<tokenHash> \
  -H "Content-Type: application/json" \
  -d '{
    "ticker": "SPY",
    "action": "buy",
    "sentiment": "long",
    "quantity": 1,
    "order_type": "market"
  }'

Expected response:

{
  "ok": true,
  "bot_log_id": "bl_01J8Z...",
  "skipped": false
}

If both sides clear, your stock wiring is good.

Step 7: Fire a multi-leg options test order

Nyria's Alpaca integration accepts up to four legs per options order. Use this to test verticals, iron condors, butterflies, and similar structures. The payload below opens a SPY iron condor — short call spread plus short put spread — using Nyria's delta-target syntax so you don't have to hand-pick strikes.

curl -X POST https://trades.nyria.io/webhooks/<tokenHash> \
  -H "Content-Type: application/json" \
  -d '{
    "ticker": "SPY",
    "action": "open",
    "direction": "short",
    "order_type": "limit",
    "legs": [
      { "side": "CALL", "action": "sell_to_open", "delta_target": 0.20, "dte_min": 30, "dte_max": 45, "quantity": 1 },
      { "side": "CALL", "action": "buy_to_open",  "delta_target": 0.10, "dte_min": 30, "dte_max": 45, "quantity": 1 },
      { "side": "PUT",  "action": "sell_to_open", "delta_target": 0.20, "dte_min": 30, "dte_max": 45, "quantity": 1 },
      { "side": "PUT",  "action": "buy_to_open",  "delta_target": 0.10, "dte_min": 30, "dte_max": 45, "quantity": 1 }
    ]
  }'

What each field means once Nyria resolves it:

For a single-leg options test (lower margin requirement on the paper account, faster to verify), use the simpler payload from the Webhook reference:

{
  "ticker": "SPY",
  "action": "open",
  "direction": "long",
  "legs": [{ "side": "PUT", "action": "buy_to_open", "delta_target": 0.30, "dte_min": 7, "dte_max": 21, "quantity": 1 }],
  "order_type": "market"
}

Step 8: Unpause the bot

When both stock and options test orders cleared end-to-end:

Troubleshooting

Connect fails with invalid credentials

The key/secret pair didn't validate against Alpaca. The most common causes: the secret was copied with a trailing space, the key was regenerated in Alpaca after you copied it (regenerating invalidates the old pair), or the Alpaca account has not finished provisioning (brand-new sign-up where Alpaca is still creating the PA* account — wait a few minutes and retry).

Connection shows Connected but the buying power reads $0.00

This usually means the key belongs to the other environment than the account type you picked (e.g. a live key connected as Paper). Disconnect the integration, confirm which environment the Alpaca dashboard was in when you generated the key, and reconnect with the matching account type.

Stock test order returns 422 unprocessable_entity

Open the bot log entry for the call. The error_detail field will explain the rejection. Common Alpaca paper rejections:

• symbol not tradable — the ticker is not in Alpaca's paper universe (some OTC tickers are missing). Try a major large-cap to confirm the wiring.
• insufficient buying power — your paper account has been used for prior tests and has open positions tying up cash. Close them in the Alpaca dashboard.
• pdt restriction — the account has been flagged Pattern Day Trader and is under $25k. Reset the paper account from the Alpaca dashboard.

Options test order returns 403 options_level_required

Your Alpaca paper account does not have the options level required for the structure. Two- and four-leg defined-risk spreads require Level 3 on Alpaca paper. Enable it from Alpaca's Account → Options settings and retry. Note that the level may take a minute to propagate.

Four-leg order partially fills

This should not happen on Alpaca — multi-leg orders fill atomically or not at all. If you see partial fills on the Nyria log but the Alpaca dashboard shows all four legs filled, refresh the Nyria log; the per-leg status may have lagged the broker-side fill by a few seconds while the order-status sync task caught up.

Key stopped working after a while

Alpaca API keys don't expire on a schedule, but they are invalidated if you regenerate keys in the Alpaca dashboard or reset the paper account. If a bot starts failing with 401 unauthorized, generate a fresh key pair and reconnect from the Integrations page — your bot config and history are preserved across reconnect.

Going from paper to a real signal source

Once the cURL probes pass, replace the manual tests with your real alert source. The webhook URL does not change — it is per-strategy, not per-broker:

• TradingView setup
• Discord alerts
• Telegram alerts — coming soon
• Custom webhook — for any source that can POST JSON

What's next

• Alpaca integration overview — supported equity types, position sizing, and margin rules.
• Webhook payload reference — every field Nyria recognizes, including all legs[] shapes.
• Equity types — how Nyria models stocks, options, and crypto across brokers.
• Trading behavior — entry, exit, and pyramiding semantics.
• Troubleshooting — error codes mapped to fixes if the webhook returns non-2xx.