0xDocs 0x.limo

Docs / Scripting

Economy: SCRIP payouts from a funded wallet

Partly live

The economy capability: SCRIP payouts from a funded wallet, under caps.

#Economy: SCRIP payouts from a funded wallet

Capability economy. Typings: @x1/script Economy, Payout, Wallet (packages/script/v1/economy.d.ts).

ts
import { Economy, Players } from "@x1/script";

const r = await Economy.PayoutAsync(player, 25, "Pike, 4.2 kg", `catch-${catchId}`);
if (r.capped) player.SendMessage(`Paid ${r.paid} (cut: ${r.reason})`);
const w = await Economy.WalletAsync(); // { balance, todayPaid, caps: { perPayout, perPlayerDay, perDay }, frozen }

#Where the money is

SCRIP lives in each world's SCRIP ledger, the same one the Earth shop and the world's games use. That ledger is the only record of who holds what. Your experience's wallet is an account in it, x1w:<experience>, one per world.

  • A payout is an ordinary ledger transfer from the wallet to the player. The world's tax law applies.
  • Nothing can create SCRIP. There is no mint call in the API or in the host. A payout the wallet can't cover pays what it can, down to 0 (reason: "wallet").
  • The wallet is funded only by transfers:
    • you, in the world: /x1 <experience> fund <amount> moves your own SCRIP into the wallet;
    • an operator in the console (Worlds › Script economy › Fund), from the treasury or another ledger account.

#Caps

The approver grants three caps with the capability:

CapMeaning
per_payoutThe most one payout pays
per_player_dayThe most one player receives from this experience per UTC day
per_dayThe most this experience pays per UTC day, across every world and server

An operator can lower them in the console, or freeze the wallet (payouts pay 0, reason: "frozen"). Caps cut a payout short instead of failing it: check paid, capped and reason (per_payout, per_player_day, per_day, wallet, frozen).

The host also limits payouts to 2 per second per sandbox; past that the call throws rate limited.

#Idempotency

key (1-128 printable characters, no spaces) names the payout. The platform keeps one record per (experience, key), so a retry with the same key answers the first result with reason: "duplicate" and never pays twice. That holds even if the call timed out, the server restarted mid-payout or the retry ran on another server. Use a key that names the thing being rewarded, such as catch-<id> or quest-<player>-<quest>, never a random value per call.

#What happens on a payout

  1. The host checks your grant and the rate, and reads the wallet's ledger balance.
  2. The platform reserves the payout. In one transaction it applies the three caps and the key, and answers the amount allowed.
  3. The host writes the payout to its journal on disk, then asks the ledger to transfer. The memo is x1pay <experience> <id>: <memo>.
  4. The host reports the result. A crash between steps 3 and 4 is settled at the next start from the ledger's own audit: the transfer is either there or it never happened.

Every payout is in the console's payout log: key, asked, allowed, paid, tax, why it was cut.

#When payouts are closed

Payouts are refused while the world's PaperMCP says SCRIP can become real money. That covers three cases:

  • mcp.custom.scrip.real_money is on;
  • payments run on a real network;
  • the settings can't be read.

These are the same rules as the world's casino and poker. The operator can allow payouts anyway with the X1Script setting economy.allow-when-real-money.