Connect Alpaca to Nyria

Alpaca connects with an API key you generate in the Alpaca dashboard. Paste the key ID and secret into the Alpaca card's dialog on Integrations. A paper key only works on paper and a live key only on live. Alpaca shows the secret once, so copy it straight away.

Prerequisites

• A Nyria account with onboarding finished. If you are new, start at the quick start.
• An Alpaca account. You can open one at alpaca.markets. Paper accounts start with $100,000 of simulated cash.
• A Nyria strategy to deploy a bot on. Strategies shows how to create one.
• For the options tests, options trading turned on in your Alpaca paper account. Alpaca paper goes up to Options Level 3, which covers the four-leg structures below. Set the level in Alpaca's account settings before you connect.

Step 1: Open the Alpaca dialog

Step 2: Generate an API key in Alpaca

Step 3: Paste the key into Nyria

Step 4: Confirm the connection in Nyria

Nyria shows Alpaca paper account connected (or Alpaca live account connected), and the account appears in the Alpaca dialog with a Connected badge. Make sure the account number matches the one in your Alpaca dashboard. Paper account numbers start with PA.

Step 5: Create a bot on the connection

A connected account does nothing until a bot uses it. The bot links a strategy to the account.

Step 6: Send a stock test order

Start with a market order on a liquid US stock. Replace <tokenHash> with your strategy's webhook token: on the strategy's Integration tab, find Webhook URL and select Copy URL.

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

Expected response:

{
  "status": "processed",
  "webhook": true,
  "originalAlert": "...",
  "structuredAlert": { "instrument": "SPY", "action": "OPEN", "direction": "LONG" }
}

If the open and the close both reach Alpaca, stock trading works.

Step 7: Send a multi-leg options test order

Nyria sends up to 4 legs per options order to Alpaca, so you can test a vertical spread, an iron condor or an iron butterfly here.

The legs don't go in the alert. You set them once on the strategy, in the What it trades step, and every alert opens that structure:

curl -X POST https://trades.nyria.io/webhooks/<tokenHash> \
  -H "Content-Type: application/json" \
  -d '{
    "ticker": "SPY",
    "action": "OPEN",
    "direction": "SHORT",
    "order_type": "limit",
    "price": 2.00
  }'

What each field does:

The alert carries no delta targets, expiry window or contract count. Those come from the strategy and the bot.

A single-leg test needs less margin on the paper account and is quicker to check. For one, use the shorter payload from the webhook reference:

{
  "ticker": "SPY",
  "action": "OPEN",
  "direction": "LONG",
  "order_type": "market"
}

Troubleshooting

"Alpaca didn't accept these keys"

The dialog shows this under Account number when Alpaca refuses the key and secret. The usual causes:

• A trailing space copied with the secret
• A key regenerated in Alpaca after you copied it, which voids the old pair
• A key from the other environment, such as a live key under Connect paper account. Check whether the Alpaca dashboard was on Paper or Live when you generated it

If it says Alpaca didn't return an account for these keys, Alpaca may still be creating the PA* account for a new signup. Wait a few minutes and try again.

Stock test order returns 422 unprocessable_entity

Open the bot log entry for the call and read the error_detail field. Common Alpaca paper rejections:

• symbol not tradable: Alpaca paper does not list the ticker (some OTC tickers are missing). Try a large-cap stock to check the setup.
• insufficient buying power: open positions from earlier tests are tying up cash. Close them in the Alpaca dashboard.
• pdt restriction: the account has been flagged Pattern Day Trader and is under $25,000. Reset the paper account from the Alpaca dashboard.

Options test order returns 403 options_level_required

Two- and four-leg defined-risk spreads need options Level 3, and your Alpaca paper account is below it. Raise it in Alpaca's Account → Options settings and try again. The new level can take a minute to apply.

Four-leg order partially fills

Alpaca fills a multi-leg order as a whole or not at all. If the Nyria log shows a partial fill and the Alpaca dashboard shows all four legs filled, refresh the Nyria log. Per-leg status can lag the broker by a few seconds while Nyria syncs.

Key stopped working after a while

Alpaca API keys don't expire on a schedule, but regenerating them in the Alpaca dashboard or resetting the paper account voids them. If a bot starts failing with 401 unauthorized, generate a new key pair and reconnect from the Integrations page. Your bot settings and history are kept.

Going from paper to a real alert source

When the curl tests pass, point your real alert source at the same webhook URL. The URL belongs to the strategy, not the broker, so it doesn't change:

• TradingView setup
• Discord alerts
• Custom webhook: for any source that can POST JSON

Next steps

• Alpaca: what it trades, and its limitations.
• Webhook reference: every field Nyria reads, including all legs[] shapes.
• What you can trade: how Nyria models stocks, options and crypto across brokers.
• Trading behavior: entries, exits and multiple entries.
• Troubleshooting: fixes by log message.