agentwalletapi

What this skill does

# OpenclawCash Agent API

Interact with OpenclawCash-managed wallets to send native assets and tokens, check balances, execute DEX swaps, and manage Polymarket account, orders, and redeem flows via Polygon wallets.
This skill may also be referred to as `openclawcash`.

## Requirements

- Required env var: `AGENTWALLETAPI_KEY`
- Optional env var: `AGENTWALLETAPI_URL` (default: `https://openclawcash.com`)
- Required local binary: `curl`
- Optional local binary: `jq` (for pretty JSON output in CLI)
- Network access required: `https://openclawcash.com`

## Preferred Integration Path

- If the client supports MCP, prefer the public OpenClawCash MCP server:
  ```bash
  npx -y @openclawcash/mcp-server
  ```
- Use MCP as the primary execution path because tools, schemas, and results are structured for the client.
- Use the included CLI script only as a fallback when MCP is unavailable or the client cannot attach MCP servers.
- MCP and the CLI script target the same underlying OpenClawCash agent API. They are two access paths, not two different products.

## Safety Model

- Start with read-only calls (`wallets`, `wallet`, `balance`, `tokens`) on testnets first.
- High-risk actions are gated:
  - API key permissions in dashboard (`allowWalletCreation`, `allowWalletImport`)
  - Explicit CLI confirmation (`--yes`) for write actions
- Agents should establish an approval mode early in the session for write actions:
  - `confirm_each_write`: ask before every write action.
  - `operate_on_my_behalf`: after one explicit onboarding approval, execute future write actions without re-asking, as long as the user keeps instructing the agent in the same session.
- For `operate_on_my_behalf`, the agent should treat the user's later task messages as execution instructions and run the corresponding write commands with `--yes`.
- Ask again only if:
  - the user revokes or changes approval mode
  - the session is restarted or memory is lost
  - the action is outside the scope the user approved
  - the agent is unsure which wallet, token, amount, destination, spender, or chain is intended
- If the user gives only a broad instruction like "go ahead" but execution details are still missing, gather the missing details first instead of repeating a generic permission request.

## Setup

1. Run the setup script to create your `.env` file:
   ```
   bash scripts/setup.sh
   ```
2. Edit the `.env` file in this skill folder and replace the placeholder with your real API key:
   ```
   AGENTWALLETAPI_KEY=occ_your_api_key
   ```
3. Get your API key at https://openclawcash.com (sign up, create a wallet, go to API Keys page).

## Legacy CLI Fallback

If MCP is unavailable, use the included tool script to make API calls directly:

