---
name: potrun
description: Play Potrun on Base mainnet with an existing EVM wallet. Use when an agent wants to inspect Potrun pools and odds, spin ETH, resolve a Chainlink VRF v2.5 outcome, or claim a pending payout.
---

# Potrun

Potrun is an onchain multiplier game on Base mainnet. You spin ETH into a pool, Chainlink VRF v2.5 selects one of nine outcomes, and payouts range from 0x to 200x, capped at 80% of the live pool pot. Any EVM wallet or signer can play. The examples use viem as a reference; no other tooling is required.

## Bring your own wallet

- If you already have a wallet, use it. Do not create a new wallet and do not export a seed phrase or private key into a prompt, log, or chat.
- Read-only calls need only a Base RPC endpoint. Writes need a wallet or signer.
- The wallet-agnostic transaction recipe is `{ chainId: 8453, to: "0x24f2858928B5b16bb1F4942cEBD5e825f7CC2b6F", data, value }`. Let the wallet fill nonce and gas, and let it request confirmation if it normally does.
- Any of these signer styles work:
  - EIP-1193 provider (browser wallet) via viem `custom(provider)`.
  - JSON-RPC signer or node-managed account via `createWalletClient`.
  - Wallet SDK or smart account (Safe, ERC-4337); the player is the smart-account address.
  - A local key only for a dedicated low-balance wallet: `privateKeyToAccount(process.env.PRIVATE_KEY)`.
- Build `data` with the minimal ABI below. For example:

```ts
import { encodeFunctionData } from "viem";

const data = encodeFunctionData({
  abi,
  functionName: "spin",
  args: [1n],
});

// Send { chainId: 8453, to: "0x24f2858928B5b16bb1F4942cEBD5e825f7CC2b6F", data, value: amount }
// through your wallet's transaction API.
```

- Verify the chain before writing. Base mainnet is chain ID `8453`; do not send on another chain.
- Never send ETH directly to the contract. Use `spin`.

## Operating mode

Choose the mode that fits your authorization:

- **Approval mode** — prepare the bet, show the pool, amount, live payout cap, and expected loss, then wait for sign-off or wallet confirmation.
- **Autonomous mode** — proceed within your operator's mandate, spend limit, and stop conditions.

This skill does not impose an approval step. Decide based on your own authorization and risk policy.

## Network

| Item | Value |
| --- | --- |
| Network | Base mainnet |
| Chain ID | 8453 |
| Public RPC | https://mainnet.base.org |
| Potrun contract | 0x24f2858928B5b16bb1F4942cEBD5e825f7CC2b6F |
| ETH pool ID (current) | 1 |
| Native ETH sentinel | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |

`NATIVE_ETH` is a custom sentinel address, not an ERC20 contract. It always means native ETH. Do not call `name()`, `symbol()`, or `decimals()` on it. Treat it as `ETH` with 18 decimals.

Pools are created dynamically by the contract owner. Enumerate them at runtime; do not hardcode the pool list. The ETH pool is the pool whose token equals `NATIVE_ETH` (pool `1` at the time of writing).

## Discover pools

List every onchain pool, including future and test/mock pools. The web UI may hide some tokens; this enumeration does not. Use the `publicClient`, `POTRUN`, `NATIVE_ETH`, and `abi` from the reference setup below.

```ts
import { erc20Abi, formatUnits } from "viem";

const poolCount = await publicClient.readContract({
  address: POTRUN,
  abi,
  functionName: "poolCount",
});

const pools = await Promise.all(
  Array.from({ length: Number(poolCount) }, (_, index) => {
    const poolId = BigInt(index + 1);

    return (async () => {
      const [token, pot, totalSpins] = await publicClient.readContract({
        address: POTRUN,
        abi,
        functionName: "getPool",
        args: [poolId],
      });

      if (token.toLowerCase() === NATIVE_ETH.toLowerCase()) {
        return {
          poolId,
          token,
          name: "Ether",
          symbol: "ETH",
          decimals: 18,
          pot: formatUnits(pot, 18),
          totalSpins,
        };
      }

      const [name, symbol, decimals] = await Promise.all([
        publicClient
          .readContract({ address: token, abi: erc20Abi, functionName: "name" })
          .catch(() => "Unknown token"),
        publicClient
          .readContract({ address: token, abi: erc20Abi, functionName: "symbol" })
          .catch(() => token),
        publicClient
          .readContract({ address: token, abi: erc20Abi, functionName: "decimals" })
          .catch(() => 18),
      ]);

      return {
        poolId,
        token,
        name,
        symbol,
        decimals,
        pot: formatUnits(pot, decimals),
        totalSpins,
      };
    })();
  }),
);

console.table(pools);
```

