A practical checklist for scoped API keys for beginner trading agents

A scoped API key is the first line of defense between a trading agent and real money. It restricts the agent to specific markets, actions, and spending limits so that even if the logic fails, the damage is bounded. For beginners, building this scope correctly before going live is more important than the strategy itself.

What does a scoped API key actually control?

A scoped API key is not merely a password. It is a policy object that enumerates exactly what the agent is allowed to do and how much it can spend. When you create the key, you define the universe of tradable instruments, the order types the agent may submit, the maximum position size expressed in plain US dollars, and the total budget that can be deployed across all venues. The Felix infrastructure enforces these limits at the API layer, which means the agent cannot talk its way around them through prompt engineering, context window confusion, or simple logic errors. The scope is evaluated on every request, so a bug that generates a thousand orders in a loop will hit the cap and stop.

• ·Tradable instruments and approved markets
• ·Permitted order types
• ·Maximum position size in US dollars
• ·Total budget cap
• ·Forbidden actions such as withdrawals or transfers

The scope should also explicitly define what the agent cannot do. For example, the key can be configured to forbid withdrawals, forbid transfers, and forbid trading outside the approved market list. This is the non-custodial property made concrete. The owner retains the wallet, and the agent receives only a tightly bound set of capabilities. If the agent is compromised or its instructions drift, the key still cannot exceed its original boundaries. This is important because agents are software, and software can behave in ways that are hard to predict. A scoped key is a hard ceiling that does not depend on the agent’s reasoning. To understand how this fits into a broader custody model, read how to set guardrails for a trading agent without giving up custody.

Which markets should a beginner agent access first?

Beginners should start with exactly one market type and one direction. A key that can trade stocks, crypto, perps, options, and prediction markets simultaneously is difficult to reason about and dangerous to debug. The mental model for position sizing, margin, and settlement differs across each asset class. Pick a single market, and scope the key to that class alone. If the strategy is directional, consider scoping the key to buy orders only, or to long positions only, until the behavior is verified over multiple sessions. This reduces the number of variables that can go wrong. You are not trying to maximize returns at this stage. You are trying to verify that the agent does exactly what you expect, when you expect it, with no side effects. Once the agent is reliable in one market, you can clone the scope and expand it carefully.

Paper trading is the right place to test multi-market logic. A scoped paper-trading key uses the same permission model as a live key but settles against virtual balances. Only after the agent behaves predictably in paper should you authorize a live key with the identical scope. This keeps the blast radius small while you are still learning how the agent interprets instructions, handles errors, and responds to price changes. Do not treat paper trading as a performance test. Performance in paper does not guarantee performance live. Treat it instead as a scope verification test. You are checking that the agent stays inside its boundaries, that the API rejects out-of-scope actions, and that the audit log captures every decision. Only when those three conditions are met should you consider live authorization.

How do you set a budget cap that limits real loss?

Budget caps are the most important numeric field in a scoped key. They should be set to an amount you are genuinely willing to lose in full, because trading can lose money, including everything. The cap is enforced in US dollars across all positions tied to the key, so the agent cannot hide exposure by splitting orders across instruments or venues. The API normalizes venue-specific contract math into plain dollar amounts, which means the cap is easy to reason about even when the underlying market uses leverage, notional sizing, or tick values. This normalization is critical for beginners, who should not have to learn the contract specifications of every venue before they can protect their capital. The dollar cap is a universal language. Suppose you set the cap to five hundred dollars. The agent can then only place orders that sum to five hundred dollars of exposure, regardless of whether it is trading a stock or a perps contract.

A useful pattern is to set three nested caps: a daily cap, a weekly cap, and a total cap. The daily cap catches runaway behavior early. The weekly cap prevents a slow bleed across multiple sessions. The total cap is the maximum capital ever at risk under this key. These three layers mean that a single bug, a bad signal, or an unexpected market event cannot escalate beyond the pre-approved boundary. When the agent hits any cap, the API returns a rejection and the agent must stop. The rejection is logged, which gives you a clear signal that the scope is active. Some beginners set only a total cap and then watch the account drain over days. A daily cap forces a pause that lets you review the strategy before continuing. Think of the caps as circuit breakers for capital, not just suggestions. For a deeper walkthrough on hard limits, see how trading APIs keep AI agents safe in 2026.

What is a kill switch and why does it belong in the key setup?

