crypto-com-app

What this skill does

# Skill: crypto-com-app

## Agent Capability Requirements

This skill requires your agent platform to support the following capabilities. If your platform lacks any **required** capability, the skill will not function.

| Capability | Required | Details |
|---|---|---|
| **Shell command execution** | Yes | Must be able to run `npx tsx ./scripts/...` and capture stdout |
| **Environment variables** | Yes | Must read `CDC_API_KEY` and `CDC_API_SECRET` from the shell environment |
| **JSON parsing** | Yes | Must parse structured JSON from script stdout to extract fields |
| **Multi-turn conversation** | Yes | Trading uses a quote → confirm flow that spans multiple user turns |
| **Persistent memory** | No | Used for `confirmation_required` preference. If unsupported, default to always confirming trades |
| **Elapsed-time awareness** | No | Used to check quote expiry (`countdown` field). If unsupported, always attempt confirmation and handle `invalid_quotation` errors gracefully |

## CRITICAL: How This Skill Works

**You MUST use the TypeScript scripts for ALL API interactions. NEVER call the API directly with `curl`, `fetch`, or any other HTTP method.**

The scripts handle request signing, error handling, and response formatting. If you bypass them:
- The request will fail (missing HMAC signature)
- The response won't be filtered or structured

**For every user request, find the matching command below and run it via `npx tsx`. Read the JSON output. Act on it.**

## Configurations
- BASE_URL: `https://wapi.crypto.com`
- CDC_API_KEY: `{{env.CDC_API_KEY}}`
- CDC_API_SECRET: `{{env.CDC_API_SECRET}}`
- CONFIRMATION_REQUIRED: `{{memory.confirmation_required}}` (Default: true)
- SKILL_DIR: The directory containing this `SKILL.md` file. Resolve it from the path you loaded this file from (e.g. if you read `/home/user/skills/crypto-com-app/SKILL.md`, then `SKILL_DIR` is `/home/user/skills/crypto-com-app`).

## Environment Setup
- Both `CDC_API_KEY` and `CDC_API_SECRET` must be set as environment variables before use.
- **Before running any script**, check whether both variables are set by running:
  ```bash
  echo "CDC_API_KEY=${CDC_API_KEY:+set}" "CDC_API_SECRET=${CDC_API_SECRET:+set}"
  ```
  If either prints empty instead of `set`, prompt the user:
  > "Your API credentials are not configured. Please set them in your terminal before I can proceed:
  > ```
  > export CDC_API_KEY="your-api-key"
  > export CDC_API_SECRET="your-api-secret"
  > ```
  > You can generate an API key at https://help.crypto.com/en/articles/13843786-api-key-management.
  > Let me know once you've set them."
  
  Then **stop and wait** for the user to confirm before retrying.
- If a script returns a `MISSING_ENV` error, treat it the same way: prompt the user to set the variables and wait.

## Script Commands

**ALL API interactions MUST go through these scripts.** They handle signing, execution, filtering, and error formatting. Run the appropriate command below via shell, then parse the JSON output.

**Prerequisite:** `npx tsx` (Node.js 18+ required; `tsx` is fetched automatically by `npx`).

**Important:** All script paths below use `$SKILL_DIR` as a placeholder for this skill's root directory. Resolve it from the path you loaded this SKILL.md from, or `cd` into the skill directory and use `./scripts/...` as the path. Either approach works.

### Account Commands

```bash
# Filtered non-zero balances (scope: fiat | crypto | all)
npx tsx $SKILL_DIR/scripts/account.ts balances [fiat|crypto|all]

# Single token balance lookup
npx tsx $SKILL_DIR/scripts/account.ts balance <SYMBOL>

# Weekly trading limit
npx tsx $SKILL_DIR/scripts/account.ts trading-limit

# Find funded source wallets for a trade type
npx tsx $SKILL_DIR/scripts/account.ts resolve-source <purchase|sale|exchange>

# Kill switch — revoke API key
npx tsx $SKILL_DIR/scripts/account.ts revoke-key
```

### Trade Commands

Trading follows a **two-step flow**: get a quotation first, then confirm the order.

