# Cauldron Swap

> Swap between BCH and PUSD (ParyonUSD stablecoin) using the cashtoken-cli and Cauldron DEX on Bitcoin Cash. Covers buying PUSD with BCH, selling PUSD back to BCH, and checking balances.

- Skill: `permissionless-software-foundation/cauldron-swap` (Agent Skill)
- Install (CLI): `npx skillmds@latest add permissionless-software-foundation/cauldron-swap`
- Raw SKILL.md: https://api.skillmd.com/api/skills/permissionless-software-foundation/cauldron-swap/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Permissionless-Software-Foundation (https://skillmd.com/u/permissionless-software-foundation)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/permissionless-software-foundation/cauldron-swap

---


# Cauldron DEX Swaps (BCH ↔ PUSD)

Swap between BCH and the **PUSD** stablecoin (ParyonUSD) on Bitcoin Cash using the [Cauldron DEX](https://cauldron.quest). The CLI handles pool discovery, optimal multi-pool trade splitting, quoting, and broadcast.

## CLI Location

```
/home/bot/repos/cashtoken-cli/cashtoken-cli.js
```

Always run from the repo directory:
```bash
cd /home/bot/repos/cashtoken-cli
```

## Configuration

Wallet credentials are stored in `.env`:
```bash
cat /home/bot/repos/cashtoken-cli/.env
```

Set `PRIVATE_KEY_WIF` and `NETWORK` there, or pass `--wif <WIF>` at runtime. The token-aware address is auto-derived from the WIF.

## PUSD Token Details

| Field | Value |
|-------|-------|
| Token ID | `2469acc5afa4b10cb5b5c04afb89c3a3ffd61c5da9c01e26d00951cae2a02544` |
| Decimals | 2 (1 PUSD = 100 base units) |
| Type | Stablecoin (1:1 USD peg) |

## Available Commands

### Check Balance
```bash
node cashtoken-cli.js balance --wif <WIF>
```

### Buy PUSD with BCH (recommended — uses dollar amounts)
```bash
# Buy $1 PUSD (dry-run, shows quote first)
node cashtoken-cli.js buy-pusd --amount 1 --wif <WIF>

# Buy $1 PUSD (broadcast immediately)
node cashtoken-cli.js buy-pusd --amount 1 --wif <WIF> --yes
```

### Sell PUSD for BCH (recommended — uses dollar amounts)
```bash
# Sell $1 PUSD (dry-run)
node cashtoken-cli.js sell-pusd --amount 1 --wif <WIF>

# Sell $1 PUSD (broadcast immediately)
node cashtoken-cli.js sell-pusd --amount 1 --wif <WIF> --yes
```

### Generic Swap (any CashToken)

```bash
# Buy tokens with BCH
node cashtoken-cli.js swap-bch-for-token \
  -c <64-char-token-id> \
  -a <base-units> \
  --ticker <SYMBOL> \
  --wif <WIF> \
  --yes

# Sell tokens for BCH
node cashtoken-cli.js swap-token-for-bch \
  -c <64-char-token-id> \
  -a <base-units> \
  --ticker <SYMBOL> \
  --wif <WIF> \
  --yes
```

## Typical Round-Trip Procedure

### 1. Check Balance
```bash
cd /home/bot/repos/cashtoken-cli && node cashtoken-cli.js balance --wif <WIF>
```

### 2. Buy PUSD
```bash
cd /home/bot/repos/cashtoken-cli && node cashtoken-cli.js buy-pusd --amount <Dollars> --wif <WIF> --yes
```

### 3. Verify PUSD received
```bash
cd /home/bot/repos/cashtoken-cli && node cashtoken-cli.js balance --wif <WIF>
```

### 4. Sell PUSD back to BCH
```bash
cd /home/bot/repos/cashtoken-cli && node cashtoken-cli.js sell-pusd --amount <Dollars> --wif <WIF> --yes
```

### 5. Verify BCH returned
```bash
cd /home/bot/repos/cashtoken-cli && node cashtoken-cli.js balance --wif <WIF>
```

## How It Works

1. `buy-pusd`/`sell-pusd` hardcode the PUSD token category ID and convert dollar amounts to base units automatically (multiply by 10^decimals = 100)
2. The commands fetch all active Cauldron liquidity pools from the Cauldron indexer
3. The SDK computes the optimal trade split across pools using binary search on marginal rate — minimizes price impact
4. Each pool charges 0.3% LP fee
5. Without `--yes`, the command shows a quote and exits (dry-run mode)
6. With `--yes`, it broadcasts the transaction and returns the TXID

## Notes

- **Dry-run by default**: Always verify the quote before passing `--yes`
- **Dust amount**: Token outputs require ~1000 satoshis dust (handled automatically)
- **Amount precision**: PUSD has 2 decimals, so `--amount 1` = 100 base units = $1 PUSD
- **No Cauldron fee**: Only 0.3% LP fee paid to pool providers, plus BCH network fee
- **WIF can be omitted** if `PRIVATE_KEY_WIF` is set in the `.env` file