GUIDE

Getting started

Install the API, take your first payment, and collect the money — in six steps. No crypto experience needed.

What you need

  • A Linux or macOS machine (Windows works too, with minor path differences)
  • Python 3.9+
  • An internet connection — the API queries BlockCypher to watch addresses
  • Somewhere to receive coins (a wallet like Electrum, Exodus, or an exchange account) — for step 6
How it works, in one paragraph
You ask the API for an order. It creates a brand-new wallet address and gives it to you. Your customer sends coins to that address. The API watches the blockchain, and when the coins arrive with enough confirmations, the order flips to paid. You then export the private key and move the coins to your own wallet.

Step 1 — Install

Get the code and install its dependencies:

bash 
cd payment-api
pip install -r requirements.txt

If you use a virtual environment (recommended), activate it before running the commands above:

bash 
python -m venv venv
source venv/bin/activate   # on Windows: venv\Scripts\activate
Dependency gotcha
python-dotenv must be installed, or the API will not read your .env file and will exit with "SECRET_KEY and API_TOKEN are required". Installing requirements.txt covers it.

Step 2 — Configure

Copy the example config and open it in an editor:

bash 
cp .env.example .env
nano .env   # or any editor

Two values are required. Generate a secret key, and pick any long random string as your API token:

bash 
python -c "import secrets; print(secrets.token_hex(32))"

Paste the output into SECRET_KEY in .env. Set API_TOKEN to any string you will remember — you send it with every request:

bash 
SECRET_KEY=your-generated-64-char-hex
API_TOKEN=choose-a-long-random-string
What these do
SECRET_KEY encrypts private keys in the database — losing it means losing access to funds received. API_TOKEN is your password for the API; anyone with it can read orders and export keys.

Everything else is optional. The defaults are fine to start.

Step 3 — Run it

bash 
python app.py

You should see:

bash 
[api] listening on http://127.0.0.1:8000 (BTC conf 3, LTC conf 1)

The API is now running on your machine, on port 8000. Leave this terminal open. Verify it is healthy in another terminal:

bash 
curl http://127.0.0.1:8000/health
# {"ok": true, "uptime": 3.5}

See Deployment to run it in the background permanently instead of in a terminal.

Step 4 — Create your first order

An order is one payment request. Create one with curl:

bash 
curl -X POST http://127.0.0.1:8000/orders \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"coin": "LTC", "amount": 5.0, "label": "order-42"}'

Replace YOUR_API_TOKEN with the token you set in step 2. The response is the order:

json 
{
  "id": "467d856742701c47",
  "coin": "LTC",
  "address": "Lg1vJdAcwCNqCGUafpaLSAhSLSZ6aGm2GH",
  "amount": 5.0,
  "status": "pending",
  ...
}
This is what your customer sees
The address is what you show the customer. It is a normal LTC (or BTC) address — they pay it from any wallet, exactly like paying a friend. The id is your internal handle for tracking this order.

Step 5 — Watch the payment arrive

Send a small test payment from your own wallet to the order's address (e.g. 5 LTC). The API polls the blockchain every 30 seconds. Check the order status:

bash 
curl http://127.0.0.1:8000/orders/467d856742701c47 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Statuses, in order:

  • pending — waiting for coins
  • — coins received with enough confirmations — ship the goods!
  • underpaid — coins arrived but less than the amount

In your app, poll GET /orders/{id} on a timer (say every 10 seconds) and act when status becomes paid.

Why confirmations matter
A transaction is "confirmed" when miners include it in a block. One confirmation means the coins are almost certainly yours; more confirmations make double-spends effectively impossible. Defaults: 3 for BTC, 1 for LTC. Configurable in .env.

Step 6 — Collect the funds

Coins received sit in the order's wallet. To move them to your own wallet, export the private key:

bash 
curl http://127.0.0.1:8000/orders/467d856742701c47/secret \
  -H "Authorization: Bearer YOUR_API_TOKEN"
json 
{
  "mnemonic": "rack judge lounge ripple great spider kitten miss width unusual senior world",
  "private_key_wif": "T3RkJzgbX5f5re3efqfbfsG7gSto4QhNsJL6ZfGGQbmmu3J4cy6C"
}

In your wallet app (Electrum, Exodus, ...), use "import private key" / "sweep wallet" and paste the private_key_wif — or restore from the mnemonic phrase. The coins move to your wallet. The order wallet is now empty; the order can be discarded.

Handle with care
Anyone who gets this key can take the coins. Export it only when you are about to sweep. Keep it off chat logs and screenshots.

Next steps