AGENTS

cdcx Agent Integration Guide

This guide provides comprehensive integration documentation for AI agents using the cdcx CLI and MCP server.

Table of Contents

1. Authentication
2. Error Handling
3. Rate Limiting
4. Safety Tiers
5. MCP Server Setup
6. Example Workflows
7. Best Practices

Authentication

Credential Resolution

The CLI resolves credentials in this order:

1. Environment variables (highest priority)

   export CDC_API_KEY="ABC123"
   export CDC_API_SECRET="XYZ789"
   cdcx account info
   

2. Config file (lowest priority)

   # ~/.config/cdcx/config.toml
   [profiles.default]
   api_key = "ABC123"
   api_secret = "XYZ789"
   

Verification

Before executing trading or account operations, verify authentication:

cdcx account info

Expected response on success:

{"status":"ok","result":{...account data...}}

Expected response on auth failure:

{
  "status":"error",
  "error":{
    "category":"auth",
    "code":10002,
    "message":"Invalid API key",
    "retryable":false
  }
}

For Agents Using MCP

Configure services and start the MCP server:

cdcx mcp config --enable trade,account
cdcx mcp

The server will attempt to resolve credentials from the environment or config file. If credentials are not available for private endpoints, the MCP server will reject requests with an auth error.

Error Handling

Error Categories

All errors returned by cdcx fall into well-defined categories. Each error envelope includes:

• category — Error classification (see table below)
• code — CDC exchange error code (0 for non-CDC errors)
• message — Human-readable error message
• retryable — Whether the operation should be retried

Category	Description	CDC Codes	Retryable	Guidance
auth	Authentication or authorization failure	10002, 10003, 10006, 10007, 40101, 40102	No	Check API key and secret. Verify permissions on the key.
validation	Invalid parameters or request format	10001, 10004, 10005, 10008, 10009	No	Check parameter types and values. Use cdcx schema show <method> to verify.
safety	Operation blocked by safety rails	N/A	No	Set acknowledged=true in parameters for mutate-tier commands.
rate_limit	Too many requests (HTTP 429)	42901	Yes	Implement exponential backoff (start with 1s, max 32s).
insufficient_funds	Account balance too low	20001, 306	No	Check balance with cdcx account summary before retrying.
order_error	Order rejection or processing failure	20002, 20005, 20006, 20007, 318	Maybe	Verify order parameters. Check if order was partially filled.
network	Connection, timeout, or I/O error	N/A	Yes	Retry with exponential backoff.
api	API returned non-zero code (unmapped)	Varies	Depends	Check code and message for guidance.
config	Configuration or setup error	N/A	No	Fix configuration. Check file paths and syntax.
io	File or stream I/O error	N/A	Maybe	Check file permissions and disk space.