```bash
# Step 1 — Get quotation (type: purchase | sale | exchange)
npx tsx $SKILL_DIR/scripts/trade.ts quote <type> '<json-params>'
# Returns: {"ok": true, "data": {"id": "<quotation-id>", "from_amount": {...}, "to_amount": {...}, "countdown": 15, ...}}

# Step 2 — Confirm order: pass the data.id from Step 1 as <quotation-id>
npx tsx $SKILL_DIR/scripts/trade.ts confirm <type> <quotation-id>

# View recent transactions
npx tsx $SKILL_DIR/scripts/trade.ts history
```

**How to map user intent to trade type:**

| User says | Trade type | From | To |
|-----------|-----------|------|-----|
| "Buy CRO with 100 USD" | `purchase` | USD (fiat) | CRO (crypto) |
| "Sell 0.1 BTC" | `sale` | BTC (crypto) | USD (fiat) |
| "Swap 0.1 BTC to ETH" | `exchange` | BTC (crypto) | ETH (crypto) |

**Quotation JSON params by trade type:**

| Type | JSON fields |
|------|------------|
| purchase | `{"from_currency":"USD","to_currency":"CRO","from_amount":"100"}` or use `to_amount` instead |
| sale | `{"from_currency":"BTC","to_currency":"USD","from_amount":"0.1","fixed_side":"from"}` |
| exchange | `{"from_currency":"BTC","to_currency":"ETH","from_amount":"0.1","side":"buy"}` |

**Example — "Buy CRO with 100 USD":**

1. Run: `npx tsx $SKILL_DIR/scripts/trade.ts quote purchase '{"from_currency":"USD","to_currency":"CRO","from_amount":"100"}'`
2. Read `data.id`, `data.from_amount`, `data.to_amount`, `data.countdown` from the response.
3. **If confirmation required** (default): Ask user "Confirm: 100 USD for X CRO? Valid for {countdown}s. Reply 'YES' to proceed."
   - If user says YES (within countdown): `npx tsx $SKILL_DIR/scripts/trade.ts confirm purchase <data.id>`
4. **If confirmation opted out** (`memory.confirmation_required` is `false`): Skip asking and immediately run `npx tsx $SKILL_DIR/scripts/trade.ts confirm purchase <data.id>`

**Opt-in / Opt-out:** Users can say "stop asking for confirmation" to auto-execute trades, or "require confirmation" to re-enable the prompt. See Section 3 below.

### Coin Discovery Commands

```bash
# Search coins
npx tsx $SKILL_DIR/scripts/coins.ts search '{"keyword":"BTC","sort_by":"rank","sort_direction":"asc","native_currency":"USD","page_size":10}'
```

**Required JSON parameters:**

| Parameter | Type | Allowed values |
|-----------|------|----------------|
| `sort_by` | string | `rank`, `market_cap`, `alphabetical`, `volume`, `performance` |
| `sort_direction` | string | `asc`, `desc` |
| `native_currency` | string | Uppercase currency code (e.g. `USD`) |
| `keyword` | string | Search string, 1–100 chars; matches coin name and symbol only |
| `page_size` | integer | Number of results per page |

**Optional:** `page_token` — opaque token for fetching the next page (see pagination below).

**Pagination:** The response includes a `pagination` object with `has_more` (boolean) and `next_page_token` (string). When `has_more` is `true`, pass `next_page_token` as `page_token` in the next request to fetch the next page.

**Key response fields per coin:** `rails_id` (identical to `currency_id` / `currency` in trade and account APIs — use this to cross-reference), `price_native`, `price_usd`, `percent_change_*_native` (price performance over past timeframes, e.g. `percent_change_24h_native`).

### Cash (Fiat) Commands

Cash commands handle deposits, withdrawals, and bank account management.

```bash
# Cash overview — balances + available payment networks per currency
npx tsx $SKILL_DIR/scripts/fiat.ts discover

# Payment networks for a currency
npx tsx $SKILL_DIR/scripts/fiat.ts payment-networks <CURRENCY>

# Deposit method details (bank routing info)
npx tsx $SKILL_DIR/scripts/fiat.ts deposit-methods <CURRENCY> <DEPOSIT_METHOD>

# Email deposit instructions to user
npx tsx $SKILL_DIR/scripts/fiat.ts email-deposit-info <CURRENCY> <VIBAN_TYPE>

# Withdrawal details (quotas, fees, minimums)
npx tsx $SKILL_DIR/scripts/fiat.ts withdrawal-details <CURRENCY> <VIBAN_TYPE>

# Create withdrawal order (returns order with fees + r