ucash CLI

Create U.CASH Pay checkouts from the terminal. Crypto + cards. Non-custodial.

ucash is a tiny zero-dependency Node CLI that builds U.CASH Pay checkout links straight from your shell. Funds always settle to the addresses you configure in your pay.u.cash account. No custodial balance is ever held by the CLI.

• Zero runtime dependencies (Node built-ins only: fetch, URLSearchParams).
• Publishable, browser-safe Store Cloud Token. No server secret required.
• Two modes:
  • Hosted link (default): builds the embed.php checkout URL.
  • Tracked checkout (--tracked): POSTs an idempotent create-transaction and returns the payment URL plus transaction id.

Install

Requires Node 18+ (for global fetch).

npm install -g @ucash/cli

Or run once without installing:

npx @ucash/cli pay 25 --cloud st_xxx --title "Pro plan"

Homebrew (community tap, once published):

brew install udotcash/tap/ucash

Publish (for maintainers)

npm version patch && npm publish

Usage

ucash pay <amount> [currency] [options]

| Option | Description | | --------------------- | --------------------------------------------------------------------------- | | --title <t> | Title shown on the checkout page. | | --external-ref <r> | Your order/reference id. Idempotency key when using --tracked. | | --redirect <url> | URL to send the customer to after payment. | | --cloud <token> | Store Cloud Token. Falls back to UCASH_CLOUD. | | --tracked | POST create-transaction server-side (idempotent) and return the live URL. | | --json | Print only the URL (machine-readable). | | --help, -h | Show help. | | --version, -v | Print the version. |

Examples

Publishable hosted link (default, safe to open anywhere):

ucash pay 25 --cloud st_xxx --title "Pro plan"
# https://pay.u.cash/embed.php?cloud=st_xxx&amount=25&currency=USD&title=Pro+plan

Crypto amount with a custom currency:

ucash pay 0.01 BTC --cloud st_xxx --external-ref order_123 --redirect https://shop.example/thanks

Tracked, idempotent checkout created server-side:

ucash pay 49.99 --cloud st_xxx --external-ref order_123 --tracked
# U.CASH Pay checkout:
#   https://pay.u.cash/...
#   Transaction ID: 123456

Set the cloud token once for the session instead of passing --cloud:

export UCASH_CLOUD=st_xxx
ucash pay 10 --title "Test"

How it works

The Store Cloud Token is publishable: the same value is embedded in your public checkout page in the browser, so it is safe to ship in this CLI, a mobile app, or any client. It can only create checkouts that pay to your own receive addresses. It cannot move funds or read balances.

Hosted link mode (default)

Builds a GET URL against the U.CASH Pay hosted checkout:

GET https://pay.u.cash/embed.php?cloud=<token>&amount=<amount>&currency=<currency>&title=<t>&external_reference=<r>&redirect=<url>

Tracked mode (--tracked)

POSTs an idempotent transaction to the U.CASH Pay ajax endpoint and returns the live payment URL. Idempotency is keyed on external_reference, so re-running with the same reference returns the same checkout instead of creating a duplicate.

POST https://pay.u.cash/payment/ajax.php
content-type: application/x-www-form-urlencoded
body: function=create-transaction&amount=<amount>&currency_code=<currency>&cryptocurrency_code=&external_reference=<r>&title=<t>&redirect=<url>&cloud=<token>&idempotent=1

The response is JSON { success: true, response: [...] }; the payment URL is the array element starting with http(s)://.

Set up your pay.u.cash account

1. Sign up at pay.u.cash, then click the verification link in the email.
2. Set receive addresses under Settings -> Addresses (raw address, ENS, Unstoppable Domains, or FIO).
3. Create a store under Account -> Stores and copy its Store Cloud Token (use the store-level token, not the account-wide one).
4. For fiat cards, connect your own Stripe under Settings -> Payment processors.

Non-custodial note

This CLI never takes custody of funds. It only creates checkout links. All funds settle directly to the addresses you configured in your pay.u.cash account. The Store Cloud Token is intentionally publishable and safe to embed in client code.

License

MIT. See LICENSE.