For HumansFor Agents

FOR AGENTS

Integrate Lotero into your AI agent or application. Execute spins and claims via REST API with x402 payments. No API keys needed — just USDC on Base.

Don't want to read? Copy everything and paste it into your favorite LLM.

Quick start

Install
npm install @x402/fetch @x402/evm viem
Spin (Node.js)
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount("0xYOUR_PRIVATE_KEY");
const client = new x402Client();
registerExactEvmScheme(client, { signer });
const fetchWithPayment = wrapFetchWithPayment(fetch, client);

// Spin
const res = await fetchWithPayment("https://api.lotero.xyz/spinWith1USDC", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ player: signer.address, referral: null })
});
const { requestId } = await res.json();

// Poll for result
let result;
do {
  await new Promise(r => setTimeout(r, 3000));
  const poll = await fetch(`https://api.lotero.xyz/round?requestId=${requestId}`);
  result = await poll.json();
} while (!result.resolved);

console.log(result.round); // { number1, number2, number3, hasWon, prize }

Endpoints

POST/spinWith1USDC1.1 USDC

Execute one slot spin. 1 USDC bet + 0.1 USDC fee.

Request
{ "player": "0x...", "referral": "0x..." | null }
Response
{ "requestId": "123", "txHash": "0x...", "status": "pending" }
POST/claim0.1 USDC

Claim player earnings (wins + referrals). Gasless.

Request
{ "user": "0x..." }
Response
{ "user": "0x...", "amount": "5000000", "txHash": "0x...", "status": "claimed" }
GET/round?requestId=...Free

Get spin result. Poll until resolved is true.

Response
{
  "requestId": "123",
  "resolved": true,
  "round": {
    "number1": "4", "number2": "4", "number3": "4",
    "hasWon": true, "prize": "5000000"
  }
}
GET/player/:address/balancesFree

Get player stats: total bet, earned, claimed, referrals.

GET/contract/healthFree

Check executor balance, contract bankroll, and VRF subscription status.

How x402 payment works

1
Call paid endpoint

Agent gets 402 response with payment requirements

2
Sign USDC authorization

x402 client signs a transferWithAuthorization (EIP-3009) — no on-chain tx

3
Retry with payment

x402 retries the request with the signed payment header

4
Execution

Facilitator settles payment, agent executes playFor() on-chain

Technical details

PLAY AS HUMAN
Built by Saka Labs