/credentials

name: credentials
description: "Secure credential management for trading platforms"
emoji: "🔐"

Credentials - Complete API Reference

Securely store and manage API credentials for trading platforms with AES-256-GCM encryption.

---

Chat Commands

Add Credentials

/creds add polymarket                       Interactive setup
/creds add kalshi --key abc --secret xyz    Direct setup
/creds add binance                          Add Binance API
/creds add hyperliquid                      Add wallet key

View Credentials

/creds list                                 List configured platforms
/creds status                               Encryption system status
/creds test polymarket                      Test API connection
/creds check polymarket                     Verify credentials work

Remove Credentials

/creds remove polymarket                    Remove platform creds
/creds clear                                Clear all (careful!)

Auth Status

/auth status                                Overall auth status
/auth refresh kalshi                        Refresh tokens
/auth cooldown                              View cooldown status

---

TypeScript API Reference

Create Credentials Manager

import { createCredentialsManager } from 'clodds/credentials';

const creds = createCredentialsManager({
  // Encryption key (required)
  encryptionKey: process.env.CREDENTIALS_KEY,

  // Storage backend
  storage: 'sqlite',  // 'sqlite' | 'postgres'
  dbPath: './credentials.db',

  // Cooldown settings
  cooldownMinutes: 15,
  maxFailures: 3,
});

Set Credentials

// Polymarket (API + signing key)
await creds.setCredentials({
  userId: 'user-123',
  platform: 'polymarket',
  credentials: {
    apiKey: 'pk_...',
    apiSecret: 'sk_...',
    privateKey: '0x...',  // For order signing
    funderAddress: '0x...',
  },
});

// Kalshi (API key)
await creds.setCredentials({
  userId: 'user-123',
  platform: 'kalshi',
  credentials: {
    email: 'user@example.com',
    apiKey: 'key_...',
  },
});

// Binance Futures
await creds.setCredentials({
  userId: 'user-123',
  platform: 'binance',
  credentials: {
    apiKey: 'abc...',
    apiSecret: 'xyz...',
  },
});

// Hyperliquid (wallet)
await creds.setCredentials({
  userId: 'user-123',
  platform: 'hyperliquid',
  credentials: {
    privateKey: '0x...',
    walletAddress: '0x...',
  },
});

Get Credentials

// Get for specific platform
const polymarketCreds = await creds.getCredentials({
  userId: 'user-123',
  platform: 'polymarket',
});

if (polymarketCreds) {
  console.log(`API Key: ${polymarketCreds.apiKey}`);
  // Credentials are decrypted on retrieval
}

// List user's configured platforms
const platforms = await creds.listUserPlatforms('user-123');
console.log(`Configured: ${platforms.join(', ')}`);

Delete Credentials

// Remove single platform
await creds.deleteCredentials({
  userId: 'user-123',
  platform: 'kalshi',
});

// Remove all for user
await creds.deleteAllCredentials('user-123');

Test Credentials

// Test API connection
const result = await creds.testCredentials({
  userId: 'user-123',
  platform: 'polymarket',
});

if (result.success) {
  console.log(`✓ Connected to ${result.platform}`);
  console.log(`  Balance: $${result.balance}`);
} else {
  console.log(`✗ Failed: ${result.error}`);
}

Cooldown Management

// Mark failed auth attempt
await creds.markFailure({
  userId: 'user-123',
  platform: 'kalshi',
  error: 'Invalid API key',
});

// Check if in cooldown
const inCooldown = await creds.isInCooldown({
  userId: 'user-123',
  platform: 'kalshi',
});

if (inCooldown) {
  const remaining = await creds.getCooldownRemaining({
    userId: 'user-123',
    platform: 'kalshi',
  });
  console.log(`Cooldown: ${remaining} minutes remaining`);
}

// Mark successful auth (resets failures)
await creds.markSuccess({
  userId: 'user-123',
  platform: 'kalshi',
});

Build Trading Context

// Get ready-to-use trading context
const context = await creds.buildTradingContext({
  userId: 'user-123',
  platform: 'polymarket',
});

// Context includes authenticated client
await context.client.getBalance();
await context.client.placeOrder({ ... });

---

Supported Platforms

| Platform | Credentials Required | |----------|---------------------| | **Polymarket** | API key, secret, private key, funder address | | **Kalshi** | Email, API key | | **Betfair** | App key, session token | | **Smarkets** | API key | | **Binance** | API key, secret | | **Bybit** | API key, secret | | **Hyperliquid** | Private key, wallet address | | **MEXC** | API key, secret |

---

Security Features

| Feature | Description | |---------|-------------| | **AES-256-GCM** | Military-grade encryption at rest | | **Per-user keys** | Isolated credential storage | | **Cooldown** | Rate limits on failed attempts | | **No logging** | Secrets never logged | | **Memory wipe** | Credentials cleared from memory after use |

---

Environment Variables

# Required encryption key (generate with: openssl rand -hex 32)
CREDENTIALS_KEY=your-64-char-hex-key

# Optional: per-platform keys
POLYMARKET_API_KEY=pk_...
POLYMARKET_API_SECRET=sk_...
POLYMARKET_PRIVATE_KEY=0x...
KALSHI_EMAIL=user@example.com
KALSHI_API_KEY=key_...

---

Best Practices

1. **Strong encryption key** — Use `openssl rand -hex 32` 2. **Rotate keys regularly** — Update API keys periodically 3. **Test after adding** — Always verify credentials work 4. **Minimal permissions** — Use read-only keys when possible 5. **Backup securely** — Keep encrypted backups offline