x402-trinity-gaming

A headless, zero-UI payment utility for Unity and Unreal Engine storefronts.

No UI. No overlay. No browser handoff. No console output. Your button, your art, your unlock animation — this handles the money and gets out of the way.

npm install x402-trinity-gaming

How it fits

Your storefront UI  ──▶  your backend  ──▶  chain
   (Unreal/Unity)         (this package)
        ▲                       │
        └────── events ─────────┘

The player's client signs one authorization with their own key. Your server does everything else. You never hold the player's key, and for direct purchases you hold no balance either. (Tabs are the exception - see INTEGRATION.md.)

Use

import { createStorefront } from 'x402-trinity-gaming/storefront';

const store = createStorefront({
  payTo: '0xYourStudioWallet',
  network: 'base',
  facilitator: 'https://your-facilitator.example',   // REQUIRED - no default
  nonceStore,                                        // REQUIRED - must survive restarts
  catalog: {
    vanguard_skin_01: '1500000',   // atomic units: 1.50 USDC (6 decimals)
    season_pass_04:  '9990000',    // 9.99
  },
  surcharge: { proceedsKey },      // the key for payTo
});

store.on('settled',  e => grantItem(e.playerId, e.itemId));
store.on('declined', e => showRefusal(e.playerId, e.code));

Serve the quote, take the signature, redeem it:

// 1. the client asks what it must sign
const quote = store.quote('vanguard_skin_01');

// 2. the client signs it and posts back { authorization, signature }
const result = await store.purchase({
  itemId: 'vanguard_skin_01',
  playerId: 'player-8823',
  playerAddress: '0xPlayerWallet',
  authorization,
  signature,
});

Events

Decline codes are unknown_item, already_used, rejected, settlement_failed and malformed. Each carries retryable — true means the same authorization may be presented again unchanged, false means mint a fresh one. Re-sending when retryable is false risks paying twice.

Prices are strings

Atomic units of the asset, as a decimal string. USDC has 6 decimals, so 1.50 is '1500000'. A float cannot represent money exactly, and this value goes inside a signature.

Nothing is printed

This library never writes to stdout or stderr — that is enforced by its build, not by convention. Diagnostics reach you through onDiagnostic, and the fee disclosure is exported as NOTICE for you to place wherever disclosure belongs in your product.

Scope

Base mainnet + USDC. Other EVM chains work by passing customChains. Check any entry against the deployed contract first: call DOMAIN_SEPARATOR() and confirm it matches what this library computes. A wrong name or version produces a signature that looks valid and the contract rejects.

Before you use it with real money

This software signs payment authorizations. You are responsible for the funds in any wallet you configure it with and for the limits you set. nonceStore must be durable — an in-memory replay guard forgets every settled payment on restart, which means selling the same item twice for free.

Building from source

git clone https://github.com/devmster/x402-trinity-gaming.git
cd x402-trinity-gaming
npm install
node tools/build.mjs

npm install first — the bundler is a dev dependency, and without it the build stops at ERR_MODULE_NOT_FOUND. The build verifies itself and prints BUILD VERIFIED; the dist/ it produces is byte-identical to the published package.

License

Business Source License 1.1. Source-available; converts to MIT on 2029-08-25. See LICENSE.

Network fee: 0.1% of merchant proceeds and 1 cent every 100 sales.