proxmox/config/btc-settlement-pathways.json

{
  "schemaVersion": 1,
  "updated": "2026-04-03",
  "description": "End-to-end pathways from Chain 138 to native BTC via Changelly (partner API) or Atomic Wallet (user-operated swap). Used by orchestration design; does not imply keys or contracts are configured.",
  "homeChainId": 138,
  "destinationAsset": {
    "symbol": "BTC",
    "network": "bitcoin-mainnet",
    "addressFormat": "bech32-p2wpkh-or-legacy"
  },
  "references": {
    "mainnetLiquidityPlan": "docs/00-meta/MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md",
    "rampUserFlows": "docs/04-configuration/MAINNET_RAMP_USER_FLOWS.md",
    "deployedBridgesStatus": "docs/11-references/DEPLOYED_TOKENS_BRIDGES_LPS_AND_ROUTING_STATUS.md",
    "changellyDocs": "https://docs.changelly.com/",
    "changellySupportEmail": "pro@changelly.com",
    "atomicWalletSwapKb": "https://support.atomicwallet.io/article/73-how-to-make-an-exchange"
  },
  "changelly": {
    "product": "Changelly Exchange API v2",
    "integrationSurface": "backend_jsonrpc",
    "apiBaseUrl": "https://api.changelly.com/v2",
    "authentication": {
      "headers": ["X-Api-Key", "X-Api-Signature"],
      "signatureAlgorithm": "RSA-SHA256 over raw JSON-RPC body",
      "note": "Generate RSA keypair; register public key with Changelly; never expose private key to browsers."
    },
    "documentedRpcFlow": [
      "getCurrencies",
      "getPairsParams",
      "getMinAmount",
      "validateAddress",
      "getExchangeAmount",
      "createTransaction",
      "getTransactions (poll status)"
    ],
    "envVars": [
      "CHANGELLY_API_PUBLIC_KEY",
      "CHANGELLY_API_PRIVATE_KEY_PEM_PATH"
    ]
  },
  "atomicWallet": {
    "product": "Atomic Wallet (desktop/mobile)",
    "integrationSurface": "user_operated",
    "note": "Swaps route through in-wallet partners to deposit addresses; there is no documented first-party B2B swap API equivalent to Changelly v2 for arbitrary server-side settlement. Use for operator or end-user manual path after funds sit on a chain Atomic supports.",
    "supportedChainsForSwap": "See in-app asset list; typically includes BTC and major EVM assets when counterpart is available."
  },
  "pathways": [
    {
      "id": "138-evm-changelly-btc-treasury",
      "label": "Automated-friendly: 138 → Ethereum mainnet stables/ETH → Changelly → BTC payout address",
      "venue": "changelly",
      "automationTier": "high",
      "summary": "Bridge and swap on-chain until Ethereum holds USDT, USDC, ETH, or WETH that Changelly lists; backend calls createTransaction with payout btc address; treasury sends the exact deposit amount to Changelly’s deposit address.",
      "preconditions": [
        "Ethereum mainnet liquidity for chosen bridge (LiquidityPoolETH / CCIP WETH path per MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md)",
        "Changelly partner API key registered (pro@changelly.com)",
        "Treasury hot wallet on Ethereum with gas ETH and sendable USDT/USDC/ETH per quote",
        "Confirm Changelly ticker names for from-currency (e.g. eth, usdt20, usdc) match your token contract version"
      ],
      "steps": [
        {
          "order": 1,
          "chainId": 138,
          "action": "swap_to_bridge_asset",
          "detail": "Use DODOPMMIntegration / EnhancedSwapRouter on 138 to convert source (e.g. cUSDT, cUSDC) into the token your bridge expects (often WETH for CCIP WETH bridges, or corridor-specific asset)."
        },
        {
          "order": 2,
          "chainId": 138,
          "action": "bridge_to_ethereum",
          "detail": "Execute CCIP or trustless bridge to Ethereum mainnet per deployed bridge matrix (DEPLOYED_TOKENS_BRIDGES_LPS_AND_ROUTING_STATUS.md)."
        },
        {
          "order": 3,
          "chainId": 1,
          "action": "optional_swap_on_mainnet",
          "detail": "If payout asset is wrong shape (e.g. WETH only, need USDT), swap on mainnet via DEX/aggregator to Changelly-accepted from-currency."
        },
        {
          "order": 4,
          "chainId": 0,
          "action": "changelly_quote_and_create",
          "detail": "JSON-RPC: getMinAmount, getExchangeAmount, validateAddress(BTC), createTransaction with amount, from, to btc, address = user btc address. Store payin address + id."
        },
        {
          "order": 5,
          "chainId": 1,
          "action": "send_payin",
          "detail": "Broadcast Ethereum tx from treasury to Changelly deposit address for exact amount; single output per Changelly rules for UTXO targets."
        },
        {
          "order": 6,
          "chainId": 0,
          "action": "poll_until_btc_sent",
          "detail": "Poll getTransactions / status until outbound BTC confirmed; record btc txid for reconciliation."
        }
      ]
    },
    {
      "id": "138-evm-atomic-user-btc",
      "label": "User-operated: 138 → Ethereum → Atomic Wallet swap → BTC",
      "venue": "atomic_wallet",
      "automationTier": "low",
      "summary": "After funds arrive on an Ethereum address the user controls in Atomic Wallet, user runs in-app Exchange to BTC; no server-side Atomic swap API in repo.",
      "preconditions": [
        "Bridge completes to user-controlled Ethereum address (same EOA in MetaMask and Atomic, or user sends to Atomic-seeded wallet)",
        "User installs Atomic Wallet and holds seed phrase",
        "Asset appears in Atomic’s supported list for swap into BTC"
      ],
      "steps": [
        {
          "order": 1,
          "chainId": 138,
          "action": "swap_and_bridge_to_user_eoa_mainnet",
          "detail": "Same as Changelly path steps 1–2 but recipient is user’s Ethereum mainnet address."
        },
        {
          "order": 2,
          "chainId": 1,
          "action": "user_opens_atomic_exchange",
          "detail": "In Atomic: Exchange → select from asset (ETH/USDT/USDC etc.) → to BTC → enter amount and destination BTC address (often same app wallet’s BTC account)."
        },
        {
          "order": 3,
          "chainId": 0,
          "action": "user_completes_partner_flow",
          "detail": "Follow Atomic prompts (rates non-fixed, ~20 min typical per vendor KB); user bears slippage and network fees."
        }
      ]
    }
  ]
}