- The ETH pool is always identified by `token === NATIVE_ETH`, never by an ERC20 `symbol()` call.
- `tokenToPoolId(token)` returns `0` if no pool exists for that token.
- `getPoolByToken(token)` returns `(poolId, accumulatedFees, totalSpins)` for a known token.
- For ERC20 market context, DexScreener's free token endpoint can help: `https://api.dexscreener.com/latest/dex/tokens/<tokenAddress>`. It is not a source of truth for Potrun pot, payout cap, or outcomes; read those from the contract.

## Randomness: Chainlink VRF v2.5

Potrun uses subscription-based Chainlink VRF v2.5. `spin()` only requests randomness; the outcome is resolved in a later VRF callback that fills `spinRequests[requestId]`. The player cannot predict or influence the outcome. If fulfillment is delayed, keep polling; do not submit another spin for the same request.

## Game mechanics

- Platform fee: currently `10%` of each spin, sent to the platform fee recipient. The rest goes to the pool pot. Read `platformFeePct()` before playing; the owner can change it up to 20%.
- Multipliers use 10,000 as 1.0x. A payout is `bet * multiplier / 10,000`.
- Payout cap: `min(raw payout, 80% of the live pool pot)`. Large bets are frequently capped. Read `getPool(poolId).accumulatedFees` and compute the cap before betting.
- Pending payouts: if a direct payout transfer fails, the amount is stored in `pendingWithdrawals[player][token]`. The player can call `claimPendingPayout(token)`.
- Minimum: the contract requires `amount > 0`; the web UI enforces a $0.10 minimum. Start with a small test bet.
- Gas is paid separately on Base.

## Outcomes

| Outcome | Multiplier | Chance |
| --- | --- | --- |
| 1 (Miss) | 0x | 53.70% |
| 2 | 0.5x | 14.00% |
| 3 | 1.2x | 14.00% |
| 4 | 1.5x | 9.00% |
| 5 | 2x | 6.00% |
| 6 | 5x | 2.40% |
| 7 | 10x | 0.80% |
| 8 | 100x | 0.08% |
| 9 (Jackpot) | 200x | 0.02% |

Overall win chance: 46.30%. Theoretical RTP: 81.30%.

## Risk and expected value

- Theoretical RTP is 81.30%, which means an expected loss of 18.70% per spin before gas.
- Actual returns can be lower due to the 80%-of-pot cap, fee changes, pot recovery by the owner, and short-session variance.
- RTP is an average over many spins, not a guarantee. You can lose the full bet.
- Read the live pot, fee, and preview before choosing an amount.

## Minimal ABI

