DOCSEARCHbyAlgolia
Submit Docs

clodds AI Trading Terminal

repository·main·Indexed 19 days ago

https://github.com/alsk1992/cloddsbot

An open-source AI trading terminal powered by Claude for prediction markets, crypto spot, and perpetual futures. Supports trading on Polymarket, Kalshi, Betfair, Binance, Bybit, Hyperliquid, and Solana DEXs via Telegram, Discord, Slack, or a web interface. Features include arbitrage detection, whale tracking, copy trading, DeFi swaps, MEV protection, and Bittensor (TAO) mining management. Version 1.8.0.

Tokens
257.5K
Snippets
856
Records
1.1K
Agent score
68%

What's inside clodds

  1. Overview of the Agent Commerce Protocol (ACP)

    main

    The Agent Commerce Protocol (ACP) is a framework designed to enable agent-to-agent commerce. It facilitates secure transactions through on-chain escrow on the Solana blockchain, cryptographic agreements using Ed25519 signatures, and intelligent service discovery. The protocol architecture consists of several layers:

    • ACP Layer: Includes modules for Registry (agent/service management), Agreement (proof-of-agreement), Escrow (on-chain payments), Discovery (service matching), Identity (@handles and referrals), and Predictions (forecasts and Brier scores).
    • Persistence Layer: Uses SQLite for storing agent profiles, services, agreements, escrow records, and ratings.
    • Blockchain Layer: Utilizes the Solana blockchain for executing escrow transfers.

    Developers can interact with ACP via a CLI (using the /acp prefix) or through 39 programmatic agent tools.

  2. Clodds API Overview and Base URL

    main

    The Clodds API provides HTTP and WebSocket endpoints for external integrations such as dashboards, mobile apps, automation scripts, Telegram/Discord bots, and AI agent tools (MCP, LangChain).

    By default, the gateway binds to the loopback address on port 18789.

    Base URL: http://127.0.0.1:18789

    http://127.0.0.1:18789

  3. System Overview of Clodds

    main

    Clodds is a modular AI trading terminal designed around three core principles:

    1. Multi-Channel Communication: Supports connectivity through 21 different messaging platforms (e.g., Telegram, Discord, Slack, WhatsApp, Matrix, Signal, Teams, WebChat).
    2. Multi-Market Integration: Provides access to 10 prediction markets and 7 futures exchanges, including on-chain Solana perpetuals.
    3. AI-First Design: Utilizes a Claude-powered agent architecture featuring semantic memory and a wide array of specialized tools.

  4. Clanker Token Specifications and Best Practices

    main

    Token Constraints

    • Supply: Fixed at 100 billion.
    • Vault Limits: Maximum 90% of supply can be vaulted (minimum 10% must go to Liquidity Pool).
    • Extensions: Maximum of 10 extensions allowed.
    • Rewards: Maximum of 7 reward recipients.

    Fees and Protection

    • Sniper Protection: Default protection reduces fees from 66% to 4% over a 15-second window.
    • Fee Split: By default, trading fees are split 80% to the creator and 20% to the interface.

    Best Practices

    1. Test first: Always use /clanker simulate before committing to a real deployment.
    2. Quality images: Ensure your token image is already uploaded to IPFS before deployment.
    3. Configure vesting: Use the --vault options to lock tokens and build community trust.
    4. Use vanity: Use the --vanity flag to generate memorable addresses for marketing.
    5. Deploy on Base: Use the base chain for lower gas fees compared to Ethereum mainnet.

  5. How weather edge is calculated

    main

    The weather skill calculates edge by comparing official NOAA probability against the current Polymarket YES price.

    Formula: Edge = NOAA Probability - Market Price

    Example:

    • NOAA forecast: 80% chance of rain in NYC.
    • Polymarket YES price: 0.65 (65%).
    • Edge: $80% - 65% = +15%$. This indicates a bet on YES.

    Confidence Levels based on Edge:

    • High: Edge $\ge$ 15%
    • Medium: Edge 10-15%
    • Low: Edge 5-10%

  6. Escrow Authorization Rules and Security

    main

    Escrow operations in ACP are governed by strict authorization rules to ensure security.

    Authorization Matrix

    ActionAuthorized Parties
    FundBuyer only
    ReleaseBuyer or Arbiter
    RefundSeller (anytime), Buyer (after expiry), Arbiter (anytime)
    DisputeBuyer or Seller
    Resolve DisputeArbiter only

    Security Warnings

    • Keypair Management: Escrow keypairs are stored in memory only. For production environments, use a proper escrow program with Program Derived Addresses (PDAs) and implement secure key management (HSM, KMS). Never restart the service while there are active funded escrows.
    • Supported Assets: Currently, only native SOL is supported. Support for SPL tokens requires additional implementation for associated token account creation and rent handling.

  7. Understand Divergence Detection and Strategy Tags

    main

    The detection algorithm monitors spot price ticks across multiple time windows (5s, 10s, 15s, 30s, 60s, 90s, 120s). It calculates spotMovePct = (now - then) / then * 100 by comparing the current price to the price $N$ seconds ago.

    A signal is generated if the move meets a threshold and the Polymarket price is fresh (< 5s stale).

    Strategy Tag Format

    Signals are encoded using the pattern: {ASSET}_{DIR}_s{bucket}_w{window}.

    • Example: BTC_DOWN_s12-14_w15 indicates a BTC price drop of 0.12% - 0.14% over a 15-second window.

    Threshold Buckets

    BucketSpot Move Range
    s08-100.08% - 0.10%
    s10-120.10% - 0.12%
    s12-140.12% - 0.14%
    s14-160.14% - 0.16%
    s16-200.16% - 0.20%
    s20+0.20%+

  8. Plugin Directory Structure and Metadata

    main

    A Clodds plugin should follow a specific directory structure and include a package.json for metadata and permission declarations.

    Recommended Structure:

    • index.ts: The main entry point.
    • package.json: Metadata and configuration.
    • settings.json: Default settings.
    • commands/: Directory for command handlers.
    • tools/: Directory for tool definitions.
    • assets/: Directory for static assets.

    package.json Requirements: Use the clodds key to define requirements and capabilities:

    • minVersion: Minimum required Clodds version.
    • permissions: Array of requested access levels.
    • commands: Array of registered command names.
    • tools: Array of registered tool names.
    {
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My custom plugin",
  "main": "index.ts",
  "clodds": {
    "minVersion": "0.1.0",
    "permissions": ["network", "storage"],
    "commands": ["my-command"],
    "tools": ["my-tool"]
  }
}

  9. Important Trading Notes for Opinion.trade

    main

    When trading on Opinion.trade via Clodds, keep the following technical constraints in mind:

    • Chain: BNB Chain (chainId 56).
    • Token IDs: These are large uint256 integers. Always use string representation when passing them to avoid precision issues.
    • Rate Limits: 15 requests per second.
    • Order Signing: Uses EIP-712 typed data signatures.
    • Fees: Verify the current fee structure directly on the Opinion.trade platform.

  10. Verify Clodds Webhook signatures

    main

    When using callbackUrl in compute requests, Clodds posts results to your endpoint. To ensure the request is authentic, verify the X-Clodds-Signature header. This header contains an HMAC-SHA256 signature of the request body, generated using your webhook secret.

    // Example Webhook Payload
{
  "id": "req_123",
  "jobId": "job_456",
  "service": "llm",
  "status": "completed",
  "result": { ... },
  "cost": 0.05,
  "timestamp": 1706500000000
}

  11. Divergence Skill Exit Logic

    main

    The divergence skill uses several mechanisms to exit positions:

    1. Force exit: Triggered automatically < 30s before market expiry.
    2. Take profit: Exits when PnL $\ge$ 15% (configurable via --tp).
    3. Stop loss: Exits when PnL $\le$ -25% (configurable via --sl).
    4. Trailing stop: Activated once PnL reaches +10%; exits if the price drops 8% from the High Water Mark (HWM).
    5. Time exit: Triggered < 2min before expiry.

  12. How the Market Making (mm) skill works

    main

    The Market Making skill follows a continuous cycle to provide liquidity while managing risk:

    1. Fair Value Calculation: Computes fair value from the orderbook using methods like weighted_mid, vwap, or ema.
    2. Spread Adjustment: The spread is dynamically adjusted based on recent volatility (spreads widen in volatile markets).
    3. Inventory Skew: Quotes are shifted away from the overweight side to manage inventory levels.
    4. Order Placement: Quotes are placed as post-only maker orders (both bid and ask).
    5. Requote Cycle: The bot cancels existing orders, recalculates parameters, and places new orders.
    6. Auto-halt: The system automatically halts if realized P&L exceeds the configured --max-loss threshold.