Undertow Tide Sign in Start billing

Developer guide

Bill your users in USDC every month without holding their money or your own keys on a server. Most apps need three things from this page: a link, one signature check and one request.

Start here

Sign in with your wallet and publish a plan: a name, a price and a billing period. You get a checkout link. Payments go from your customer's wallet straight to the wallet you signed in with; we trigger each renewal and never hold the funds.

Everything below uses two values from the dashboard: the plan's address (Plans) and your signing secret (Settings).

Send customers to checkout

Link to the plan's checkout page. Add ref with your own identifier for the person, such as a user id, so you can recognise them when they come back.

https://tide.undertow.sh/pay/PLAN_ADDRESS?ref=user-8841

The customer connects a wallet, approves, and the first payment is collected within seconds. They can also choose how to hear about a failed payment: a browser notification, Telegram or email.

Bring them back, signed

Give the plan a return address (New plan, or "Add it to your site or app" on the plan). Straight after a customer subscribes we send them there with these values added:

plan
The plan's address.
wallet
The wallet that subscribed.
ref
What you put on the checkout link. Left out if you gave none.
ts
When we signed it, in seconds.
sig
Hex HMAC-SHA256 of ts.plan.wallet.ref under your signing secret, with an empty ref when there was none.

Check the signature on your server before you believe any of it. It is only made at the moment the wallet has signed the subscription, so a valid one means: this wallet just subscribed, and it was the person you sent with this ref.

import { createHmac, timingSafeEqual } from 'node:crypto';

// Returns { plan, wallet, ref } or null. `url` is the address the customer arrived on.
export function verifiedReturn(url, signingSecret) {
  const query = new URL(url).searchParams;
  const [plan, wallet, ref, ts, sig] = ['plan', 'wallet', 'ref', 'ts', 'sig'].map((name) => query.get(name));
  if (!plan || !wallet || !ts || !/^[0-9a-f]{64}$/.test(sig ?? '')) return null;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 600) return null; // older than ten minutes
  const expected = createHmac('sha256', signingSecret).update(`${ts}.${plan}.${wallet}.${ref ?? ''}`).digest();
  return timingSafeEqual(expected, Buffer.from(sig, 'hex')) ? { plan, wallet, ref } : null;
}

A customer who returns to the checkout page later sees a "Continue" button to the same address. That visit carries no ts or sig, because nothing was signed: treat it as an ordinary visit and ask them to sign in.

Check access

Ask whether a wallet may use your service right now. No key is needed, and browsers may call it directly.

curl https://tide.undertow.sh/api/public/access/PLAN_ADDRESS/WALLET
hasAccess
The answer. True while paid, and during your grace period after a failed payment.
standing
paid, due, grace, past_due, ended, or none for a wallet that never subscribed.
state
active, cancelling (cancelled, paid period still running) or expired.
periodEndsAt
End of the paid period, in seconds.
graceEndsAt
When access stops if the failed payment is not made good.

This tells you about a wallet, and wallet addresses are public. Make sure the person in front of you controls that wallet: have them sign in with it, or tie it to their account once through the signed return above.

Webhooks

Enter an address under Settings and we send each billing event to it as a JSON POST.

{ "id": "notice:412", "type": "payment.failed", "created": 1794862271,
  "data": { "plan": "…", "subscriber": "…", "account": "…", "amount": "9990000", … } }

Event types: subscription.created, subscription.cancelled, subscription.resumed, subscription.billing_stopped, payment.collected, payment.failed, payment.past_due, payment.recovered, plan.created, plan.updated, plan.deleted. Amounts are strings in the token's smallest unit (six decimals for USDC).

Each request carries x-undertow-event-id and x-undertow-signature: t=TIMESTAMP,v1=HEX, where the hex is the HMAC-SHA256 of TIMESTAMP.BODY under your signing secret. Verify it against the raw body, and refuse timestamps more than five minutes old.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifiedWebhook(header, rawBody, signingSecret) {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? '');
  if (!match || Math.abs(Date.now() / 1000 - Number(match[1])) > 300) return false;
  const expected = createHmac('sha256', signingSecret).update(`${match[1]}.${rawBody}`).digest();
  return timingSafeEqual(expected, Buffer.from(match[2], 'hex'));
}

Answer with any 2xx status. Otherwise we try again after 10 seconds, 1 minute, 5 minutes, 30 minutes and 2 hours, in order, then give up on that event. The same event can arrive twice: use the id to ignore repeats.

API keys

Create a key under Settings and send it as a Bearer token. A key can do what you can do in the dashboard, except manage keys.

curl -H "Authorization: Bearer ut_…" https://tide.undertow.sh/api/overview
GET /api/overview
Plans, subscribers with their standing, payments and totals.
GET /api/plans/PLAN
One plan: subscribers, payment attempts, messages sent.
PUT /api/plans/PLAN
Change the return address: {"returnUrl": "https://…"}, or null to remove it.
POST /api/subscribers/stop
Stop billing one customer: {"plan": "…", "subscriber": "…"}. They keep what they paid for and are told.
POST /api/subscribers/resume
Start billing them again.
POST /api/plans/prepare
Start a new plan: name, amount, periodHours, optional description and returnUrl. Returns a transaction for your wallet to sign; send it to /api/plans/confirm.

Anything that changes a plan on Solana comes back as an unsigned transaction. Your wallet signs it; a key alone cannot publish, close or delete a plan.

What we cannot do

These are limits of billing on chain, and worth knowing before you build around them.

  • We cannot move money anywhere but your wallet. A plan names your wallet as its only destination.
  • A plan's price and period are fixed. To change them, publish a new plan and close the old one.
  • You cannot cancel a customer's subscription for them. You can stop billing them; only their wallet can close it.
  • Closing a plan takes one billing period. The program gives subscribers that much notice.
  • A payment fails if the wallet is short. We tell the customer and you, retry on your schedule, and keep access open for your grace period.