# Quickstart: top up the balance by API (card, Stripe Checkout)

Last verified: 2026-10-28. Base URL `https://api.proxies.sx/v1`, header `X-API-Key: psx_...` with the `billing:topup` scope (opt-in; tick it when creating the key at https://client.proxies.sx/account). The amount needs the user's approval before step 1, and a HUMAN pays the Checkout page: this is never headless. Per-key daily cap `spendCapUsdPerDay`, default 100 USD, reset 00:00 UTC; a human raises it with `PUT /v1/api-keys/<id> {"spendCapUsdPerDay": 500}` from a dashboard session. Crypto instead: `POST /v1/coingate/create-order` (hosted checkout, JWT or key).

1. **Create the Checkout link** (whole USD, at least 1).
   ```bash
   curl -s -X POST https://api.proxies.sx/v1/stripe/create-balance-checkout -H "X-API-Key: $KEY" \
     -H 'Content-Type: application/json' -d '{"amount": 20}'
   # -> 201 {"url":"https://checkout.stripe.com/c/pay/cs_...","sessionId":"cs_..."}
   ```
   Verify: 201 with `url` and `sessionId`. 403 `scope_missing` = the key lacks `billing:topup`; 403 `spend_cap_reached` = wait for 00:00 UTC or raise the cap; 400 `invalid_amount` = send a whole number of USD, at least 1; 401 = the key path is not enabled on this deployment yet, so use the dashboard https://client.proxies.sx/billing.
2. **Hand the `url` to the user.** They open it in a browser and pay by card. Stripe returns them to https://agents.proxies.sx/topup/done/?checkout_session=cs_... (or your `successUrl` on a proxies.sx site).
3. **Poll the receipt** every ~10 s for up to ~15 min.
   ```bash
   curl -s https://api.proxies.sx/v1/stripe/balance-checkout/cs_.../receipt -H "X-API-Key: $KEY"
   # -> {"credited":false}                      while the user is still paying
   # -> {"credited":true,"payment_receipt":{...}} once paid AND credited (sessions younger than 24 h)
   ```
   Verify: `credited` is `true`. The webhook credits each session exactly once, so polling never double-credits.
4. **Read the balance.**
   ```bash
   curl -s https://api.proxies.sx/v1/account/summary -H "X-API-Key: $KEY" | jq '.balance'
   ```
   Verify: the balance rose by the amount. Then buy GB (https://agents.proxies.sx/quickstart/buy-gb.md, dashboard step) or rent a modem (https://agents.proxies.sx/quickstart/buy-modem.md).