How to scope API keys for a trading agent that handles real money

A scoped API key is the boundary between an autonomous agent and your capital. It defines which markets the agent can access, the maximum notional dollars it can expose, the addresses where funds may land, and whether the key is allowed to send live orders at all. Before an agent ever submits a buy or sell instruction, the key should already enforce the constraints that keep the agent inside a predetermined safety zone. This article is a practical guide for developers who need to configure those boundaries correctly. Developers often focus on model accuracy and signal generation, but in live trading the infrastructure boundary matters more than the prediction quality. A perfectly accurate model can still destroy capital if it lacks spend caps, if it can trade instruments it does not understand, or if it can send funds to an unverified address. Scoped keys address these risks by turning policy into a hardware like rule that the API enforces independently of the agent's code.

What does a scoped API key actually control?

At the core of the Felix model is the idea that permission and capital should be constrained at the infrastructure layer, not merely in the agent's prompt or logic. A scoped API key carries a policy that is evaluated on every request. The policy typically includes several dimensions that you configure when the key is minted.

• ·Permitted market types, such as stocks, crypto spot, perpetual futures, options, or prediction markets.
• ·A global budget cap, expressed in US dollars, which limits the total notional value of open positions plus pending orders.
• ·Per market sub limits, so that an agent authorized for both stocks and perps cannot accidentally concentrate the entire budget in a single volatile contract.
• ·Allowed actions, such as create, amend, or cancel orders, and a reduce only mode that lets the agent exit but never increase risk.
• ·A withdrawal address whitelist that restricts where funds can land if the agent ever triggers a transfer.

Position sizing is normalized to plain US dollars by the API, but the key still enforces the ceiling. If the agent attempts to place an order that would push the total exposure above the cap, the request is rejected before it reaches a venue. This removes an entire class of accidents where an agent misreads decimal places, lot sizes, or contract multipliers. The key does not trust the agent to do the math correctly; it verifies the dollar impact itself.

Another critical control is the allowed action set. A key can be scoped to create orders only, or it can include cancel and amend permissions. Some developers start with a key that allows only reduce only orders, which lets the agent exit positions but never increase risk. This is useful during testing or when the agent is transitioning from paper to live trading. The exact permission model is documented, but the principle is that each capability must be explicitly granted rather than implicitly allowed.

How should you structure a key for paper trading versus live trading?

Felix separates paper trading and live trading into two distinct key types. A paper key points to simulated market data and simulated fills. It lets the agent exercise its logic, generate signals, and observe slippage estimates without touching real capital. The paper key should still carry the same budget caps and market restrictions you intend to use in production, because the goal is to validate behavior under realistic constraints, not to let the agent roam freely in a sandbox.

Promoting a key to live trading requires an explicit owner authorization step. The owner, who controls the wallet, must approve the withdrawal addresses and confirm the budget cap before the key can send orders that move real funds. This design prevents a compromised development environment or a misconfigured CI pipeline from silently upgrading a test key to live execution. The agent itself cannot perform this promotion; only the owner can.

In practice, developers should store the paper key and live key as separate secrets in their deployment environment. Use environment variables or a secrets manager to inject the correct key at runtime. Never commit either key to version control. The paper key is still a credential that can consume rate limits and generate simulated fills, so it should be rotated on the same schedule as the live key.

Developers should treat the paper key as a strict rehearsal, not a toy. If the paper key is more permissive than the live key, the rehearsal is misleading. Align the scopes, then change only the environment flag. How algorithmic traders can start with self custody and hard limits discusses the broader setup of constraints before going live.

Why do withdrawal addresses matter as much as order limits?

The system is non custodial by construction. Funds remain in a wallet that the owner controls through standard cryptographic means. The agent receives a scoped key that lets it place orders, but the key cannot withdraw funds to an arbitrary address. Withdrawal destinations are owner approved at key creation time. If the agent is compromised, the attacker can only trade within the key's limits; they cannot sweep the wallet to an external account.

This property is what makes the architecture suitable for autonomous agents. Without hardcoded withdrawal addresses, a software bug or a malicious prompt injection could instruct the agent to drain the wallet. With scoped addresses, the API layer blocks any transfer that does not match the pre approved list. The agent can lose money through bad trades, and it can lose the entire budget if the strategy fails, but it cannot steal the principal by moving it elsewhere.

Developers should configure the withdrawal list with the same rigor as the trading budget. Use cold storage or treasury addresses that you control, and avoid reusing addresses across unrelated strategies. If you need to change a destination, rotate the key rather than editing a live policy in place. How self custody works for algorithmic traders covers the wallet architecture in more detail.

Where does the kill switch fit in the key lifecycle?

