Common mistakes with scoped API keys for trading agents

Developers often treat scoped API keys as a complete security boundary for trading agents, but the keys themselves only enforce the limits that humans configure. A misscoped key can expose an account to larger losses than intended, while an overly restrictive key can cause silent failures that leave positions unhedged. The most common mistakes are not bugs in the API, but gaps between the intended safety model and the actual permissions attached to the credential. Understanding these gaps is essential before sending an agent live with real money.

What does a scoped API key actually control?

A scoped API key for an agentic trading system is a credential that carries both authentication and authorization constraints. On Felix, one key can reach stocks, crypto, perpetual futures, options, and prediction markets, but the scope determines which of those markets the agent may touch, how much notional value it can place at risk, and whether it can open positions, reduce them, or both. The owner retains custody because the key cannot add withdrawal addresses or move funds to an external wallet; it can only spend within the approved budget against the markets that are explicitly enabled. This means the scope is the contract between the owner and the agent, and any ambiguity in that contract becomes a vulnerability.

Many developers assume that scoping is primarily about read versus write access. In practice, the dangerous mistakes happen inside the write permissions. A key scoped to allow market orders on perpetual futures but not limit orders removes price control, while a key scoped to allow both entry and exit on all five asset classes when the strategy only trades one asset class creates unnecessary exposure. The scope should match the strategy's known surface area, not the platform's entire surface area. If the strategy trades prediction markets only, the key should say so explicitly. If it never uses options, the key should not include them. Each additional market in the scope is a potential path for error.

When you are building your first system, it is worth reviewing the full checklist in building your first agentic trading system before finalizing the key. The exact request schema is in the docs; the shape looks like this:

{
  "key_name": "agent-strategy-alpha",
  "markets": ["perps", "prediction"],
  "max_position_usd": 5000,
  "daily_spend_cap_usd": 1000,
  "allow_withdrawal": false,
  "allowed_order_types": ["limit", "market"],
  "panic_endpoint": "owner-verified"
}

This example is illustrative. The actual fields and nesting may differ, but the principle is that each parameter narrows the agent's operating envelope. If you omit a field because you are unsure what it does, you may accidentally leave the default, which is often the broadest setting. That is the first mistake.

Why do broad permissions defeat the purpose of scoping?

The entire point of a scoped key is to reduce the blast radius of a bug or a compromised agent. When a developer creates a single key with access to all five market types simply because the platform supports them, the scope becomes a formality rather than a safeguard. If the agent is supposed to trade prediction markets only, a key that also permits options and perps means a logic error or a prompt injection could open positions where no strategy exists to manage them. The result is not just a bad trade, but an unmonitored trade in an unfamiliar market.

Broad permissions also complicate monitoring and incident response. A scoped key should make it easy to see when an agent steps outside its lane. When the lane is the entire road, anomaly detection becomes impossible. You lose the ability to distinguish between expected behavior and a runaway process. If something goes wrong, you must first determine which market was affected before you can assess the damage. A narrow scope tells you immediately that the error is contained to one area. This containment is valuable when you are operating under stress and need to decide whether to hit the kill switch or let the agent continue.

The correct approach is to create the narrowest viable scope for the specific strategy, then widen it only after proving that the additional market is necessary and that the agent's sizing logic handles it correctly. This principle connects directly to custody. A scoped key is one layer of the guardrail system that keeps funds under owner control. You can read more about the full model in how to set guardrails for a trading agent without giving up custody. The key is not the only safeguard, but it is the first one, and it should be treated as a precise instrument rather than a master password. If you treat it as a master password, you have already made the second mistake.

How can budget caps be set too high or too low?

Budget caps are numeric scopes, and numbers are easy to get wrong. A cap set too high is obvious: the agent can lose more money than the owner is prepared to lose. A cap set too low is subtler. When the agent hits a low daily cap, subsequent orders are rejected by the API. If the strategy assumes that an exit order will always clear, that rejection can leave a position open longer than intended. The agent may also enter a retry loop that wastes API calls or generates misleading logs. In a fast market, a rejected exit order is as dangerous as an unauthorized entry order.

The right cap is derived from the strategy's worst-case scenario, not from the total wallet balance. If a strategy is designed to risk one percent of capital per trade, the key's daily spend cap should reflect the number of trades the agent is expected to make in a day, plus a small buffer for slippage or partial fills. It should not reflect the full account size. Using the full balance as a cap is equivalent to using no cap, because a single bad day can still consume everything. The API normalizes orders in plain US dollars, which helps, but the human still has to choose the number.

