Security
Purple Flea is an API platform for AI agents handling real financial operations across casino, trading, wallet, and domain services. This document covers every layer of the security model — from API key lifecycle to wallet custody to circuit breakers — so you can build agents that operate safely at scale.
Security Overview
AI agents executing financial transactions introduce a distinct threat model compared to traditional web applications. A compromised agent can drain funds autonomously, accumulate losses without a human noticing, or propagate exploits across hundreds of concurrent sessions. Purple Flea's security architecture is designed around three principles that directly address these risks.
API Key Security
API keys are the primary credential for Purple Flea. Every request to every endpoint must include a valid API key. Understanding the full lifecycle — generation, rotation, scoping, and revocation — is essential for operating securely.
Generating, rotating, and revoking keys
Keys are generated from the dashboard at purpleflea.com/dashboard or programmatically via the management API. A newly generated key is shown exactly once — copy it immediately and store it in secrets management. Purple Flea does not store the plaintext key after generation.
| Operation | Endpoint | Notes |
|---|---|---|
| Generate new key | POST /v1/keys | Returns key once — store immediately |
| List keys | GET /v1/keys | Returns key prefixes only, never plaintext |
| Rotate key | POST /v1/keys/:id/rotate | Old key invalidated after 60-second grace window |
| Revoke key immediately | DELETE /v1/keys/:id | Instant — in-flight requests using the key will 401 |
Rotation grace window. When you rotate a key via POST /v1/keys/:id/rotate, the old key remains valid for 60 seconds to allow zero-downtime deploys. After the grace window expires, the old key is permanently invalidated. If you suspect compromise, use DELETE /v1/keys/:id instead — this revokes immediately with no grace window.
Key scoping: read-only vs. full access
Every key is issued with a scope at creation time. The scope cannot be upgraded after issuance — generate a new key with broader scope if needed. Apply the principle of least privilege: grant only the permissions the agent actually uses.
| Scope | Prefix | Permitted Operations |
|---|---|---|
| Read-only | sk_ro_... | GET endpoints only: balances, prices, bet history, audit logs. No writes, no transactions. |
| Trade | sk_trade_... | Casino bets and trading orders. Cannot initiate wallet sends or withdrawals. |
| Wallet | sk_wallet_... | Wallet sends and receives. Cannot place bets or trading orders. |
| Full access | sk_live_... | All operations including withdrawals and key management. Use only in secure server-side environments. |
Never use a full-access key in an agent that only needs a subset of operations. A compromised sk_trade_ key cannot drain your wallet. A compromised sk_live_ key can. Segment by scope.
Code examples: secure vs. insecure key handling
The most common key compromise vector is accidental exposure in source code, logs, or version control. The following examples show the correct pattern and the patterns to avoid.
Environment variable best practices
- Store keys in your platform's native secrets management: AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, Doppler, or equivalent.
- Add
.envto.gitignore— but treat.envfiles as a development convenience only, not a production secrets store. - Rotate secrets on a schedule (every 90 days is a reasonable baseline) and immediately upon any personnel change or suspected compromise.
- Audit which CI/CD jobs and services have access to each secret. Principle of least privilege applies to machines, not just humans.
- Use separate keys for separate environments:
PF_API_KEY_PROD,PF_API_KEY_SANDBOX. Never reuse production keys in staging pipelines.
Authentication & Authorization
Bearer token authentication
Every Purple Flea API endpoint requires a Bearer token in the Authorization header. There is no session-based or cookie-based auth — every request is independently authenticated.
Keys are verified on every request against a low-latency in-memory store. Revoked keys return 401 within milliseconds of revocation — there is no cache delay that would allow a revoked key to remain effective.
Agent ID isolation
Each agent on Purple Flea has a unique Agent ID. Agents are fully isolated: an agent can only read its own balance, place bets from its own funds, and initiate sends from its own wallet. Even if two agents are owned by the same account, they cannot access each other's funds or data.
Why this matters for multi-agent deployments. When you run a fleet of agents — for example, 50 concurrent trading bots — each agent gets its own funded sub-wallet and isolated state. A single compromised agent cannot access the capital allocated to other agents. Damage is strictly bounded to the compromised agent's allocation.
| Resource | Isolated Per Agent | Notes |
|---|---|---|
| Balance | Yes | Each agent has its own balance; no cross-agent reads |
| Transaction history | Yes | Audit logs are scoped per agent ID |
| Bet state | Yes | Active bets cannot be settled by another agent |
| Wallet addresses | Yes | Each agent has its own derived HD wallet path |
| Spending limits | Yes | Limits are enforced per agent, not per account |
Request signing for webhook verification (HMAC-SHA256)
When Purple Flea delivers webhooks to your endpoint (for settlement events, deposit confirmations, etc.), each request is signed with HMAC-SHA256 using your webhook secret. You must verify this signature before processing the payload — otherwise a malicious party could forge events.
Always verify webhook signatures. An unverified webhook endpoint that triggers a withdrawal or bet settlement is a critical vulnerability. An attacker who knows your endpoint URL can send forged events and cause your agent to act on fabricated data.
The signature is delivered in the X-PurpleFlea-Signature header as sha256=<hex_digest>. Compute HMAC-SHA256(webhook_secret, raw_request_body) and compare in constant time.
Wallet Security
HD wallet derivation (BIP32/BIP44)
Purple Flea wallets are hierarchical deterministic wallets following BIP32/BIP44. Every agent wallet is derived from a master seed using a deterministic path — the same seed always produces the same addresses. This makes wallet recovery predictable and auditable.
| Chain | Derivation Path | Standard |
|---|---|---|
| Ethereum / EVM | m/44'/60'/0'/0/0 | BIP-44 |
| Bitcoin (native segwit) | m/84'/0'/0'/0/0 | BIP-84 |
| Solana | m/44'/501'/0'/0' | BIP-44 |
| Tron | m/44'/195'/0'/0/0 | BIP-44 |
| Polygon / Base / Arbitrum | m/44'/60'/0'/0/0 | BIP-44 (EVM-compatible) |
Standard derivation paths mean Purple Flea wallets are fully portable. If you have the seed phrase, you can import any agent wallet into MetaMask, Ledger, or any BIP-44-compatible wallet for emergency access or withdrawal without depending on the Purple Flea API.
Key custody model: HSM-backed storage
Purple Flea offers two custody models depending on the wallet type you create.
POST /v1/wallet/send, the HSM signs the transaction in a tamper-resistant environment. Keys are never exposed to application memory or logs. This model is simpler to integrate but requires trusting Purple Flea's infrastructure.
POST /v1/wallet/broadcast. Purple Flea never sees your private key. Suitable for agents where key exposure is unacceptable.
HSM specifications. Purple Flea uses FIPS 140-2 Level 3 certified HSMs for custodial key storage. Key material never leaves the HSM boundary in plaintext. All signing operations are logged and auditable via GET /v1/audit-log.
Withdrawal limits and cooling periods
Custodial wallets are subject to withdrawal controls designed to limit damage from compromised keys or runaway agents.
| Control | Default | Configurable |
|---|---|---|
| Single withdrawal limit | $5,000 equivalent | Yes — lower via API |
| 24-hour rolling withdrawal cap | $25,000 equivalent | Yes — lower via API |
| Cooling period after key rotation | 30 minutes | No — fixed for security |
| New address whitelist delay | 10 minutes | Partial — can increase, not remove |
The cooling period after key rotation prevents an attacker who briefly obtained a key from immediately withdrawing funds — by the time they act, the key has been rotated and the cooling window gives you time to whitelist new addresses before a withdrawal can proceed.
Multi-sig for large amounts
For agents managing balances above $50,000 equivalent, Purple Flea supports multi-signature withdrawal policies. Withdrawals above a configured threshold require approval from a second key (typically held by a human operator or separate security system). Multi-sig policies are configured at the account level and apply to all agent wallets under that account.
Contact hello@purpleflea.com to configure multi-sig withdrawal policies. This feature is available on the Business tier and above.
Network Security
TLS 1.3+ on all endpoints
All Purple Flea API endpoints enforce TLS 1.3 minimum. TLS 1.0 and 1.1 connections are rejected. TLS 1.2 is accepted for compatibility with older runtimes but TLS 1.3 is strongly preferred — it eliminates renegotiation attacks and improves performance via 0-RTT resumption for returning clients.
HSTS is enforced. All responses include Strict-Transport-Security: max-age=31536000; includeSubDomains; preload. HTTP requests are rejected with 301 to the HTTPS equivalent. There is no fallback to plaintext.
CORS policy
The Purple Flea API is not intended to be called directly from browser JavaScript. The CORS policy reflects this: Access-Control-Allow-Origin is not set to wildcard. API calls from browser contexts will be blocked by the browser's same-origin policy unless you have an explicitly approved origin.
If you are building a frontend that proxies through your own backend (the correct pattern), your backend calls the Purple Flea API directly with a server-side key. The frontend should never hold an API key.
IP allowlisting
Enterprise tier customers can restrict which IP addresses or CIDR ranges are permitted to use a given API key. IP allowlisting is enforced at the CDN edge layer via Cloudflare Access, before the request reaches Purple Flea infrastructure.
To configure IP allowlisting, submit your IP ranges via the dashboard or contact hello@purpleflea.com. Keep in mind that IP restrictions may interfere with agents running in cloud environments with dynamic IP allocation — use static IPs or Elastic IPs when enabling this feature.
DDoS protection
All endpoints are behind Cloudflare's anycast network. Cloudflare provides automatic volumetric DDoS mitigation at layers 3, 4, and 7, with scrubbing capacity measured in terabits per second. For AI agent workloads specifically:
- High-frequency API traffic from agents (hundreds of requests per second) is recognized and allowed through bot filters when originating from authenticated, allowlisted sources.
- Unauthenticated high-frequency traffic is rate-limited at the CDN layer independent of application-level rate limits documented in Rate Limits.
- Enterprise customers can request Cloudflare IP allowlisting to bypass bot heuristics entirely for their agent infrastructure IPs.
Operational Security for Agent Developers
Building an AI agent that touches real money introduces operational risks that are qualitatively different from standard web development. An agent can autonomously take hundreds of actions per second. A logic bug or compromised credential can cause irreversible loss in minutes. The following practices are non-negotiable for production deployments.
Never log API keys or private keys
Logging frameworks, APM tools, and error trackers routinely capture entire request objects, environment variables, and stack frames. A single mistaken log statement can expose your API key to your entire logging infrastructure, every employee with log access, and any log aggregator breach.
Authorization header. Configure your HTTP client or middleware to strip authorization headers from request logs.
Sandbox vs. production environments
Purple Flea maintains fully separate sandbox and production environments. Sandbox keys use the prefix sk_test_ and route to api-sandbox.purpleflea.com. Sandbox transactions are simulated — no real funds move and no real blockchain transactions are broadcast.
| Environment | Base URL | Key Prefix | Real Funds |
|---|---|---|---|
| Production | api.purpleflea.com | sk_live_... | Yes |
| Sandbox | api-sandbox.purpleflea.com | sk_test_... | No |
Run all agent logic in sandbox first. The sandbox environment is functionally identical to production. New agent versions should run in sandbox for at least 24 hours before being promoted to production with real capital. Catching a runaway loop in sandbox costs nothing; catching it in production after 60 seconds of autonomous trading may not.
Spending limits per agent
Every agent can be configured with hard spending limits enforced server-side. When an agent's cumulative spend over a rolling window exceeds the configured limit, all further transactional requests return 429 Too Many Requests with a Retry-After header indicating when the window resets.
Spending limits are the primary guard against runaway agents. Set them conservatively — you can always raise them manually if a legitimate use case requires it, but an autonomous agent that exceeds its limit will stop itself before catastrophic loss.
Circuit breakers: auto-stop on loss threshold
A circuit breaker monitors cumulative losses and halts the agent if losses exceed a defined threshold within a time window. Unlike spending limits (which restrict individual transactions), circuit breakers respond to net loss across a session — the right control for catching a stategy that is systematically losing money.
The following example implements a circuit breaker at the application level in Python. This pattern should be used in all production agent deployments regardless of server-side limits.
Incident Response
Revoking a compromised key immediately
If you believe an API key has been compromised, revoke it immediately. Do not wait to investigate first — you can rotate and replace the key in seconds, and the investigation can happen afterward with the key already neutralized.
After revoking, generate a replacement key with the same scope and update your secrets store. Check the audit log for any suspicious activity that occurred while the key was potentially compromised.
Incident response SLAs
Incident status is posted in real time at purpleflea.com/status. Post-mortems for Critical and High incidents are published in the changelog within 7 days of resolution.
Contact
Security incidents and vulnerability reports: security@purpleflea.com
General support: hello@purpleflea.com
Affected users are notified directly. If an incident affects your API key, agent balance, or personal data, you will be contacted at the email on your account within the applicable SLA window. Make sure your account email is actively monitored.
Bug bounty program
Purple Flea operates a responsible disclosure program. Researchers who discover and report security vulnerabilities in good faith are eligible for recognition and compensation based on severity.
| Severity | Examples | Reward Range |
|---|---|---|
| Critical | Funds theft, auth bypass, RNG manipulation | $1,000 – $10,000 |
| High | IDOR across agents, mass key exposure, XSS in dashboard | $250 – $1,000 |
| Medium | Rate limit bypass, minor info disclosure, CORS misconfiguration | $50 – $250 |
| Low | Security header misconfiguration, non-sensitive info disclosure | Recognition + swag |
Report vulnerabilities to security@purpleflea.com with a description, proof of concept, and impact assessment. We will acknowledge within 24 hours and provide a fix timeline within 72 hours. Public disclosure is coordinated with the researcher after a fix is deployed.
Safe harbor. Security researchers acting in good faith who follow responsible disclosure practices will not face legal action from Purple Flea. We commit to not pursuing claims under the CFAA or equivalent statutes against researchers who report to us before public disclosure. In-scope research conducted without causing damage to users or service availability is explicitly permitted.
Out of scope
- Volumetric denial-of-service attacks (handled by Cloudflare infrastructure)
- Social engineering attacks against Purple Flea employees
- Vulnerabilities in third-party dependencies with published upstream fixes
- Issues requiring physical access to infrastructure
- Self-XSS or attacks that require the victim to already have account access
Compliance
Data retention policies
Purple Flea retains different categories of data for different periods based on operational requirements and legal obligations.
| Data Category | Retention Period | Notes |
|---|---|---|
| Transaction records (bets, trades, sends) | 7 years | Required for financial record-keeping; accessible via audit log API |
| API request logs | 90 days | Includes IP, endpoint, and response code; not request bodies |
| Authentication events | 1 year | Key usage, rotation, and revocation events |
| Account data | Duration of account + 90 days post-deletion | Personal data purged on verified deletion request |
| Webhook delivery logs | 30 days | Includes delivery attempts and response codes |
Audit logs
Complete audit logs for all transactional events are available via the API. Audit logs include the agent ID, API key prefix, source IP, action, parameters, and result for every request that mutated state (bets, trades, wallet sends, key changes).
Audit logs are write-once and tamper-evident. Log entries cannot be modified or deleted via the API. Deletion requests for personal data result in pseudonymization of personally identifiable fields while retaining the financial event record.
What Purple Flea does not do
If you receive a communication claiming to be from Purple Flea that requests any of the following, it is a scam.
Developer Security Checklist
Complete this checklist before promoting an agent to a production environment with real capital. All items are binary — either done or not done.
.env files committed to version control, or application databases.
sk_trade_ or sk_ro_ key, not sk_live_, unless full access is strictly required.
Authorization header from request logs.
X-PurpleFlea-Signature using hmac.compare_digest or crypto.timingSafeEqual.
daily_spend_usd, single_bet_max_usd, and single_trade_max_usd set to conservative values via PATCH /v1/agents/:id/limits.
GET /v1/audit-log on a schedule.
verify=False or equivalent. Certificate pinning is recommended for high-value deployments.
Questions about this checklist or the security architecture? Email security@purpleflea.com. For enterprise security reviews and custom compliance requirements, contact hello@purpleflea.com.