A kill switch is a revocation mechanism that flattens positions and disables the key. It belongs in the setup phase, not as an afterthought. When you scope the key, you should also define the conditions under which the switch is triggered. These can be manual, such as a button you press, or automated, such as a drawdown threshold that revokes the key when breached. The switch should be independent of the agent’s runtime. If the agent crashes, the switch still works. If the agent ignores instructions, the switch still works. This independence is what makes it a safety control rather than a feature of the agent. The kill switch operates at the key level, which means it is enforced by the infrastructure, not by the agent’s own code. You should document the switch location and test it before the first live trade.

Beginners often assume they will have time to react to a malfunction. In practice, agents can place orders faster than a human can read them. The kill switch must be wired to the key at creation so that revocation is instantaneous and does not depend on the agent’s cooperation. You should test the switch during the paper-trading phase. Trigger it deliberately and confirm that new orders are rejected and that existing positions are flattened according to your exit plan. If the exit plan is not defined, the switch may flatten at market prices, which can itself cause loss. That is still preferable to an unbounded runaway agent. The test should be boring and repetitive, because in a real emergency you will not have time to think. You can read about common mistakes in what beginners get wrong about kill switches for trading agents.

How do you test a scoped key before going live?

Testing should happen in two stages: unit testing of the scope itself, and integration testing of the agent against the scope. First, verify that the key rejects forbidden actions. Submit a withdrawal request and confirm it fails. Submit an order for an unapproved market and confirm it fails. Submit an order that exceeds the dollar cap and confirm it fails. These negative tests prove the policy is active and that the API layer is the enforcement point, not the agent’s good behavior. Negative tests are more important than positive tests at this stage. A positive test only shows that the API works when conditions are perfect. A negative test shows that the API protects you when conditions are wrong. Run these tests against both the paper and live keys, because the permission model should be identical even though the settlement differs.

Second, run the agent in paper trading with the exact scope you intend to use live. Observe whether the agent respects the position limits and whether the budget cap increments as expected. Watch for drift: if the agent tries to access a market that is not in the scope, the rejection log should show it. The exact request schema is in the docs; the shape looks like this:

{
  "key_name": "beginner-agent-scope",
  "budget_usd": 500,
  "allowed_markets": ["stocks"],
  "allow_withdrawal": false,
  "panic_drawdown_pct": 10
}

After the paper tests pass, clone the scope to a live key and repeat the negative tests with the smallest possible live order. Confirm that the live key behaves identically to the paper key. Only then increase the budget to the intended level. Do not skip this step. Paper and live environments can differ in latency and error handling, and you want to discover those differences with the smallest possible amount at risk, rather than the full budget.

What should you review in the audit logs after the first trades?

After the agent places its first orders, the audit log is your source of truth. Review every order that was rejected due to scope limits. Rejections are good: they prove the guardrails are working. Also review orders that were accepted but were close to the limit. If the agent is repeatedly hitting the cap, the scope may be too tight or the strategy may be too aggressive. Either way, the log tells you before the account is damaged. Look for patterns in the timestamps. A steady rhythm of orders suggests the agent is following its schedule. A burst of orders in a single second may indicate a loop or a feedback bug. The log is not just a compliance record. It is a diagnostic tool that reveals how the agent thinks.

Look for unexpected market access. If the key is scoped to stocks but the log shows an attempted order for a perps venue, that is a sign the agent logic is drifting. Correct the agent instructions or tighten the scope. Review the error codes too. A series of rejections followed by a successful order may mean the agent is retrying with modified parameters. For guidance on observability, see how to set up audit logs and observability for trading agents with hard limits.

How do you keep custody while letting the agent trade?

Scoped keys preserve custody by construction. The wallet is yours, and the key is only a delegated spending authority. The agent cannot move funds to an address that you have not pre-approved, and it cannot withdraw to itself. This means that even a compromised or malfunctioning agent can only lose what is inside the scoped budget, not the entire wallet balance. The owner-approved withdrawal list is the final backstop. You can add or remove addresses only through an owner-signed action, which the agent cannot forge. This architecture is what makes the system non-custodial. The agent trades with real money, but it never holds that money. It can only direct it within the narrow corridor defined by the key.

You should still treat key rotation as a regular habit. If you change strategy, revoke the old key and issue a new one with a fresh scope. Do not reuse a broad key across multiple agents or strategies. Narrow, single-purpose keys are easier to debug, safer to revoke, and simpler to audit. If one agent misbehaves, you can kill its key without affecting the others. Think of each key as a single thread of responsibility. When that thread ends, cut it. Do not leave old keys active in the background. An unused key with broad permissions is a liability.