farcaster-ucashpay

A Farcaster Frame that lets users pay with U.CASH Pay (crypto + cards). Non-custodial.

When a user opens the frame and taps the button, they are sent to a U.CASH Pay checkout where they can pay with crypto (BTC, ETH, USDC, and many more) or a fiat card. Funds settle directly to your own receive addresses. The frame itself never holds funds or private keys.

How it works

1. A cast embeds this frame (the deployed https://YOUR_HOST/ URL).
2. Farcaster renders the frame image and the Pay with U.CASH button.
3. Tapping the button POSTs to / (the frame post_url).
4. The server builds a U.CASH Pay embed link from your publishable Store Cloud Token and returns a frame whose button opens that checkout (fc:frame:button:1:action = link).
5. The user completes payment on pay.u.cash. Funds go to your configured receive addresses.

The store Cloud Token is publishable (designed to be used straight from the browser), so no server secret is required. This is non-custodial: the frame only constructs a link, it never moves funds.

Files

• index.js - Express app that serves the frame (GET /) and the button handler (POST /).
• package.json - npm manifest, depends only on express.
• .env.example - all supported environment variables.

Usage

1. Clone and install:

   git clone https://github.com/UdotCASH/farcaster-ucashpay.git
   cd farcaster-ucashpay
   npm install

2. Copy the env template and fill in your details:

   cp .env.example .env

   At minimum set CLOUD_TOKEN (your U.CASH Pay Store Cloud Token). Then set AMOUNT, CURRENCY, and TITLE.

3. Run locally:

   npm start
   # listening on http://localhost:3000

4. For Farcaster to render the frame, the server must be reachable over HTTPS at a public URL. Use a tunnel for local testing (e.g. cloudflared, ngrok) or deploy to a host (see below).

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.

Configuration

Variable	Required	Default	Description
CLOUD_TOKEN	yes		U.CASH Pay store Cloud Token (publishable).
AMOUNT	no	1	Payment amount.
CURRENCY	no	USD	ISO currency code.
TITLE	no	Pay with U.CASH	Payment title shown on the checkout.
EXTERNAL_REF	no	random id	External reference used for idempotent tracking.
REDIRECT_URL	no		URL to redirect to after payment.
FRAME_IMAGE_URL	no	/frame-image.png	Public 1.91:1 image used as the frame image.
PORT	no	3000	Port the server listens on.

Deploying

Any host that runs Node 18+ and serves HTTPS works. Examples:

Render / Railway / Fly.io

1. Create a new service from this repo.
2. Set the environment variables (CLOUD_TOKEN etc.) in the host dashboard.
3. Build command: npm install. Start command: npm start.
4. The host gives you a public HTTPS URL (e.g. https://farcaster-ucashpay.onrender.com).

Vercel / Netlify (serverless)

This Express app runs on Node hosts. For a pure serverless deploy, port index.js into a serverless function that returns the same frame HTML. The logic in GET / and POST / is the contract to preserve.

Self-host

1. Point a domain (with HTTPS, e.g. via Caddy or nginx + Let's Encrypt) at the Node process.

2. Run it behind a process manager (pm2, systemd):

   npm install --omit=dev
   CLOUD_TOKEN=st_xxx AMOUNT=5 CURRENCY=USD npm start

Add the frame to a cast

Once your frame is live at https://YOUR_HOST/:

1. Open a Farcaster client (e.g. Warpcast).
2. Compose a new cast and paste https://YOUR_HOST/ into the body.
3. The client fetches the page, reads the fc:frame meta tags, and renders the frame preview with the Pay with U.CASH button.
4. Publish the cast. Anyone who sees it can tap the button and pay.

You can also validate the frame first with the Farcaster Frame playground or the open-source frame validators.

API contract

This frame uses two U.CASH Pay entry points:

Client-side hosted pay link (publishable cloud token, usable straight from the browser, no server secret):

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

Server-side tracked checkout (call from a server route; idempotent per external_reference):

POST https://pay.u.cash/payment/ajax.php
Content-Type: application/x-www-form-urlencoded

  function=create-transaction
  &amount=<amount>
  &currency_code=<USD>
  &cryptocurrency_code=
  &external_reference=<ref>
  &title=<title>
  &redirect=<url>
  &cloud=<store cloud token>
  &idempotent=1

Response JSON { success: true, response: [paymentUrl, transactionId, ...] }. The payment URL is the array element that starts with http(s)://.

POST / tries the server-side checkout first (for tracking) and falls back to the plain embed link if it fails, so the frame keeps working even if the AJAX route is unavailable.

Limitations

• The frame creates a single payment for a fixed AMOUNT per server configuration. Dynamic per-user amounts would require the external_reference and amount to be derived per request (not implemented here to keep the frame stateless).
• Automatic recurring crypto billing is not supported by U.CASH Pay. Fiat recurring billing via your own Stripe is outside this frame's scope.
• The frame image is served at /frame-image.png if FRAME_IMAGE_URL is unset. Provide your own 1.91:1 image for best results.

License

MIT. See LICENSE.