This is a player-facing subset. It intentionally omits owner, admin, VRF configuration, and internal functions. Use [Basescan](https://basescan.org/address/0x24f2858928B5b16bb1F4942cEBD5e825f7CC2b6F) for the full ABI.

Human-readable form for viem:

```ts
const abi = parseAbi([
  "function spin(uint256 poolId) payable returns (uint256 requestId)",
  "function spin(uint256 poolId, uint256 amount) payable returns (uint256 requestId)",
  "function getPool(uint256 poolId) view returns (address token, uint256 accumulatedFees, uint256 totalSpins)",
  "function getPoolByToken(address token) view returns (uint256 poolId, uint256 accumulatedFees, uint256 totalSpins)",
  "function getOutcomes() view returns (uint32[9] weights, uint32[9] multipliers, uint32 totalWeight)",
  "function previewPayout(uint256 poolId, uint8 number, uint256 amount) view returns (uint256 potentialPayout, uint32 multiplier, uint32 weight, uint32 totalWeight)",
  "function spinRequests(uint256 requestId) view returns (uint256 poolId, address player, uint256 amount, bool fulfilled, uint8 outcomeNumber, uint256 payoutAmount)",
  "function pendingWithdrawals(address player, address token) view returns (uint256)",
  "function claimPendingPayout(address token)",
  "function platformFeePct() view returns (uint32)",
  "function poolCount() view returns (uint256)",
  "function tokenToPoolId(address token) view returns (uint256)",
  "event SpinRequested(uint256 indexed requestId, uint256 indexed poolId, address indexed player, address token, uint256 amount)",
  "event SpinFulfilled(uint256 indexed requestId, uint256 indexed poolId, address indexed player, address token, uint256 amount, uint8 outcomeNumber, uint32 multiplier, uint256 payoutAmount, uint256 remainingPot)",
  "error PoolDoesNotExist(uint256 poolId)",
  "error IncorrectPayment()",
  "error NativePaymentNotAllowed()",
  "error InvalidAmount()",
  "error NoPendingPayout()",
  "error TransferFailed()",
]);
```

JSON form for wallet tools that require a JSON ABI:

<details>
<summary>Minimal JSON ABI</summary>

```json
[
  {"type":"function","name":"MAX_PAYOUT_POOL_PCT","inputs":[],"outputs":[{"name":"","type":"uint32"}],"stateMutability":"view"},
  {"type":"function","name":"NATIVE_ETH","inputs":[],"outputs":[{"name":"","type":"address"}],"stateMutability":"view"},
  {"type":"function","name":"claimPendingPayout","inputs":[{"name":"token","type":"address"}],"outputs":[],"stateMutability":"nonpayable"},
  {"type":"function","name":"getOutcomes","inputs":[],"outputs":[{"name":"weights","type":"uint32[9]"},{"name":"multipliers","type":"uint32[9]"},{"name":"totalWeight","type":"uint32"}],"stateMutability":"view"},
  {"type":"function","name":"getPool","inputs":[{"name":"poolId","type":"uint256"}],"outputs":[{"name":"token","type":"address"},{"name":"accumulatedFees","type":"uint256"},{"name":"totalSpins","type":"uint256"}],"stateMutability":"view"},
  {"type":"function","name":"getPoolByToken","inputs":[{"name":"token","type":"address"}],"outputs":[{"name":"poolId","type":"uint256"},{"name":"accumulatedFees","type":"uint256"},{"name":"totalSpins","type":"uint256"}],"stateMutability":"view"},
  {"type":"function","name":"pendingWithdrawals","inputs":[{"name":"","type":"address"},{"name":"","type":"address"}],"outputs":[{"name":"","type":"uint256"}],"stateMutability":"view"},
  {"type":"function","name":"platformFeePct","inputs":[],"outputs":[{"name":"","type":"uint32"}],"stateMutability":"view"},
  {"type":"function","name":"poolCount","inputs":[],"outputs":[{"name":"","type":"uint256"}],"stateMutability":"view"},
  {"type":"function","name":"previewPayout","inputs":[{"name":"poolId","type":"uint256"},{"name":"number","type":"uint8"},{"name":"amount","type":"uint256"}],"outputs":[{"name":"potentialPayout","type":"uint256"},{"name":"multiplier","type":"uint32"},{"name":"weight","type":"uint32"},{"name":"totalWeight","type":"uint32"}],"stateMutability":"view"},
  {"type":"function","name":"spin","inputs":[{"name":"poolId","type":"uint256"}],"outputs":[{"name":"requestId","type":"uint256"}],"stateMutability":"payable"},
  {"type":"function","name":"spin","inputs":[{"name":"poolId","type":"uint256"},{"name":"amount","type":"uint256"}],"outputs":[{"name":"requestId","type":"uint256"}],"stateMutability":"payable"},
  {"type":"function","name":"spinRequests","inputs":[{"name":"","type":"uint256"}],"outputs":[{"name":"poolId","type":"uint256"},{"name":"player","type":"address"},{"name":"amount","type":"uint256"},{"name":"fulfilled","type":"bool"},{"name":"outcomeNumber","type":"uint8"},{"name":"payoutAmount","type":"uint256"}],"stateMutability":"view"},
  {"type":"function","name":"tokenToPoolId","inputs":[{"name":"","type":"address"}],"outputs":[{"name":"","type":"uint256"}],"stateMutability":"view"},
  {"type":"event","name":"SpinFulfilled","inputs":[{"name":"requestId","type":"uint256","indexed":true},{"name":"poolId","type":"uint256","indexed":true},{"name":"player","type":"address","indexed":true},{"name":"token","type":"address","indexed":false},{"name":"amount","type":"uint256","indexed":false},{"name":"outcomeNumber","type":"uint8","indexed":false},{"name":"multiplier","type":"uint32","indexed":false},{"name":"payoutAmount","type":"uint256","indexed":false},{"name":"remainingPot","type":"uint256","indexed":false}]},
  {"type":"event","name":"SpinRequested","inputs":[{"name":"requestId","type":"uint256","indexed":true},{"name":"poolId","type":"uint256","indexed":true},{"name":"player","type":"address","indexed":true},{"name":"token","type":"address","indexed":false},{"name":"amount","type":"uint256","indexed":false}]},
  {"type":"error","name":"IncorrectPayment","inputs":[]},
  {"type":"error","name":"InvalidAmount","inputs":[]},
  {"type":"error","name":"NativePaymentNotAllowed","inputs":[]},
  {"type":"error","name":"NoPendingPayout","inputs":[]},
  {"type":"error","name":"PoolDoesNotExist","inputs":[{"name":"poolId","type":"uint256"}]},
  {"type":"error","name":"TransferFailed","inputs":[]}
]
```

</details>

## Reference viem flow

Install `viem` (`npm i viem`, `bun add viem`, etc.) and use any Base RPC. The reference below signs with a local account; replace the signer with your wallet's account or transport if you already have one.

```ts
import {
  createPublicClient,
  createWalletClient,
  formatEther,
  http,
  parseAbi,
  parseEther,
  parseEventLogs,
} from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const POTRUN = "0x24f2858928B5b16bb1F4942cEBD5e825f7CC2b6F" as const;
const ETH_POOL_ID = 1n; // ETH pool = token === NATIVE_ETH
const NATIVE_ETH = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE" as const;
const RPC = "https://mainnet.base.org";

const abi = parseAbi([
  "function spin(uint256 poolId) payable returns (uint256 requestId)",
  "function spin(uint256 poolId, uint256 amount) payable returns (uint256 requestId)",
  "function getPool(uint256 poolId) view returns (address token, uint256 accumulatedFees, uint256 totalSpins)",
  "function getPoolByToken(address token) view returns (uint256 poolId, uint256 accumulatedFees, uint256 totalSpins)",
  "function getOutcomes() view returns (uint32[9] weights, uint32[9] multipliers, uint32 totalWeight)",
  "function previewPayout(uint256 poolId, uint8 number, uint256 amount) view returns (uint256 potentialPayout, uint32 multiplier, uint32 weight, uint32 totalWeight)",
  "function spinRequests(uint256 requestId) view returns (uint256 poolId, address player, uint256 amount, bool fulfilled, uint8 outcomeNumber, uint256 payoutAmount)",
  "function pendingWithdrawals(address player, address token) view returns (uint256)",
  "function claimPendingPayout(address token)",
  "function platformFeePct() view returns (uint32)",
  "function poolCount() view returns (uint256)",
  "function tokenToPoolId(address token) view returns (uint256)",
  "event SpinRequested(uint256 indexed requestId, uint256 indexed poolId, address indexed player, address token, uint256 amount)",
  "event SpinFulfilled(uint256 indexed requestId, uint256 indexed poolId, address indexed player, address token, uint256 amount, uint8 outcomeNumber, uint32 multiplier, uint256 payoutAmount, uint256 remainingPot)",
]);

const publicClient = createPublicClient({ chain: base, transport: http(RPC) });
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const wallet = createWalletClient({ account, chain: base, transport: http(RPC) });

async function play(amount: bigint) {
  const [token, pot] = await publicClient.readContract({
    address: POTRUN,
    abi,
    functionName: "getPool",
    args: [ETH_POOL_ID],
  });
  const feePct = await publicClient.readContract({
    address: POTRUN,
    abi,
    functionName: "platformFeePct",
  });
  const [jackpotPreview] = await publicClient.readContract({
    address: POTRUN,
    abi,
    functionName: "previewPayout",
    args: [ETH_POOL_ID, 9, amount],
  });
  const maxPayout = (pot * 80000n) / 100000n;

  console.log({
    token,
    pot: formatEther(pot),
    platformFeePct: Number(feePct) / 1000,
    maxPayout: formatEther(maxPayout),
    jackpotPreview: formatEther(jackpotPreview),
  });

  const { request } = await publicClient.simulateContract({
    account,
    address: POTRUN,
    abi,
    functionName: "spin",
    args: [ETH_POOL_ID],
    value: amount,
  });
  const hash = await wallet.writeContract(request);
  const receipt = await publicClient.waitForTransactionReceipt({ hash });
  if (receipt.status !== "success") throw new Error("Spin reverted");

  const [requested] = parseEventLogs({
    abi,
    eventName: "SpinRequested",
    logs: receipt.logs,
  });
  if (!requested) throw new Error("SpinRequested event not found");
  const requestId = requested.args.requestId;
  console.log({ requestId, txHash: hash });

  for (let attempt = 0; attempt < 60; attempt++) {
    const [poolId, player, bet, fulfilled, outcomeNumber, payoutAmount] =
      await publicClient.readContract({
        address: POTRUN,
        abi,
        functionName: "spinRequests",
        args: [requestId],
      });

    if (fulfilled) {
      const [, multipliers] = await publicClient.readContract({
        address: POTRUN,
        abi,
        functionName: "getOutcomes",
      });
      const multiplier = multipliers[Number(outcomeNumber) - 1];
      console.log({
        requestId,
        poolId,
        player,
        bet: formatEther(bet),
        outcomeNumber,
        multiplier: Number(multiplier) / 10000,
        payout: formatEther(payoutAmount),
      });
      return;
    }

    await new Promise((resolve) => setTimeout(resolve, 5000));
  }

  throw new Error(
    `VRF not fulfilled yet for request ${requestId}; check spinRequests later.`,
  );
}

await play(parseEther("0.001"));
```

Notes:

- `simulateContract` catches reverts before you spend gas.
- `wallet.writeContract(request)` uses the simulated request. If your wallet API does not accept that, send `{ to, data, value }` from `encodeFunctionData`.
- For an EIP-1193 provider, create the wallet client with `transport: custom(provider)`.
- For a smart account, use the smart-account client and address as `account`.

## Claim a pending payout

```ts
const pending = await publicClient.readContract({
  address: POTRUN,
  abi,
  functionName: "pendingWithdrawals",
  args: [account.address, NATIVE_ETH],
});

if (pending > 0n) {
  const { request } = await publicClient.simulateContract({
    account,
    address: POTRUN,
    abi,
    functionName: "claimPendingPayout",
    args: [NATIVE_ETH],
  });
  const hash = await wallet.writeContract(request);
  await publicClient.waitForTransactionReceipt({ hash });
}
```

## ERC20 pools

If a pool's token is not `NATIVE_ETH`, it is an ERC20 pool. Approve the exact amount first, then call `spin(poolId, amount)` with no ETH value. Use the `poolId` you discovered, not the ETH example's `ETH_POOL_ID`.

```ts
import { erc20Abi } from "viem";

// token = ERC20 pool token address; amount = base units of that token.
const allowance = await publicClient.readContract({
  address: token,
  abi: erc20Abi,
  functionName: "allowance",
  args: [account.address, POTRUN],
});

if (allowance < amount) {
  const hash = await wallet.writeContract({
    address: token,
    abi: erc20Abi,
    functionName: "approve",
    args: [POTRUN, amount],
  });
  await publicClient.waitForTransactionReceipt({ hash });
}

const hash = await wallet.writeContract({
  address: POTRUN,
  abi,
  functionName: "spin",
  args: [poolId, amount],
});
```

## Troubleshooting

- `PoolDoesNotExist` — wrong pool ID; discover pools at runtime. The ETH pool is the one whose token is `NATIVE_ETH` (pool `1` at the time of writing).
- `IncorrectPayment` — for ETH, `msg.value` must equal `amount`.
- `NativePaymentNotAllowed` — do not send ETH when spinning an ERC20 pool.
- `InvalidAmount` — amount must be greater than zero.
- `NoPendingPayout` — the connected player has no pending balance for that token.
- `TransferFailed` — a payout or fee transfer failed; check the wallet and token.
- VRF not fulfilled — wait and poll `spinRequests`; do not resubmit the same spin.
- Payout lower than expected — the 80%-of-pot cap was applied; read `getPool` before betting.
- Wrong chain — switch the wallet to Base mainnet (`8453`).

## Links

- App: https://potrun.xyz
- Contract on Basescan: https://basescan.org/address/0x24f2858928B5b16bb1F4942cEBD5e825f7CC2b6F
- Chainlink VRF v2.5: https://docs.chain.link/vrf/v2-5/overview
