Developer API and contract reference

The OpenAPI 3.1 document is generated from the implemented health/readiness and V3 route surface. It covers path/query inputs, the signed settlement request body, successful response boundaries, and public 400/404/409/429/503 semantics. It intentionally excludes legacy V1/V2 product routes.

• Accepted Testnet release · JSONComplete immutable address/role/policy projection, or explicit unavailable state
• FLIP V3 Public User API · OpenAPI 3.1 JSONMachine-readable source contract; no server URL until accepted release
• Evidence-B reference transactions · JSONExplicit unavailable response until every registry-bound reference family is present

• All exact integers are decimal strings. Do not round through JavaScript Number before signing, comparing, or displaying raw units.
• A 503 is unavailable evidence/readiness, never a zero balance, no entitlement, no liability, or permission to send a transaction.
• Launchpad list/trade/candle responses carry chain ID and receipt provenance, but the current asset-detail response does not carry the common release/finalized envelope. Bind it to /v3/status and require provenance.blockNumber <= status.freshness.finalized.
• The OpenAPI document publishes no servers entry while Testnet lacks an accepted HTTPS publicApiBaseUrl; clients must not substitute the docs origin or invent api.flipnow.fun.

PoolManager active liquidity `L`

The current in-range Uniswap V4 liquidity scalar. It is not USD, TVL, market cap, or a token balance.

Launch `initialLiquidity` / `actualLiquidity`

The position liquidity minted at launch. It proves launch accounting and locked principal identity, not current dollar depth.

Launch `tokenSpentRaw` / `quoteSpentRaw`

Historical assets consumed to mint the position; refunds and later price movement mean they are not current reserves.

Executable depth

A same-block Quoter curve across disclosed notionals (for example 1/10/100 USDG), including fees and price impact.

• Do not use the ERC-20 balance of PoolManager as this pool’s reserves; PoolManager accounts across many pools and currencies.
• Do not label one Quoter result as total liquidity. Publish a curve, direction, block/hash, and failure point.
• Do not add FLIP’s 3% Hook fee to Community markets. Community pools are hookless and charge the fixed V4 LP fee 3000 = 0.30% only.
• Community LP fees are not creator proceeds by default. Anyone can call PermanentPositionLockerV4.collectFees(tokenId), but both currencies go only to constructor-fixed lpFeeRecipient(); the caller cannot choose it or remove principal.
• Canonical LP fees similarly go only to FlipFairLaunchV4.lpFeeRecipient(). The separate 3% USDG Hook revenue is atomically routed through HookRevenueRouter under the release’s Reserve/Holder policy.
• The accepted release publishes canonicalLpFeeRecipient and communityLpFeeRecipient. A verifier must read both immutable getters at the same selected finalized block and fail if either differs from its accepted projection.

FDV_quote(N) = price_quote_per_token(N) × totalSupply(N)
MarketCap_quote(N) = price_quote_per_token(N) × acceptedCirculatingSupply(N)

Creator allocation, Treasury custody, a permanent LP NFT, vesting, dead addresses, and protocol balances need explicit classification. FLIP embedded in an LP position cannot be excluded by subtracting the Locker’s wallet balance. Official Stock Token identity also does not make a Community token an official stock or prove a one-for-one claim on an underlying share.

The example performs only eth_chainId, finalized block reads, eth_call, accepted public API GETs, and V4Quoter simulation. It has no send/write/broadcast path. It fails before output when the accepted release, chain, PoolKey, role address, public API identity, Community registration, fee, total supply, or finality binding differs. Community mode requires /v3/status and /v3/accounting to agree on release/manifest/finalized block, requires the RPC block hash to equal accounting finalizedHash, and re-reads the asset provenance block/hash, registered token+USDG currencies, onchain decimals, hookless fee, Locker, and fee recipient.