```bash
# Read-only (recommended first)
bash scripts/agentwalletapi.sh wallets
bash scripts/agentwalletapi.sh user-tag-get
bash scripts/agentwalletapi.sh user-tag-set my-agent-tag --yes
bash scripts/agentwalletapi.sh wallet Q7X2K9P
bash scripts/agentwalletapi.sh wallet "Trading Bot"
bash scripts/agentwalletapi.sh balance Q7X2K9P
bash scripts/agentwalletapi.sh transactions Q7X2K9P
bash scripts/agentwalletapi.sh tokens mainnet

# Write actions (require explicit --yes)
export WALLET_EXPORT_PASSPHRASE_OPS='your-strong-passphrase'
bash scripts/agentwalletapi.sh create "Ops Wallet" sepolia WALLET_EXPORT_PASSPHRASE_OPS --yes
bash scripts/agentwalletapi.sh import "Treasury Imported" mainnet --yes
bash scripts/agentwalletapi.sh import "Poly Ops" polygon-mainnet --yes
# Automation-safe import: read private key from stdin instead of command args
printf '%s' '<private_key>' | bash scripts/agentwalletapi.sh import "Treasury Imported" mainnet - --yes
bash scripts/agentwalletapi.sh transfer Q7X2K9P 0xRecipient 0.01 --yes
bash scripts/agentwalletapi.sh transfer Q7X2K9P 0xRecipient 100 USDC --yes
bash scripts/agentwalletapi.sh quote mainnet WETH USDC 10000000000000000
bash scripts/agentwalletapi.sh quote solana-mainnet SOL USDC 10000000 solana
bash scripts/agentwalletapi.sh swap Q7X2K9P WETH USDC 10000000000000000 0.5 --yes
# Checkout escrow lifecycle
bash scripts/agentwalletapi.sh checkout-payreq-create Q7X2K9P 30000000 --yes
bash scripts/agentwalletapi.sh checkout-payreq-get pr_a1b2c3
bash scripts/agentwalletapi.sh checkout-escrow-get es_d4e5f6
bash scripts/agentwalletapi.sh checkout-quick-pay es_d4e5f6 Q7X2K9P --yes
bash scripts/agentwalletapi.sh checkout-swap-and-pay-quote es_d4e5f6 Q7X2K9P
bash scripts/agentwalletapi.sh checkout-swap-and-pay-confirm es_d4e5f6 Q7X2K9P 1 --yes
bash scripts/agentwalletapi.sh checkout-release es_d4e5f6 --yes
bash scripts/agentwalletapi.sh checkout-refund es_d4e5f6 --yes
bash scripts/agentwalletapi.sh checkout-cancel es_d4e5f6 --yes
bash scripts/agentwalletapi.sh checkout-webhooks-list
# Polymarket setup is user-managed in dashboard Venues settings
# Direct setup page: https://openclawcash.com/venues/polymarket
bash scripts/agentwalletapi.sh polymarket-market Q7X2K9P 123456 BUY 25 FAK 0.65 --yes
bash scripts/agentwalletapi.sh polymarket-resolve https://polymarket.com/market/market-slug No
bash scripts/agentwalletapi.sh polymarket-account Q7X2K9P
bash scripts/agentwalletapi.sh polymarket-orders Q7X2K9P OPEN 50
bash scripts/agentwalletapi.sh polymarket-activity Q7X2K9P 50
bash scripts/agentwalletapi.sh polymarket-positions Q7X2K9P 100
bash scripts/agentwalletapi.sh polymarket-redeem Q7X2K9P all 100 --yes
bash scripts/agentwalletapi.sh polymarket-redeem Q7X2K9P 1234567890 100 --yes
bash scripts/agentwalletapi.sh polymarket-cancel Q7X2K9P order_id_here --yes
```

### Base-Units Rule (Important)

- `quote.amountIn`, `swap.amountIn`, `approve.amount`, and transfer `valueBaseUnits` must be **base-units integer strings** (digits only).
- Do **not** send decimal strings in these fields (for example, `0.001`), or validation will fail immediately.
- Examples:
  - `0.001 ETH` -> `1000000000000000` wei
  - `1 USDC` (6 decimals) -> `1000000`
- For transfer, use `amountDisplay` when you want human-readable units and let the API convert.
- Legacy transfer aliases `amount` and `value` are still accepted for compatibility.

### Import Input Safety

- Wallet import is optional and not required for normal wallet operations (list, balance, transfer, swap).
- Import works only when the user explicitly enables API key permission `allowWalletImport` in dashboard settings.
- Import execution requires explicit confirmation in the CLI (`--yes` for automation, or interactive `YES` prompt).
- Avoid passing sensitive inputs as CLI arguments when possible (shell history/process logs risk).
- Preferred options:
  - Interactive hidden prompt: omit the private key argument.
  - Automation: pass `-` and pipe input via stdin.

## Base URL

```
https://openclawcash.com
```

## Troubleshooting

If requests fail because of host/URL issues, use this recovery flow:

1. Open `agentwalletapi/.env` and verify `AGENTWALLETAPI_KEY` is set and has no extra spaces.
2. If the API host is wrong or unreachable, set this in the same `.env` file:
   ```
   AGENTWALLETAPI_URL=https://openclawcash.com
   ```
3. Retry a simple read call first:
   ```bash
   bash scripts/agentwalletapi.sh wallets
   ```
4. If it still fails, report the exact error and stop before attempting transfer/swap actions.

## Authentication

The API key is loaded from the `.env` file in this skill folder. For direct HTTP calls, include it as a header:

```
X-Agent-Key: occ_your_api_key
Content-Type: application/json
```

## API Surfaces

- **Agent API (API key auth):** `/api/agent/*`
  - Authenticate with `X-Agent-Key`
  - Used for autonomous agent execution (wallets list/create/import, transactions, balance, transfer, swap, quote, approve, checkout escrow lifecycle, and polymarket venue operations)
- Public docs intentionally include only `/api/agent/*` endpoints.

## Workflow

1. `GET /api/agent/wallets` - Discover available wallets (id, label, address, network, chain). Optional `?includeBalances=true` adds native `balance` +