Security

Security best practices for managing private keys and secrets.

Key Types

1. Agent Wallet Key

  • Signs orders on Hyperliquid

  • Server-side only

  • One key for entire platform

2. Oracle Key

  • Updates vault balances on-chain

  • Server-side only

  • Separate from agent key

3. Master Wallet Keys

  • User-controlled

  • Never shared with Atract

  • Stored in MetaMask/WalletConnect

Storage

Development

Local .env.local file (gitignored):

HL_AGENT_PRIVATE_KEY="0x..."
ORACLE_PRIVATE_KEY="0x..."

Never commit to git:

  • Add .env.local to .gitignore

  • Use .env.example for documentation

  • Never use production keys in dev

Production

Recommended: Environment variables in hosting platform

  • Vercel: Environment Variables section

  • AWS: Systems Manager Parameter Store

  • Docker: Secrets management

Never:

  • Hardcode in source code

  • Commit to repository

  • Expose in client-side code

  • Log to console or files

Access Control

Server-only code:

// ✅ CORRECT - Server-side only
// app/api/trade/route.ts
const agentKey = process.env.HL_AGENT_PRIVATE_KEY;

// ❌ WRONG - Never expose to client
// NEXT_PUBLIC_AGENT_KEY would be visible in browser

Key separation:

  • Agent key: Trading only

  • Oracle key: Balance updates only

  • Never reuse keys across services

Rotation

When to rotate:

  • Suspected compromise

  • Employee offboarding

  • Regular schedule (quarterly)

  • After security incident

How to rotate:

  1. Generate new key

  2. Update environment variables

  3. Restart services

  4. Verify new key works

  5. Revoke old key (if applicable)

For agent key:

  • Users must re-authorize new agent

  • Coordinate rotation with users

  • Provide migration period

Monitoring

Alert on:

  • Unauthorized use attempts

  • Key access from new IPs

  • High volume of signatures

  • Failed authentication attempts

Log (without exposing keys):

logger.info('agent_sign', 'Order signed', {
  user: maskAddress(address),
  signature: '[redacted]',
  timestamp: Date.now()
});

Backup

Backup securely:

  • Encrypted backup of keys

  • Separate from application code

  • Multiple secure locations

  • Document recovery process

Never:

  • Email keys

  • Store in Slack/Discord

  • Save in plaintext

  • Share via insecure channels

Incident Response

If key is compromised:

  1. Immediately rotate key

  2. Notify users (for agent key)

  3. Audit recent activity

  4. Review access logs

  5. Document incident

  6. Improve security measures

Best Practices

Do:

  • Use hardware wallets for high-value keys

  • Implement least-privilege access

  • Regularly audit key usage

  • Use separate keys per environment

  • Encrypt at rest

Don't:

  • Share keys between services

  • Use production keys in development

  • Hard-code keys in code

  • Expose keys in logs

  • Store keys in databases

Related Pages

PreviousEnvironment VariablesNextTerms of Service

Last updated