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.refunder your signing secret, with an emptyrefwhen 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, ornonefor a wallet that never subscribed.- state
active,cancelling(cancelled, paid period still running) orexpired.- 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://…"}, ornullto 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, optionaldescriptionandreturnUrl. 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.