# Auto-convert

Auto-convert lets customers pay with coins you don't want to hold (BTC, ETH, SOL and others) while you receive
a stablecoin (USDC or USDT) in your cold wallet. A third-party swap provider does the conversion; Coldtill never
holds the funds and only credits a payment once its own nodes see the stablecoin arrive.

It is off by default, and only available on mainnet installs.

## Turning it on

Under **Project settings → Auto-convert to stablecoins** (project admin, with two-factor):

1. **Settle in:** pick USDC or USDT on Ethereum, Base, Polygon, BNB Chain or Solana. The project needs a deposit
   wallet on that network, because its cold wallet receives the stablecoin.
2. **Maximum slippage:** between 10 and 300 basis points (0.1% to 3%).
3. **THORChain fallback:** optional, off by default. See [Providers](#providers).

## What the customer sees

1. At checkout, every coin the project already takes into its own deposit wallets stays direct (for example
   USDT on Ethereum). NEAR Intents is only offered for coins that have no deposit wallet route.
2. The customer picks a coin and enters a **refund address** on that coin's chain. It is validated per chain.
3. Coldtill asks the provider for a quote that delivers exactly the amount still owed to your cold wallet. The
   quote is locked for 30 minutes (an hour for Bitcoin-like coins).
4. The checkout shows the provider's deposit address, the exact amount, the rate and the swap fee.
5. The customer pays; the checkout follows the swap through `awaiting_deposit`, `processing`, `delivering`
   and `completed`.

If the swap fails or the customer sends too little, the provider refunds the refund address. Up to three
active conversions are allowed per payment.

## How Coldtill checks a conversion

Swap providers report progress, but Coldtill treats their reports as hints only. Before a payment is credited:

- **The quote is checked:** the recipient must be your cold wallet, the destination asset must be your
  settlement asset, the guaranteed output must cover the amount owed and (for 1Click) no memo may be
  required. For THORChain, the memo's asset and recipient are parsed and checked too.
- **The delivery is verified on-chain** by your own nodes. Coldtill looks up each delivery transaction the
  provider reports and sums transfers of the settlement token to your cold wallet that:
  - come from successful transactions in blocks still on the canonical chain;
  - were mined after the conversion was created (allowing five minutes of clock skew);
  - are not from your own deposit addresses or factories (a sweep is not a delivery).
- **The transaction must be new:** a delivery transaction that is one of Coldtill's own sweeps or payouts, or
  that already credited another conversion, is refused.
- **Confirmations:** the delivery needs the network's required confirmations (Solana: `finalized`).

Anything that fails a check becomes `mismatch`, is logged as a warning (`conversion delivery mismatch`), and
shows the reason under **Conversions**. The payment is not credited. Investigate with the transaction hashes
shown; the provider's own explorer usually explains what happened.

## Providers

- **NEAR Intents 1Click** (default): every token 1Click lists, which in October 2026 was over 200 tokens on more
  than 35 chains (BTC, ZEC, XRP, TON, SUI, ADA, ETH, SOL, memecoins and others). The list comes from 1Click live.
  Known stables stay pinned to their canonical contracts so a look-alike token is never offered. Deposits need
  no memo, so customers can pay from an exchange. Without `COLDTILL_ONECLICK_API_KEY`, 1Click adds a 0.2% fee.
- **THORChain** (optional fallback): BTC, LTC, DOGE and BCH. Deposits need a memo, so the customer must pay
  from their own wallet, not an exchange. Refunds go to the sending address.

Provider endpoints are configured with `COLDTILL_ONECLICK_URL`, `COLDTILL_THORNODE_URL` and
`COLDTILL_MIDGARD_URL`. On mainnet the client never follows redirects and refuses private addresses.

## Risks

While a swap is in progress, the provider holds the customer's coins. A provider that fails to deliver or
refund costs the customer money, not you: Coldtill never credits a payment without an on-chain delivery. See
R2 in the [threat model](https://coldtill.com/docs/threat-model.md#residual-risks).

## Testing

In testnet mode auto-convert is hidden, because providers only run on mainnet. To test the flow end to end,
point `COLDTILL_ONECLICK_URL` at a stub that implements the 1Click quote and status endpoints, and make real
stablecoin transfers on a local chain (see Development).

---

Source: https://coldtill.com/docs/auto-convert/ · All Coldtill docs: https://coldtill.com/llms.txt