Yoinx! product button
Drop a button on any product page. Shoppers open a multiplayer prize table for that SKU — attributed to your business, playable on Yoinx.
What it is
The Yoinx! button is a business embed for product pages — fashion shops, Gamerholic merch, custom Next apps, or any storefront. When a shopper clicks it, Yoinx creates a live physical item table for that SKU. Tables store your business id; the clicker’s Internet Identity is the creator principal. Winners claim the real product through your fulfillment flow.
You never put a private API secret on a static site. A publishable site key (yx_pk_…) maps to your business server-side, with an optional Origin allowlist.
Business
Owns the product & embed keys. Games get games.business_id.
Site key
Publishable yx_pk_… sent as X-Yoinx-Site-Key header.
Player
Connects II, taps Yoinx!, plays the prize table.
How it works
01
Register a business
Profile → Businesses → Add business. One principal can own many shops.
02
Generate a site key
On this page (or Profile → Yoinx! button), create a publishable key for that business.
03
Allow shop origins
List exact Origins (https://your-shop.com). Empty = open (dev only).
04
Wire your product site
Env: API URL, site key, business id. Product page calls /api/create/embed on click.
Business ID
What is a business id?
Every Yoinx business has a stable UUID (businesses.id). Embed creates stamp games.business_id so prize tables show under your shop, analytics stay attributed, and fulfillment knows which merchant owes the physical prize.
Env name
NEXT_PUBLIC_YOINX_BUSINESS_ID
Request field
body.businessId
The site key already maps to a business. Sending businessId is a hard check — if it doesn’t match the key’s business, create is rejected (no cross-merchant spoofing).
Your keys
Key generation & revoke
Manage publishable site keys for each business. Generate creates a new active key and deactivates previous active keys for that business. Revoke immediately stops embed creates for that key. Copy env into your product app when ready.
Connect to manage keys
Internet Identity is required to list and create embed keys for businesses you own.
Economics
Entry tools
Entry cost is set so a full lobby covers the item’s USD value at ≈ $0.10 per Yoinx tool.
minPlayers = random 5…25 entryYoinx = ceil(itemUsd / 0.10 / minPlayers) // 1 Yoinx ≈ $0.10 so pot covers item when full
Prize model
The table prize is the physical product you listed (images + story). Winner claims on Yoinx; you fulfill shipping / pickup as the business. Tools used to enter stay in the Yoinx economy — they are not a refund of the merch.
API reference
POST /api/create/embed
CORSCreate a physical item table for the business mapped to the site key. Call from the shopper’s browser after they connect Internet Identity.
Headers
Content-Type: application/json X-Yoinx-Site-Key: yx_pk_…
Body
{
"principal": "<shopper II principal>",
"businessId": "<businesses.id UUID>",
"title": "Product display title",
"itemName": "SKU / product name",
"itemDescription": "Story / details for the table",
"itemPriceUsd": 49,
"minPlayers": 12,
"maxPlayers": 25,
"entryYoinx": 41,
"gameImages": ["https://…/product.jpg"]
}Success response
{
"id": "<game id>",
"businessId": "<uuid>",
"businessName": "Your shop"
}
// Open: {YOINX_APP}/play/?id={id}Integrate
Client example
Minimal fetch from a product page. Use absolute image URLs that Yoinx can load (CDN / public assets). Gamerholic ships a ready client at src/lib/yoinx/client.ts.
// Product page — create table on Yoinx! click
const minPlayers = 5 + Math.floor(Math.random() * 21); // 5…25
const entryYoinx = Math.ceil(itemUsd / 0.10 / minPlayers);
const res = await fetch(`${YOINX_API}/api/create/embed`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Yoinx-Site-Key": process.env.NEXT_PUBLIC_YOINX_SITE_KEY!,
},
body: JSON.stringify({
principal, // shopper Internet Identity
businessId: process.env.NEXT_PUBLIC_YOINX_BUSINESS_ID,
title: product.name,
itemName: product.name,
itemDescription: product.story,
itemPriceUsd: product.priceUsd,
minPlayers,
maxPlayers: 25,
entryYoinx,
gameImages: [product.imageAbsoluteUrl], // public HTTPS URLs
}),
});
const { id } = await res.json();
// window.location = `${YOINX_APP}/play/?id=${id}`;Security
Publishable site key
Safe in frontend env (like Stripe pk_). Maps to one business. Rotate if leaked.
Origin allowlist
When set, only listed Origins may create tables with your key.
businessId check
Body businessId must match the key’s business — no cross-merchant spoofing.
No secret on IC assets
Static shops never hold a private API secret; Yoinx validates the site key.
Shopper flow
Connect II
Same identity as Yoinx.
Tap Yoinx!
Table opens for that product.
Play & win
Winner claims the merch.