proxmox/docs/04-configuration/BTC_SETTLEMENT_CHANGELLY_ATOMIC_PATHWAYS.md

Pathways: Chain 138 → native BTC (Changelly & Atomic Wallet)

Purpose: Define how value moves from Chain 138 to native BTC on Bitcoin mainnet using Changelly (partner API, automation-friendly) and Atomic Wallet (in-app swap, user-operated). Machine-readable steps live in config/btc-settlement-pathways.json.

Related: MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md (mainnet liquidity for bridges), MAINNET_RAMP_USER_FLOWS.md, DEPLOYED_TOKENS_BRIDGES_LPS_AND_ROUTING_STATUS.md.

---

1. Changelly (recommended for orchestration)

Changelly operates a white-label crypto-to-crypto product: Exchange API v2 (JSON-RPC over HTTPS). You implement calls only on a backend; keys must not ship to browsers. Official docs: Changelly Exchange API v2.

1.1 Partner onboarding

1. Generate an RSA key pair (Changelly documents the format in Generate keys).
2. Register at changelly.com and email pro@changelly.com with account email, public key, and Base64 public key, plus project description (per Getting started).
3. Store the private key in your secrets vault (file path or KMS); map env vars in .env.master.example (CHANGELLY_*).

1.2 Auth model

Each request sends:

• X-Api-Key — SHA-256 hash of your public key (hex), as documented.
• X-Api-Signature — RSA-SHA256 signature of the exact JSON-RPC body.

See Authentication.

1.3 Typical API sequence (BTC payout)

Use the methods listed in config/btc-settlement-pathways.json under changelly.documentedRpcFlow. In practice:

1. getCurrencies / getPairsParams — Confirm from tickers you will fund (e.g. eth, usdt20, usdc) and to = btc.
2. getMinAmount — Respect minimums for the pair.
3. validateAddress — Validate the user’s BTC address before creating the transaction.
4. getExchangeAmount — Quote expected BTC out (v2 quotes must pair with v2 createTransaction).
5. createTransaction — Pass payout BTC address, from currency, and amount; receive Changelly deposit (payin) address and transaction id.
6. On Ethereum: Send the exact payin amount from your treasury wallet to the deposit address (ERC-20 transfer or native ETH per instructions).
7. getTransactions (or status polling) — Track until outbound BTC is sent; record Bitcoin txid for reconciliation.

Constraint: For currencies with multiple outputs (e.g. BTC), Changelly does not accept more than one output per address in a single transaction (Getting started).

1.4 How this attaches to Chain 138

Changelly does not speak Chain 138. Your orchestrator must first land standard Ethereum mainnet assets:

• Swap on 138 (e.g. cUSDT/cUSDC via PMM) into whatever your bridge expects (often WETH for CCIP WETH bridges).
• Bridge 138 → Ethereum using your deployed bridges; ensure mainnet liquidity so payouts do not stall (MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md).
• Optional mainnet DEX if the bridged asset is not exactly the Changelly from ticker (e.g. WETH → USDT).

Then run the Changelly sequence above from a mainnet treasury EOA or contract you control.

---

2. Atomic Wallet (user path, not a drop-in server API)

Atomic Wallet’s Exchange feature is documented for end users: you choose assets and send to partner deposit flows inside the app; rates are not fixed; completion time is vendor-dependent. See How do I make a swap? and The process of a swap.

2.1 Pathway in this project

1. Same 138 → Ethereum bridge outcome as for Changelly, but funds must end on an Ethereum address the user controls in Atomic (import the same key, or transfer to Atomic’s ETH account).
2. User opens Exchange in Atomic, selects from (e.g. ETH, USDT, USDC if listed) to BTC, confirms quote, completes the flow.
3. Ops / compliance: Treat as manual or semi-manual; idempotency and server-side reconciliation are your bookkeeping, not Atomic’s public API in this pathway.

2.2 Why not “just call Atomic’s API” like Changelly?

There is no first-party, documented B2B swap API in Atomic’s public knowledge base equivalent to Changelly v2 for arbitrary server-to-BTC settlement. Third-party portfolio / connectivity products may exist; they are out of scope for this repo unless you add a dedicated integration with contractual coverage.

Use Atomic when end users already use the wallet and you accept human-in-the-loop swaps. Use Changelly when you need backend-driven create-and-pay flows.

---

3. Architecture sketch (orchestrator)

flowchart LR
  subgraph chain138 [Chain 138]
    A[Source tokens e.g. cUSDT cUSDC]
    B[PMM or router swap]
    C[Bridge lock or CCIP send]
  end
  subgraph mainnet [Ethereum mainnet]
    D[Recipient treasury or user EOA]
    E[Optional DEX to USDT USDC ETH]
  end
  subgraph settlement [BTC settlement]
    F[Changelly createTransaction plus payin tx]
    G[Atomic user Exchange]
    H[Native BTC UTXO payout]
  end
  A --> B --> C --> D --> E
  E --> F --> H
  E --> G --> H

---

4. What you still implement in software

Piece	Changelly path	Atomic path
Bridge + swap planner	Required	Required
Secure Changelly JSON-RPC client	Required	N/A
Treasury mainnet wallet + gas	Required	User wallet
Job store + idempotency + status UI	Required	Optional / manual
BTC address validation	Via Changelly + local checks	User

---

5. Env placeholders

See CHANGELLY_* in .env.master.example. Do not commit private keys; use a secrets manager or encrypted PEM path on servers.