coboglobal/cobo-cli/cobo-waas

Cobo WaaS Skill

This skill uses cobo-cli to perform WaaS 2.0 and Portal tasks (wallets, transfers, logs). It is self-contained for agentic coding tools (Claude Code, Codex, Cursor, Gemini CLI).

Quick Start

Fastest path to your first API call:

# 1. Verify installation
cobo version                           # If fails: pip install cobo-cli
# 2. Set environment
cobo env dev                           # Use dev for testing
# 3. Login (OAuth — opens browser, auto-registers API key)
cobo login -u                          # Authorize in browser when prompted
# 4. Generate API keys
cobo keys generate --key-type API      # Secret saved automatically
# 5. Register key
cobo keys register        # dev/sandbox only — auto-registers
# For prod: cobo open developer → add public key manually + grant permissions
# 6. Set auth method
cobo auth apikey
# 7. Test it works
cobo get /wallets --limit 1            # Should return JSON

Run SDK samples (Python/Node/Go/Java): load env from config once, then run your script in the same shell:

• macOS / Linux (bash, zsh): eval $(cobo config env)
• Windows PowerShell: cobo config env --format powershell | Invoke-Expression
• Windows CMD: cobo config env --format cmd > env.bat && env.bat

Then e.g. python your_script.py or node app.js.

When to Use

• The user wants to interact with Cobo WaaS 2.0 or Portal using the CLI
• The task needs a CLI-only path instead of MCP
• The task includes configuring env/auth, generating keys, wallet operations, transfers, logs, or GraphQL queries
• The user wants to generate SDK code for Python, Node.js, Go, or Java

State Detection

Before starting, run these checks and fix any issues automatically — do not ask the user to run commands manually.

# Is CLI installed?
cobo version
# Is it configured?
cobo config list
# Does auth work?
cobo get /wallets --limit 1

Execution principle: always run the fix commands yourself. Only stop and ask the user when human interaction is unavoidable (e.g. browser OAuth login, manual Portal permission grant in prod). For detailed diagnostics, see references/diagnostics.md.

Before Generating API Requests (reduce errors)

Always look up the endpoint’s parameters before generating CLI or SDK code.

1. Identify the API path from the user’s intent (e.g. “list wallets” → GET /wallets, “create wallet” → POST /wallets).
2. Look up parameters: run cobo doc <path> (e.g. cobo doc /wallets) and read the printed operation description (parameters, types, required/optional).
3. Then generate the exact cobo get/post ... or SDK call using those parameter names and types.

Example: before writing cobo get /wallets ... or SDK code for listing wallets, run cobo doc /wallets and use the output to build the correct query (e.g. limit, cursor). This reduces wrong parameter names, wrong types, and missing required fields.

Reference Navigation

Choose the right reference for your task:

SDK / generated code rules (avoid over-engineering)

Applies to all languages (Python, Node.js, Go, Java). When generating SDK or script code, follow the template for that language exactly; do not add extra structure the user did not ask for.

1. Use the template as the single source of style. For each language the canonical style is in assets/templates/ (python.md, ts-node.md, go.md, java.md). Copy the minimal setup and one short block per operation (e.g. list wallets = a few lines: call the API, then a short loop or print). Same requirement for Python, Node/TS, Go, and Java.
2. Do not add unless the user explicitly asks (in any language):

• Wrapper/helper functions that hide the API (e.g. getClient(), listWallets(api, ...))
• Every optional parameter in signatures — only pass what the task needs (e.g. limit=10)
• Converting responses to custom shapes (e.g. plain dict/JSON, custom DTOs)
• Long module/function docstrings, usage instructions in comments, or heavy error handling

1. Match the template snippet length. In every language, template examples are a few lines per operation. Generated code should be the same size unless the user asks for more.
2. When in doubt, generate less. Prefer the minimal version from the template for that language; the user can ask for more structure or error handling if needed.

Use-case Oriented Workflow

Pick the smallest slice that solves the task:

1. Configure environment and auth - references/onboarding.md
2. Generate and validate keypair - references/auth.md
3. Discover and describe API endpoints - Run cobo doc <path> (e.g. cobo doc /wallets) for parameter details, then references/cli.md
4. Create wallets and addresses - references/recipes.md Recipe 2-3
5. Create transfers and check status - references/recipes.md Recipe 4-5
6. Debug failures - references/errors.md, references/troubleshooting.md
7. Set up webhooks - references/recipes.md Recipe 7
8. Run GraphQL queries - references/graphql.md
9. Generate SDK code - references/sdk-patterns.md, references/samples/*

Output Format for Agents

After each action, return a short JSON object:

Success Response

{
  "action": "create_wallet",
  "status": "ok",
  "ids": {
    "wallet_id": "f47ac10b-58cc-..."
  },
  "links": {
    "portal_wallet_url": "https://portal.cobo.com/wallets/f47ac10b-..."
  },
  "next_step": "Create address with: cobo post /wallets/{wallet_id}/addresses --chain_id ETH",
  "notes": "Custodial Asset wallet created successfully"
}

Error Response

{
  "action": "create_wallet",
  "status": "error",
  "error": {
    "code": 401,
    "message": "Unauthorized"
  },
  "diagnosis": "API key not registered in Portal",
  "recovery": "Register public key: cobo keys register (dev/sandbox) or cobo open developer (prod)",
  "reference": "references/errors.md#401-unauthorized"
}

Error Code Response Format

API responses may include both HTTP status codes and business error codes (error_code). They serve different purposes:

• HTTP Status Code: Indicates the HTTP-level result (200=success, 4xx=client error, 5xx=server error)
• Business Error Code (`error_code`): Provides specific business logic error details in the response body

Example error response with both:

{
  "error_code": 2024,
  "error_message": "Unauthorized",
  "error_id": "48d1f0c3382f4c50a11ff529a2c3a65a"
}

HTTP status: 401 Unauthorized

Recovery Patterns

When operations fail, execute the fix automatically — do not show the user a list of commands to run manually.

1. Identify the error - Check HTTP status code, error_code in response body, and message
2. Diagnose - Run relevant diagnostic commands
3. Consult reference - Check references/errors.md or references/troubleshooting.md
4. Apply fix - Execute the recovery commands directly
5. Verify - Re-run the original operation and confirm success

HTTP Status Code Recovery

Business Error Code Recovery

When response includes error_code field, use specific recovery steps: