fomopayDocs
FomoPay API · v1

Pay the @ from your code.

One call resolves a verified Fomo identity, routes the payment to its verified payout wallet on Robinhood Chain, and gives you a receipt. You never collect, store or paste a wallet address.

the whole integration
await fomopay.send({
  to: "@lyra",
  amount: 100,
  asset: "USDG",
});

That is the product in one line. Everything else — identity resolution, the verified destination, gas, confirmation tracking, receipts, idempotency — happens underneath.

Your code never sees a wallet address. FomoPay resolves @lyra server-side to the payout wallet FomoPay verified for that identity on Robinhood Chain, pays it from your Reward Vault, and tells you when the chain has confirmed it.

Wallet payments where a person signs with their own wallet use the same identity layer through a checkout link — see Payments.

L
@lyra
FomoPay ReadyRobinhood Chain
  1. Identity resolved
    FomoPay Ready — a payout wallet verified by FomoPay
  2. Routed server-side
    To @lyra's verified wallet on Robinhood Chain. You never handle the address.
  3. 100 USDG settles
    transferFrom your Reward Vault, signed by the payout signer
  4. PAID ✓
    Confirmed on-chain and verified → receipt + payment.confirmed webhook

Set up in two lines

import { FomoPay } from "@fomopay/sdk";

const fomopay = new FomoPay({ apiKey: process.env.FOMOPAY_API_KEY });

await fomopay.send({ to: "@lyra", amount: 100, asset: "USDG" });

send pays from your project's Reward Vault — a wallet you own that approved FomoPay's payout signer for a capped USDG allowance. The SDK attaches an idempotency key to every create call, so its retries can never pay twice. For end-to-end exactly-once, pass your own key derived from the event you are paying for (Idempotency).

At a glance

Base URL
https://fomopay.family/v1 · local stack http://localhost:6280/v1
Network
Robinhood Chain ("robinhood") — Ethereum L2, chain id 4663, gas in ETH. Local development runs an anvil chain (31337).
Assets
USDG Global Dollar, 6 decimals, 0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168 · ETH native, 18 decimals. There is no official USDC on Robinhood Chain.
Auth
Authorization: Bearer fp_test_… (local chain) or fp_live_… (mainnet). Scoped, hashed, shown once.
Format
JSON, snake_case keys, amounts as decimal strings ("100.5"), timestamps ISO 8601 UTC.
Request ids
Every response carries x-request-id; errors repeat it as error.request_id.

Start here

5 minutes
Quickstart

API key → install → first reward to @lyra → webhook.

Games & bounties
Rewards

Pay winners by handle with an idempotency key.

Referrals & payroll
Bulk payouts

Validate @mia, @frog, @builder… then pay in one batch.

Signed events
Webhooks

payment.confirmed, verification, retries.

How a payment flows

  1. Type the @. You send @lyra, an amount and an asset. No address.
  2. FomoPay verifies the identity. The handle resolves through FomoPay's identity adapter to a profile with a payout wallet FomoPay verified (wallet signature + identity proof). Anything else — unverified, no wallet, wrong network, suspended, unknown — is refused with a specific error, never paid “just in case”.
  3. The destination is snapshotted. The verified wallet, its verification version and time are frozen onto the payment. A wallet change afterwards never redirects it.
  4. Risk checks run. Limits, vault availability, recent wallet changes, look-alike handles and approval thresholds can hold or block a payment before anything moves.
  5. It settles on Robinhood Chain. A plain ERC-20 transferFrom (vault) or a transfer signed by the sender's own wallet (checkout), tagged with a 32-byte payment reference. FomoPay marks it CONFIRMED only after the chain confirms it and the transfer is verified against the snapshot.

Built for games: FomoRun

Replace “DM us your wallet” with the winner's handle. The idempotency key is derived from the round, so a retried job, a double-clicked admin button or a redeploy mid-payout cannot pay the winner twice.

reward-winner.ts
import { FomoPay } from "@fomopay/sdk";

const fomopay = new FomoPay({ apiKey: process.env.FOMOPAY_API_KEY });

// When a FomoRun round ends. No wallet collection: the handle is enough.
const winner = match.winner.handle; // "@lyra"

await fomopay.rewards.create({
  recipient: winner,
  amount: "500",
  asset: "USDG",
  reason: `FomoRun #${round.id}`,
  // same round → same payout, however often this code runs
  idempotencyKey: `FOMORUN_${round.id}_WINNER`,
});
Sandbox identities

Until FomoPay's live Fomo identity integration is authorized, handles resolve to sandbox identities. They are labelled “Sandbox” in every UI and carry sandbox: true plus a SANDBOX_IDENTITY warning in the API. Payments to them are real transfers on the chain you run against.