RELEASE_ID="${FLIP_ACCEPTED_RELEASE_ID:?copy the accepted release ID from this docs site}"
node apps/docs/examples/read-only-market-metrics.mjs \
  --accepted-release "docs/releases/46630/${RELEASE_ID}/accepted-release.json"

RELEASE_ID="${FLIP_ACCEPTED_RELEASE_ID:?copy the accepted release ID from this docs site}"
COMMUNITY_TOKEN="${FLIP_COMMUNITY_TOKEN:?use a token returned by the accepted Launchpad API}"
node apps/docs/examples/read-only-market-metrics.mjs \
  --accepted-release "docs/releases/46630/${RELEASE_ID}/accepted-release.json" \
  --community-token "$COMMUNITY_TOKEN"

The machine-readable endpoint currently returns status=unavailable and references=[]. This is an explicit fail-closed result: the configured registry-bound inputs are absent or do not contain every required Coin/VRF, Parity, JIT, Holder and RWA reference family.

1. 01

   Accept one immutable Evidence B

   The release, manifest, acceptance plan, finalized Health, strict-verifier receipts, and all scenario artifacts must be registry-bound to one Evidence B commit.

2. 02

   Derive—not enter—each reference

   A generator reads only those immutable artifacts, loads the canonical receipt, decodes emitted IDs, and reconciles role address, chain/release/manifest, finalized block/hash, uniqueness, and terminal state.

3. 03

   Hash the derived response

   The docs build computes projectionHash over the complete derived payload so consumers can compare exact responses. The derived JSON and hash are not separate Evidence B registry records; authority remains the registry-bound source artifacts and accepted Evidence B commit.

4. 04

   Publish atomically

   Only after every scenario family passes may status=available and non-empty references appear. Partial success keeps the whole shortcut projection unavailable; raw accepted evidence remains the authority.

RPC, explorer, deployment block, contract addresses, ABI hashes, and public API base URL must be emitted from the accepted release manifest. This page will not guess them.

POST /v3/settlement-quotes
{
  "gameKind": "coin-manual",
  "player": "0x…",
  "allInUsdRaw": "10000000",
  "authorization": {
    "requestNonce": "0x<32 random bytes>",
    "deadline": "<unix seconds, no more than 60s ahead>",
    "signature": "0x…"
  }
}

domain = {
  name: "FLIP Settlement Quote Request",
  version: "1",
  chainId: 46630,
  verifyingContract: <accepted Gateway for gameKind>
}
primaryType = "SettlementQuoteRequestAuthorization"
types = {
  SettlementQuoteRequestAuthorization: [
    { name: "player",         type: "address" },
    { name: "gameKindHash",   type: "bytes32" },
    { name: "allInUsdRaw",    type: "uint256" },
    { name: "manifestHash",   type: "bytes32" },
    { name: "addressSetHash", type: "bytes32" },
    { name: "requestNonce",   type: "bytes32" },
    { name: "deadline",       type: "uint64" }
  ]
}
gameKindHash = keccak256(toBytes(gameKind))

The message values come only from the machine-readable accepted release, the connected wallet, and the user’s exact choice. Generate a fresh nonzero random requestNonce; never reuse it. The service never accepts a private key and never submits the player’s Bet.

• Complete viem Coin Manual integration exampleInjected wallet client · EIP-712/1271 request · user FLIP ceiling · EOA permit or pre-approved contract wallet · simulation · receipt Bet ID

1. 01

   Bind immutable and live identity

   Load /release/accepted-testnet.json; require status=accepted and a safe publicApiBaseUrl. Require /v3/status to be healthy and to match the accepted chain ID, release, Source A commit, manifest hash, config hash, rules version and deployment block, with fresh finalized state. /v3/status does not publish addressSetHash; take that immutable value only from the accepted-release JSON.

2. 02

   Check Catalog and capacity

   Use only an active eligible reward returned by /v3/rewards/catalog. Require capacity.admission.ready == true and no blockers, while remembering this read is advisory.