Another numeric error is confusing the daily spend cap with the maximum position size. A spend cap controls flow, while a position limit controls stock. An agent can hit the spend cap on entry and then be unable to exit because the exit order would push the day's total over the cap. The scope must allow both the entry and the exit, or the cap must be set high enough to accommodate the full round trip. Treating these two numbers as interchangeable is a common oversight. Trading can lose money, including everything. A scoped key with a sensible cap does not eliminate risk; it only limits the speed at which losses can accumulate. Owners should review caps after each backtest and paper trading period, adjusting them as the strategy's behavior becomes clearer. Paper trading exists for exactly this calibration, and live trading should not begin until the cap has been validated against observed volatility. If the cap is chosen by copying a number from a tutorial without adapting it to your strategy, you have made the third mistake.

What happens when revocation is never tested?

A scoped key that cannot be revoked quickly is just a delayed disaster. Many developers generate a key, embed it in an agent or an MCP client, and then never test the revocation flow until an emergency. In an emergency, you do not want to discover that the agent has cached the key in memory, that the MCP server holds a persistent connection, or that the revocation endpoint requires a different credential than the one you have handy. These are implementation details that matter more than the scope itself.

Some developers also forget that revocation is not always instantaneous across every layer. If the MCP client maintains a connection pool, the old key may remain valid for a few seconds after dashboard revocation. Those seconds matter. The only way to discover this latency is to test it with a stopwatch and a test order. Document the lag, and if it is unacceptable, change the client configuration before going live.

Testing revocation means more than deleting the key from the dashboard. It means observing that in-flight orders are canceled, that open positions are flattened according to the exit plan, and that the agent receives a clear error rather than a silent fallback. The panic or kill switch should be part of the same test. You can learn about the underlying mechanics in how kill switches work from first principles for trading agents. The test should be run under the same conditions as live trading, including the same network paths and the same client software. Revocation tests should happen during paper trading, before any live authorization. If the agent is running through an MCP tool in Claude or Cursor, the test must include the entire chain: the editor, the MCP server, the API, and the downstream venues. A break in any link delays revocation, and delays are measured in dollars when markets move fast. If you have never pressed the panic button on purpose, you have made the fourth mistake.

Why do agents need exit plans and not just entry logic?

Scoped keys are often configured with entry in mind. The developer asks, 'Can the agent open a position?' and sets the key to allow it. They forget to ask, 'Can the agent close the position if the strategy halts?' An exit plan is a scope concern because the key must permit the orders that unwind risk, even when the primary strategy fails. Without explicit exit permissions, a stop-loss or take-profit order may be rejected, and the owner is left holding an unmanaged position.

If the key is time-bound and expires while a position is open, the agent may lose the ability to close it. The scope should explicitly include exit permissions, or the owner should maintain a separate, tightly scoped exit key that is tested and ready. This is not over-engineering; it is acknowledging that an agent's lifetime is unpredictable. A connection drop, a model error, or a venue outage can all interrupt the agent at the worst moment.

A complete scope also defines what happens when the connection drops. Does the venue support bracket orders that sit outside the agent's key? Does the API offer a time-in-force setting that matches the strategy's holding period? These questions are part of scoping. If the answer is no, the scope must be broad enough to allow the agent to manage the full lifecycle of every trade it enters. Exit permissions should also account for partial fills. If the agent is scoped to close a position but the API rejects partial closes because of a misconfigured minimum order size, the agent may leave a residual position that is too small to manage. The scope and the strategy must agree on what constitutes a complete exit. Testing this in paper trading reveals mismatches that are invisible in the scope dashboard. Otherwise, the owner is left with manual cleanup during a crisis, and manual cleanup is exactly what the agent was supposed to prevent. If your scope only covers entry, you have made the fifth mistake.

How should a kill switch fit into the key lifecycle?

The kill switch is the final scope transition: it changes the key's permissions from some access to no access, and it triggers a flattening of all positions. The mistake is treating the kill switch as a theoretical feature rather than a tested, documented step in the deployment checklist. A kill switch that is not exercised before live trading is a wish, not a tool. You should know the exact sequence of events that follows the press of the button, and you should verify that sequence in a safe environment.

On Felix, the kill switch is non-custodial by construction. It flattens and revokes, but it does not move funds to a new wallet because the key never had that power. This is a safety property, not a limitation. The owner should verify that the kill switch target addresses and position limits are correct at the moment the key is created, not hours later when the market is volatile. The design philosophy is explained in how a single API keeps AI trading agents safe by design. Understanding this philosophy helps you avoid the temptation to grant broader permissions just to make the switch easier.

Before taking an agent live, authorize the key explicitly, test the kill switch, and document the recovery path. After the test, rotate the key if the test exposed it in logs or chat history. Scoped keys are cheap to create and destroy; the cost of skipping these steps is the entire budget cap, and possibly more if the scope was misconfigured. If you treat the kill switch as a footer note rather than a core feature, you have made the sixth mistake.