A scoped key is not a static credential. It is a live policy that can be tightened, paused, or revoked. The kill switch is the most aggressive form of revocation. When triggered, it flattens all open positions, cancels all pending orders, and disables the key permanently. The owner can trigger it manually, and some developers wire it to automated health checks that detect anomalous behavior, such as a sudden spike in order frequency or an unexpected market type.

The kill switch is distinct from a simple API key deletion. Deleting a key might leave positions open and exposed to market risk. The kill switch is designed to wind down exposure first. It is also distinct from the exit plans and take profit rules that the agent may carry in its own logic. The agent's exit plan is a strategy; the kill switch is an emergency brake. Both should exist, but they should not depend on each other. How to automate exit plans and take profit rules for an AI trading agent explains how to build strategy level exits that complement the kill switch.

Monitoring should expose the key state in real time. A dashboard that shows the remaining budget, the list of open positions by market type, and the last time the key was used gives the owner situational awareness. If the agent is silent for an unexpected period, or if it is trading outside its usual hours, the owner can investigate before the kill switch becomes necessary. Observability and scoping work together; the key defines the boundaries, and the logs prove whether the agent stayed inside them.

You should test the kill switch during the paper trading phase. Verify that it cancels orders quickly and that the resulting flattened state respects the key's budget cap. Latency and partial fills are real, so the switch should handle the case where some orders cannot be closed instantly. The goal is not perfect zero exposure in milliseconds, but a rapid, deterministic wind down that the agent itself cannot override.

How do you connect an agent to a scoped key through MCP or REST?

Developers have two primary paths. You can connect an agent through MCP tools, which is the typical pattern for Claude, Cursor, and other MCP clients. In this model, the agent calls a tool that wraps the Felix API, and the tool carries the scoped key. The agent does not see the key directly; it sees a function named something like place_order or get_position. The tool implementation enforces the policy before forwarding the request.

Alternatively, you can call the REST API directly from your own code. This is common when the agent is a custom service written in Python, Go, or Rust. The exact request schema is in the docs; the shape looks like this.

{
  "api_key": "YOUR_KEY",
  "market_type": "perpetual_futures",
  "order_notional_usd": 150,
  "side": "buy",
  "reduce_only": false
}

The agent sends a plain dollar amount, and the API translates it into the venue specific contract size, margin requirement, and tick rounding. The key policy is checked after normalization. If the order violates the budget cap or the allowed market list, the API returns an error before any external venue sees the request. This means the developer does not need to replicate the policy logic inside the agent.

Whether you use MCP or REST, store the key in a secrets manager, not in the codebase. Rotate the key if you suspect any exposure. Scoped keys are revocable instantly, so the blast radius of a leaked credential is limited to the remaining budget and open positions, not the entire wallet.

What can go wrong if the key is too permissive?

Overly broad permissions create failure modes that no amount of prompt engineering can fix. If the key allows all five market types but the agent was only tested on stocks, a misunderstood signal could open a leveraged perpetual futures position. If the budget cap is set to the full wallet balance instead of a strategy specific subset, a runaway loop could exhaust the entire account. Trading can lose money, including everything, and a permissive key accelerates that outcome.

Drawdown limits are another parameter that should live in the key policy, not in the agent's strategy file. A key level drawdown limit measures the peak to trough decline of the strategy's allocated budget. If the agent loses, say, twenty percent of its allocation, the key can automatically halt new orders and enter a reduce only mode. This prevents the agent from doubling down in an attempt to recover losses. The owner retains the ability to reset the drawdown limit after reviewing the agent's behavior, but the default posture is to stop trading when the limit is breached.

Another common mistake is granting amend and cancel permissions without restrictions. A compromised agent could cancel legitimate stop orders, replace them with larger sizes, or chase prices across multiple venues. The scoped key should match the agent's actual needs. If the agent does not need options, remove options. If it does not need to withdraw, remove withdrawal permissions entirely. The principle of least privilege applies to trading infrastructure exactly as it applies to server access.

Finally, avoid the temptation to reuse a single scoped key across multiple agents or strategies. Each agent should have its own key with its own budget. This isolates failure. If one agent malfunctions, the others continue unaffected. It also simplifies audit logs, because every request can be traced to a specific key and therefore to a specific strategy. How to evaluate audit logs and observability for trading agents through one API covers the monitoring side of this architecture.

Scoped API keys are not a convenience feature. They are the structural foundation that makes non custodial agentic trading possible. By baking market permissions, dollar limits, withdrawal addresses, and lifecycle controls into the key itself, you remove the burden of safety from the agent's reasoning loop and place it in the infrastructure layer. The agent can then focus on execution, while the owner retains deterministic control over capital. Before you deploy any agent with live money, verify the key policy line by line, test the kill switch, and confirm that the withdrawal list contains only your own addresses. The cost of a misconfigured key is real capital loss.