# Introduction

**Drip Tools** lets you swap real **mainnet** tokens for **testnet** tokens. You pay a small
amount of a live asset (ETH, USDC, USDT, SOL, TON, …) on a mainnet chain, and one or more
recipients receive test tokens on the testnet of your choice — for funding QA wallets, airdrop
farming, or filling faucets that have run dry.

This section is for developers who want to run swaps **programmatically** — from a script, a
backend, or a bot — without opening the web app. In a hurry? [At a glance](https://docs.drip.tools/guide/cheatsheet.md)
fits on one screen; the [Quick Start](https://docs.drip.tools/guide/quickstart.md) is one runnable script.

## How a swap works

Drip Tools uses an **off-chain order** built around a **backend-signed quote**. You never encode
recipients or amounts on-chain: the whole order lives in the quote, and your wallet makes a single
payment that references it.

*Diagram: Your script requests a quote from the API, pays once on the FROM chain, and the backend delivers to every recipient on the testnet.*

In four steps:

1. **Discover** — [`GET /api/chains`](https://docs.drip.tools/api/discovery.md) lists the FROM (mainnet) chains, the TO
   (testnet) chains, their tokens, and each FROM chain's **pay target** (`contracts.depository`).
2. **Quote** — [`POST /api/quote`](https://docs.drip.tools/api/quote.md) with the recipients and the exact TO amounts you
   want each to receive. You get a `quoteId`, the total cost (`fromTotal`), a `deadline`, and a
   `signature`. A quote is free and commits you to nothing.
3. **Pay** — send **one** transaction on the FROM chain that carries the `quoteId`: a call to
   the depository contract on an EVM chain, or a plain transfer to the treasury with the
   `quoteId` as the memo on Solana / TON. See [Pay on-chain](https://docs.drip.tools/swap/flow.md#step-3-pay-on-chain).
4. **Track** — the backend sees the payment, expands the quote into one order per recipient, and
   sends the testnet tokens. Poll [`GET /api/order`](https://docs.drip.tools/api/orders.md) until every recipient is
   `completed`.

## Key concepts

**One direction only.** Swaps always go **mainnet → testnet**. You spend a real asset; recipients
get test tokens. There is no reverse.

**You choose the TO amount; the API prices the FROM side.** You say "recipient X should get
`1.5` testnet ETH" (as base units); the API tells you exactly how much mainnet token that costs
(`fromTotal`). You pay that — exactly that.

**What you pay.** The testnet tokens have a listed USD rate ([`GET /api/quotes`](https://docs.drip.tools/api/discovery.md#get-api-quotes-rates-liquidity));
your cost is that rate converted at the live Chainlink price of the token you pay with. There is
no additional fee or spread. Gas on the FROM chain is yours; gas for the testnet payouts is ours.

**One payment, many recipients.** Whether you have one recipient or thousands, you make a single
payment. All recipients and amounts are in the signed quote, and the backend fans out the
deliveries. Minimum order value is **$1** for a single recipient and **$5** for a multisend.

**Two payment models, one API.** On the ten EVM FROM chains you call the depository contract. On
Solana and TON there is no contract: you transfer to the treasury with the `quoteId` in the memo
(Solana) or the text comment (TON). Quote and tracking calls are identical — only the payment
transaction differs. See [Paying from Solana & TON](https://docs.drip.tools/swap/memo.md).

**The chain only sees the payment.** It records that `payer` paid `fromAmount` for `quoteId`;
the backend matches that against the quote (same payer, same token, same amount, before the
deadline) before delivering. That is why the on-chain part is tiny and identical for single and
batch swaps — and why you must pay exactly what was quoted. See
[Payment rules](https://docs.drip.tools/reference/lifecycle.md#payment-rules).

## Orders

Every recipient becomes one **order**: `processing` while the payout is queued, then
`completed` (with the payout transaction in `to.txHash`) or `failed`. A multisend collapses into
one aggregate status — `processing`, `completed`, `failed` or `partial` — and failed slices are
refunded. See [Order lifecycle & refunds](https://docs.drip.tools/reference/lifecycle.md).

> **Tip: Where to pay**
>
> Always read `contracts.depository` from [`GET /api/chains`](https://docs.drip.tools/api/discovery.md) for your FROM chain
> at runtime. On an EVM chain it is the depository contract; on Solana and TON it is the treasury
> account. If it is absent, programmatic swaps aren't enabled on that chain.

## Next steps

- **[At a glance](https://docs.drip.tools/guide/cheatsheet.md)** — the whole API on one screen.
- **[Quick Start](https://docs.drip.tools/guide/quickstart.md)** — a minimal end-to-end script in JavaScript or Python.
- **[Examples](https://docs.drip.tools/swap/examples.md)** — every payment variant, ready to run.
- **[Swap flow](https://docs.drip.tools/swap/flow.md)** — the four steps in detail.
- **[API reference](https://docs.drip.tools/api/discovery.md)** and **[Errors](https://docs.drip.tools/reference/errors.md)**.