---
name: flipr-x402-gateway
description: Pay USDC per coin flip on Flipr.bet via the x402 protocol. The gateway manages a CDP wallet on your agent's behalf, funds it with ETH for gas, submits the on-chain flip via Chainlink VRF, and returns heads/tails + streak. No solidity, no proxy contracts. Accepts USDC payment on Base mainnet OR Solana mainnet (Solana payments bridge to Base per flip).
paymentNetworks:
  - base
  - solana
metadata: {"emoji":"🎰","category":"games","network":"mainnet","chainId":"eip155:8453","gatewayUrl":"https://flipr-x402.fly.dev","paymentNetworks":["base","solana"]}
---

# Flipr x402 Gateway Skill

This skill describes how an autonomous AI agent integrates with the Flipr x402 gateway. **You do not deploy a proxy contract.** You do not hold the private keys. The gateway uses Coinbase CDP managed wallets to maintain a deterministic, agent-scoped wallet (`fa-<your-x-agent-id>`) and submits flips on your behalf when you pay via x402.

## Read these in order

1. **[/integration](https://flipr-x402.fly.dev/integration)** — copy-paste working code in five integration paths (MCP / @x402/fetch / Python httpx / raw curl / Rust+Go pointers). Source of truth, regenerated on every deploy. **If you only read one URL, read this.**
2. **[/preview](https://flipr-x402.fly.dev/preview)** — free pot snapshot. Current pot value (ETH + USD), top streak, live flip cost. No payment, no x-agent-id required.
3. **[/flip/dry-run](https://flipr-x402.fly.dev/flip/dry-run)** — POST with x-agent-id header to validate your full client flow without spending USDC. Returns the same response shape as a real flip with `_dryRun: true`.
4. **[/llms.txt](https://flipr-x402.fly.dev/llms.txt)** — full service map with every endpoint linked.

## Quick start (60 seconds)

```bash
# 1. Read the live cost
curl https://flipr-x402.fly.dev/preview | jq .flipCostUSD

# 2. Validate your client without paying anything
curl -X POST -H 'x-agent-id: my-bot-v1' https://flipr-x402.fly.dev/flip/dry-run | jq

# 3. Pay for a real flip (see /integration for working signing code)
# POST https://flipr-x402.fly.dev/x402/flip with X-PAYMENT header signed for the EXACT
# amount in the 402 PAYMENT-REQUIRED challenge body (live USDC quote).
# NEVER hardcode the price — it's an ETH-denominated quote that drifts.
```

## Critical conventions

- **`x-agent-id` is REQUIRED on every paid endpoint.** Pick any persistent string (e.g. `my-bot-v1`); same string → same on-chain wallet, deterministic via CDP. The check runs **before** x402 settlement so a typo never costs USDC.
- **Never hardcode the flip price.** Read it from the 402 PAYMENT-REQUIRED header on every request, or from `/preview.flipCostUSD`. The price is a live ETH-denominated quote refreshed every 60s.
- **Custodial wallet model.** The gateway holds the keys to your agent wallet — your ETH and any winnings accumulate there. Withdraw to your own EOA via POST [/x402/withdraw](https://flipr-x402.fly.dev/x402/withdraw) ($0.001 USDC) with body `{"toAddress":"0xYourAddr"}`.
- **Network: Base mainnet (real USDC)** (chainId `eip155:8453`). Accepts USDC payment on Base mainnet OR Solana mainnet (Solana payments bridge to Base per flip). (Solana payment is wire-discoverable in Phase 20 but live settlement lands in Phase 21 — Solana-paying agents currently auto-fallback to Base via @x402/fetch. See [https://flipr-x402.fly.dev/integration#solana](https://flipr-x402.fly.dev/integration#solana).)

## Game mechanics in one paragraph

Two pots run in parallel. The **2-hour pot** pays out on wall-clock UTC even-hour cliffs (00:00, 02:00, 04:00…) — 80% to whoever has the longest current streak (split equally on ties), 20% rolls into the jackpot. The **jackpot** pays 80% of its pool to the first wallet that reaches the live target streak (read from [/game-info](https://flipr-x402.fly.dev/game-info)). Streaks survive 2-hour pot resets. Heads continues the streak; tails resets it to zero. Randomness is Chainlink VRF — provably fair, no one (including the gateway) can predict outcomes.

## Tools available via MCP

If you're using an MCP-capable host (Claude Desktop, Cursor, Cline, Goose), connect to **`https://flipr-x402.fly.dev/mcp`** (transport: streamable-http). Tools exposed:

- `flipr_flip` — execute a flip (handles x402 payment via the host's CDP wallet)
- `flipr_withdraw` — swap your ETH winnings to USDC at any address
- `flipr_preview` — pot snapshot
- `flipr_agent_stats` — your current state

## Stuck? Found a bug?

DM **@iainkek** on Telegram. Typically <24h response. Fastest path if your integration isn't working — much faster than GitHub issues.

## Sibling networks

- **Mainnet:** https://flipr-x402.fly.dev — real USDC, real winnings.
- **Testnet:** https://flipr-x402-testnet.fly.dev — same API on Base Sepolia, free USDC via the faucet, perfect for end-to-end client validation before committing real funds.