3. 03

   Authorize the quote request

   Sign the exact schema above with the player wallet, using acceptedRelease.manifest.addressSetHash. The verifying contract is the accepted Gateway for gameKind—not the core Game, settlement Router, docs origin, or API host.

4. 04

   Verify the issued quote

   Recompute its EIP-712 quoteId and recover the accepted settlementQuoteSigner. Require quote.runtime chain, release, Source A commit and manifest hash to agree with both the accepted-release JSON and live /v3/status; independently require quote.runtime.addressSetHash == acceptedRelease.manifest.addressSetHash. Then compare Router, Gateway, payer, exact USDG output, exact FLIP input, policy, expiry and one-time nonce.

5. 05

   Authorize FLIP and simulate

   Require the caller to supply a positive bigint maxFlipInRaw and reject quote.exactFlipIn > maxFlipInRaw before signing any permit. An EOA may sign FLIP EIP-2612 for the exact input in the same Gateway call. A contract wallet must pre-approve the accepted settlement Router for at least maxFlipInRaw before requesting its short-lived quote; pass permitData.enabled=false and never make the integration silently send an approval transaction. Preserve the user ceiling in the Gateway request, then simulate the exact calldata at current state.

6. 06

   Send once and decode the receipt

   Broadcast only the successful simulation request. Decode BetForwarded/TicketForwarded from that receipt for the Bet/Ticket ID, then read the finalized event journal for the VRF Request ID or report/liability identifiers. Never predict counters and never replace an unknown broadcast.

GET /v3/capacity?game=coin&mode=manual&allInRaw=10000000&asset=<reward-token-from-manifest>

# Require in the response:
chainId == 46630
manifestHash == status.manifestHash
advisoryOnly == true
atomicAdmissionRequired == true
capacity.admission.ready == true
capacity.admission.blockers.length == 0

# This remains advisory; simulate the exact Gateway call before broadcast.

Token and V4

FlipToken, canonical Hook, public router/Quoter, exact-output settlement, Fair Launch, permanent LP.

Games

Coin Game/Gateway, Parity Manual/Mystery Games/Gateways/Coordinator, Market/Reward registries.

Solvency

Unified Reserve, Game Fee Treasury, JIT Capacity/Quote/Executor, Oracle Bond Vault.

Access and rewards

Holding Oracle, Mystery Access, Holder Rewards and purchase venue.

RWA Everything

Identity Registry, Factory, Eligibility, Catalog, Community Controller/Router/Locker.

Governance

Timelock-owned managed contracts plus a pause-only EmergencyPauser.

// Winner recovery
UnifiedUsdReserveV3.makeCashClaimable(game, ticketId) // anyone, after SLA
UnifiedUsdReserveV3.claimCash(game, ticketId)         // winner only

// Holder proof relay
HolderRewardsV3.claim(epochId, index, account, amountRaw, merkleProof)

// Community launch
RwaEverythingFactoryV3.create({
  name, symbol, itemId, schemaHash, dataHash, provenanceHash, metadataUri, userSalt,
  totalSupplyRaw, creatorAllocationRaw, liquidityTokenRaw, liquidityQuoteRaw
})

Use (chainId, transactionHash, logIndex) as event identity, retain block hash and timestamp, and replay from the accepted deployment block after a reorg. Never predict IDs that the receipt emits.

Decode custom errors with the ABI bound to the manifest runtime. Unknown selector means a release/ABI mismatch and must fail closed; string-matching wallet messages is not sufficient.

• Index events in bounded block chunks and preserve transaction hash plus log index; replay after reorg.
• Use raw integer units and token decimals. Never use JavaScript floating point for fees, payouts, cents, or balances.
• Bind EIP-712 chainId and verifyingContract for every environment; Testnet signatures cannot be moved to Mainnet.
• Treat capacity reads as advisory and simulate the exact Gateway call before broadcast.
• Use finalized status and manifest identity on every evidence-sensitive response.