API

Tell us when someone did the thing. That’s the whole integration — one call, from the code that already knows it happened.

1. Get a key

Send it as a bearer token from your server. Keys starting sk_test_ only touch private tests and are never invoiced; sk_live_spends real budget. A test key is refused on a live Rewarded Action and vice versa, so a test harness left running can’t bill you.

You’ll get keys with your account. Sign in.

2. Install

npm install @mintfall/node

3. Capture

Wherever your backend already knows the event happened — the signup handler, the upgrade webhook, the feature flag that just flipped.

import { Mintfall } from "@mintfall/node";

export const mintfall = new Mintfall({
  key: process.env.MINTFALL_KEY!,       // sk_test_… while you build
  action: "ra_1a2b3c",
});

// then, wherever it already happens. "connect_repo" is the requirement's slug,
// not its category — pass the plain email and we hash it before it leaves you.
await mintfall.capture("connect_repo", { email: user.email });

That’s it. We match the call to a participant, tick the requirement, and pay them the moment the set is complete. Retry as much as you like: the same event reported twice is a no-op, enforced by a uniqueness constraint rather than by you remembering an idempotency key.

Everything else

Open one when you need it. None of it is required to get the three steps above working.

Same ergonomics from a component. The hook posts to your app, not to us — one route handler you paste in forwards it with the secret key.

npm install @mintfall/react

import { MintfallProvider, useMintfall } from "@mintfall/react";

// once, near the root — no key here, just where to post
<MintfallProvider endpoint="/api/mintfall">
  <App />
</MintfallProvider>;

// anywhere below it
function UpgradeButton() {
  const mintfall = useMintfall();
  return (
    <button onClick={() => mintfall?.capture("connect_repo")}>
      Upgrade
    </button>
  );
}

The route handler it posts to, once:

// app/api/mintfall/route.ts
import { Mintfall } from "@mintfall/node";
import { auth } from "@/lib/your-auth";

const mintfall = new Mintfall({
  key: process.env.MINTFALL_KEY!,
  action: "ra_1a2b3c",
});

export async function POST(request: Request) {
  // The slug the browser named. It is the only thing the browser gets to say.
  const { event } = await request.json();
  // You already know who this is — that's the point of forwarding through here.
  const user = await auth();
  if (!user) return new Response(null, { status: 401 });

  await mintfall.capture(event, { email: user.email });
  return Response.json({ ok: true });
}

The indirection is not ceremony. A browser holding a key that mints payouts is money anyone can print — so the client tells your server, and your server, which already knows who is signed in, tells us. That is also why there is no <script>tag version and won’t be.