--- name: buy-cycles description: "Buy cycles with a credit card for the CLI's own identity with `icp cycles buy`, through CyclePay's on-chain gateway, then continue deploying. Use when a mainnet deploy or canister creation fails for lack of cycles, the user has no ICP, no wallet or no exchange account, or asks to pay for cycles by card, Stripe, fiat or USD. Do NOT use for converting ICP you already hold (cycles-management: `icp cycles mint`), for topping up a canister from an existing balance, or for Internet Identity sign-in (agent-web-identity)." license: Apache-2.0 compatibility: "icp-cli with `icp cycles buy` (dfinity/icp-cli#815; `icp cycles --help` lists `buy`), or any icp-cli >= 1.0 for the `icp canister call` fallback. Mainnet (`-n ic`). A human with a browser on any device to pay." metadata: title: Buy Cycles With a Card category: Infrastructure summary: "Buy cycles with a credit card when you have no ICP to pay for deployment." keywords: "credit card, fiat, USD, Stripe, CyclePay, pay for cycles, purchase cycles, out of cycles, no ICP, icp cycles buy, funding" --- # Buy Cycles With a Card ## What This Is A cycles gateway is a canister that takes an order for cycles, has the buyer pay for it by card on a hosted Stripe page, and delivers the cycles on-chain. `icp cycles buy` makes the **CLI identity the buyer**: the identity that will run `icp deploy` creates the order itself, so the cycles land on that identity's own cycles-ledger account and nothing has to be linked, signed in or transferred afterwards. The agent's job is to create the order, hand the payment link to the human, wait for delivery, and carry on deploying. The default gateway is [CyclePay](https://www.cyclepay.org), run by the DFINITY Foundation: backend canister `2bwus-iiaaa-aaaac-bee3a-cai`, **mainnet only**, USD only. Everything the command quotes with is read from the gateway at run time (`get_card_terms`, `get_xdr_rate_status`): the per-order range (USD 1 to 200 at the time of writing), the card fee (2.9 % + 0.30 USD), the cycles-ledger delivery fee (200 M cycles) and the USD per XDR rate (1 XDR = 1 T cycles). Do not hardcode any of them. Card details never touch the canister or the CLI. ## Prerequisites - `icp` CLI installed (https://cli.internetcomputer.org); load the `icp-cli` skill for general usage and the `-n` / `-e` flag rule. `icp cycles --help` must list `buy`; otherwise use the fallback below. - A **named** `icp` identity for the project. The anonymous identity is refused, and the identity that buys must be the one that deploys. - A human who can open a URL on **some** device (laptop, phone). The agent's machine needs no browser. ## The Flow ```bash # 1. Who is buying, and what they hold now icp identity principal --identity "$ID" icp cycles balance -n ic --identity "$ID" # 2. Buy (spend 10 USD; or `--cycles 5t` to pay the least that buys 5 T cycles -- for a deploy, # the gap from the `icp-cli` skill's pre-deploy estimate, N canisters × (2T + 100M) − balance) icp cycles buy --amount 10 -n ic --identity "$ID" --no-open --yes --json # stdout, line 1, as soon as the order exists: # {"order_id":"co-12-…","checkout_url":"https://buy.stripe.com/…","amount":{"currency":"USD","value":"10.00"}, # "net":{"currency":"USD","value":"9.41"},"fee":{"currency":"USD","value":"0.59"}, # "estimated_cycles":"6959859171597","expires_at":"2026-10-15T18:03:12Z"} # → show checkout_url to the user VERBATIM and ask them to pay on it (any device). # The command polls every 3 s for up to an hour, then prints line 2 and exits 0 only on delivery: # {"order_id":"co-12-…","status":"delivered","cycles_delivered":"6938000000000", # "paid":{"currency":"USD","value":"10.00"},"refunded":null,"detail":null,"balance":"6938000000000"} # 3. Continue as the same identity icp cycles balance -n ic --identity "$ID" icp deploy -e ic --identity "$ID" ``` Without `--yes` the command shows the quote and asks for confirmation, which needs a terminal; without one it prints the quote and refuses (`Use --yes to proceed`), creating nothing — a usable dry run when the user wants to see the figures first: ``` Identity: dev Buyer: 7k7px-dcypq-wulnh-byzgd-6sib2-udn6c-lfo6e-6oujd-veifp-62woo-5ae Gateway: 2bwus-iiaaa-aaaac-bee3a-cai (CyclePay) Price: 10.00 USD (9.41 USD after a 0.59 USD card fee) Estimate: about 6.959T cycles, at 1.3520 USD per 1T cycles ``` Flags that matter to an agent: `--no-open` (never let the CLI try a browser), `--json` (two objects on stdout, one per line, never an array; progress and prompts go to stderr), `-q` (stdout is the link, then the final status tag), `--no-wait` (print the link and return; the order needs nothing more from the CLI), `--gateway ` / `ICP_CYCLES_GATEWAY_CANISTER_ID` (another canister serving the same interface, on any network). ### Fallback: the same order with `icp canister call` Only when the installed CLI has no `cycles buy`. Same canister, same identity rules. The argument and reply shapes are those of [`cycles_gateway.did`](https://github.com/dfinity/icp-cli/blob/main/crates/icp-cli/src/cyclepay/cycles_gateway.did), which icp-cli holds against CyclePay's backend interface; this sequence was run against icp-cli's stand-in gateway and mainnet's public queries on 2026-10-14. ```bash GW=2bwus-iiaaa-aaaac-bee3a-cai icp canister call "$GW" get_card_terms '()' -n ic --query # deliveries_paused, min/max_order_usd_cents, fee_bps, fee_fixed_usd_cents, ledger_delivery_fee_cycles icp canister call "$GW" get_xdr_rate_status '()' -n ic --query # xdr_usd_x10000, stale # Create: USD cents, destination = the caller's own cycles-ledger account. icp canister call "$GW" create_order \ '(record { destination = variant { Ledger }; beneficiary = null; project_id = null; amount_usd_cents = 1000 : nat64; confirm_system_canister = null })' \ -n ic --identity "$ID" # Ok = record { order_id = "co-…"; payment_url = "https://…"; net_usd_cents; expires_at } # Err = record { code = "AMOUNT_OUT_OF_RANGE"; message = "…" } (nothing was created) # Wait: poll until the status is Delivered, or one of the end states in Pitfall 6. icp canister call "$GW" order_status '("'"$ORDER_ID"'")' -n ic --query --identity "$ID" \ | grep -oE 'status = variant \{ [A-Za-z]+' ``` To extract the link from the Candid text, take the quoted string after `payment_url =` **unchanged**: `grep -oE 'payment_url = "[^"]+"' | sed -E 's/.*"(.*)"/\1/'` (Pitfall 2). Cycles to expect, before the ledger fee: `net_usd_cents / 100 / (xdr_usd_x10000 / 10000)` trillion, where `net = amount − (amount × fee_bps / 10000 + fee_fixed_usd_cents)`, rounded to the cent. ## Common Pitfalls 1. **The cycles go to the buyer's own cycles-ledger account, nowhere else.** The CLI has no "send to my canister" option. From there, `icp deploy -e ic` creates canisters out of the balance and `icp canister top-up --amount -e ic` funds one. `icp cycles transfer` to a canister principal credits that principal's *ledger* balance, not the canister's execution balance (see `cycles-management`). 2. **Never "clean up" the Candid text a link arrives in.** Candid prints numbers with underscore separators (`6_938_000_000_000`), and a regex that strips underscores turns `client_reference_id=o_co-12-…` into a link to the wrong order. Prefer `--json`; in the fallback, extract the quoted URL exactly and strip underscores only from values that are all digits. 3. **The agent cannot pay, and usually cannot open a browser.** Print the link and ask the human to open it; they may use another device. Never ask for or type card details. `--yes` is fine for an amount the user asked for: creating an order charges nothing, and the human sees the price again on the payment page before paying. 4. **`-n ic` is required, `-e ic` is not accepted here.** CyclePay sells on mainnet only. Run outside a project or against a local network and the command fails with `this network is not mainnet` or `is not running`, each ending in ``CyclePay sells cycles on mainnet: use `-n ic` ``. The deploy that follows takes `-e ic` as usual (`icp-cli` Pitfall 2). 5. **Buy and deploy as the same, named identity.** The command refuses the anonymous identity, and `icp deploy` spends the *default* identity's balance unless `--identity` is passed. A purchase as one identity and a deploy as another fails with insufficient cycles while the balance sits one identity over. Pass `--identity "$ID"` everywhere, or check `icp identity default` first. 6. **Stopping the command does not stop the order, and there is no resume.** Ctrl-C (or a killed process) leaves the order payable; once paid, the cycles land anyway and `icp cycles balance -n ic` shows them. Do not create a second order for the same purchase; the gateway caps open orders per principal (`TOO_MANY_OPEN_ORDERS`). To watch the first one again, poll `order_status` as in the fallback. An unpaid order expires (the `expires_at` in the JSON, about a day) with nothing charged; start a new one then. 7. **Read the final status before deciding anything.** The command exits 0 only for `delivered`; the JSON `status` (or the human message) says why otherwise: - `processing` / `payment_pending`: the card was charged and delivery is under way. Keep waiting or poll; never re-order. - `needs_review`: charged, and a CyclePay operator settles it by hand. Report the order id and the charge to the user and stop. - `refunding` / `refunded`: not delivered, the money comes back (`refunded` says how much). A new order is fine once the user agrees. - `refund_owed`: not delivered, an operator refunds by hand. Keep the order id. - `unknown` (`--json`) / "a state this version of icp does not know": a status newer than the CLI; poll `order_status` to read it. 8. **The quote is an estimate; delivery is net of a ledger fee.** The cycles are minted at the rate in force when the payment lands, so `cycles_delivered` can differ slightly from `estimated_cycles`, and the gateway's `ledger_delivery_fee_cycles` (200 M) comes off a ledger delivery. That is not a short delivery. A stale-rate warning on stderr means CyclePay has not refreshed its rate for longer than it tolerates; tell the user before they pay. With `--cycles N` the command pays the smallest amount, to the cent, that buys at least `N` at the quoted rate. 9. **A refusal is `CyclePay refused the order: : `, and nothing was created.** `AMOUNT_OUT_OF_RANGE`: the terms set the range (USD 1 to 200), pick an amount in it. `CARDS_UNAVAILABLE` / `PAUSED`: the gateway is not taking card orders, try later. `RATE_LIMITED` / `TOO_MANY_OPEN_ORDERS`: wait, or pay the open order (Pitfall 6). Do not loop on any of them. 10. **`failed to read the card terms`** means the canister does not serve the gateway interface: a `--gateway` that is not a cycles gateway, or an old CyclePay deployment. Check the canister id; do not fall back to guessing a Payment Link. ## Verify It Works ```bash icp cycles balance -n ic --identity "$ID" # ≈ estimated_cycles − 200_000_000 after a first purchase icp canister call 2bwus-iiaaa-aaaac-bee3a-cai order_status '("'"$ORDER_ID"'")' -n ic --query --identity "$ID" \ | grep -E 'status|cycles_delivered|paid_usd_cents' # status = variant { Delivered }; cycles_delivered = opt (6_938_000_000_000 : nat64) ``` `order_status` answers only the identity that created the order (`null` for anyone else, and for an unpaid order after it expired). Purchases also appear under "My purchases" on www.cyclepay.org when the user signs in there with the same identity: `icp identity link web cyclepay --app 4w3yu-fyaaa-aaaac-beeoa-cai.icp0.io` makes one. ## Security Rules for Agents - Create orders only for an amount the user named, as the identity they will deploy with, and relay the `amount`, `fee` and `estimated_cycles` the command prints. - Hand over the payment link and stop. Do not attempt to automate the payment page. - Never collect, store or echo card details; the hosted Stripe page is the only place they are entered. - Treat the order id as a reference, not a secret: it travels in the payment link. - When a purchase ends in `needs_review` or `refund_owed`, report the order id and the charge to the user and do not retry.