FidMarket Documentation

• A marketplace for Farcaster FIDs
• A transaction coordination layer for FID ownership transfers
• A wallet-native checkout and offer system
• A settlement system for Farcaster registry transfers on Optimism
• An operational dashboard for monitoring and recovery

FidMarket is not a social app, wallet, exchange, or custodial account provider. It is a marketplace and transaction coordination layer for Farcaster FID ownership flows.

FidMarket does not take custody by default when a seller creates a listing.

status = ACTIVE
executionMode = LEGACY_V1
custodyStatus = NONE

• Sellers keep using their Farcaster account while listed
• Listings are immediately live and purchasable
• Custody is not taken at listing creation
• A listing becomes reserved only when checkout starts
• Settlement transfers the FID at the end of the trade

Custodial execution paths may still exist for supported or fallback scenarios, but they are not the default marketplace path.

A Farcaster FID is the permanent numeric identity of a Farcaster account. On FidMarket, the FID is the core asset being listed and transferred.

Example: FID #1430092

An fname is the readable Farcaster username associated with an FID. A listing may include the current fname, and FidMarket tracks fname state during marketplace flows.

• FID transfer happens through Farcaster IdRegistry on Optimism
• fname handling may involve registry-side logic and hub/client propagation
• Farcaster clients may not update instantly after registry-side changes
• Registry state and visible client username state may not always update at the same time

Live-first listing means sellers do not hand over custody before listing. The seller keeps control of the FID until checkout or settlement requires action.

This reduces friction for sellers and lets listings go live faster, while signatures, custody checks, escrow, settlement status, audit logs, and admin review protect the final transaction path.

A funded WETH offer is an offer backed by WETH escrow on Optimism. The buyer signs a Farcaster transfer authorization and funds the offer escrow before the seller accepts.

When accepted, the funded offer becomes an order and settlement proceeds through the normal transfer path.

When a seller creates a listing, FidMarket stores:

• FID number
• Current fname
• Current recovery address
• Seller address
• Price
• Fee mode
• Seller authorization
• Execution mode
• Custody status
• Lifecycle timestamps

By default, a listing is created as:

ACTIVE
LEGACY_V1
custodyStatus = NONE

For normal live-first listings, the seller keeps custody while listed.

A listing becomes reserved when:

• A buyer starts checkout
• A funded offer is accepted

1. 1Buyer opens a listing
2. 2Buyer enters recovery address
3. 3Buyer signs Farcaster transfer authorization
4. 4Order is created
5. 5Buyer deposits payment into escrow
6. 6Backend confirms payment
7. 7Seller signs final settlement authorization if required
8. 8Settlement queue submits transfer
9. 9Backend verifies custody moved to buyer
10. 10Escrow release is executed
11. 11Order becomes SUCCEEDED
12. 12Listing becomes SOLD

• Buyer wallet address
• Buyer recovery address
• Buyer transfer authorization
• Payment confirmation
• Seller authorization
• Escrow reference
• Settlement transaction hash
• Release transaction hash

For Buy Now ETH checkout, the buyer deposits payment into the marketplace escrow contract. The backend confirms the escrow deposit before settlement proceeds.

• Order ID
• Buyer address
• Seller address
• Seller net amount
• Platform fee amount
• Fee recipient
• Chain ID
• Escrow contract address

1. 1Buyer opens offer modal
2. 2Buyer enters WETH amount
3. 3Buyer enters recovery address
4. 4Frontend reads Farcaster nonce from IdRegistry
5. 5Buyer signs transfer-and-change-recovery typed data
6. 6Backend prepares the funded offer
7. 7Buyer approves WETH allowance if needed
8. 8Buyer funds offer escrow
9. 9Backend verifies funding transaction
10. 10Offer becomes FUNDED
11. 11Seller may accept the offer
12. 12Accepted offer becomes an order
13. 13Settlement continues normally

• Buyer cannot fund without valid typed-data authorization
• Backend verifies buyer signature against Farcaster typed data
• Escrow funding must match expected offer slot values
• Seller can only accept valid funded offers
• Accepted funded offers transition into order settlement
• Funded offers should not be treated as normal unpaid orders
• Funded offer release is separate from normal ETH escrow release

• Listing relation
• Buyer and seller snapshots
• Promised FID
• Promised fname
• Payment status
• Settlement status
• Fname status
• Escrow references
• Transfer signatures
• Transfer deadlines
• Transaction hashes

Created
→ Payment confirmed
→ Signatures collected
→ Settlement ready
→ Settlement processing
→ Succeeded

If something goes wrong, an order may move to FAILED or NEEDS_REVIEW.

1. 1Payment confirmed
2. 2Buyer authorization collected
3. 3Seller authorization collected
4. 4Settlement job starts
5. 5FID transfer submitted on-chain
6. 6Transfer confirmation checked
7. 7Custody verified on-chain
8. 8Escrow or funded-offer release executed
9. 9Order finalized
10. 10Listing marked SOLD

• Seller still controls the expected FID
• Buyer does not already own an FID where that would block transfer
• Buyer authorization is present and valid
• Seller authorization is present and valid
• Payment is confirmed
• Escrow state matches expected order values
• FID custody changes to the expected buyer
• Release transaction succeeds

Orders may enter NEEDS_REVIEW when something is unsafe or inconsistent.

• FID custody did not move to expected buyer
• Escrow release reverted
• Funded-offer release reverted
• Chain state does not match expected state
• Transaction succeeded but final state needs manual verification
• Admin intentionally marks an order for review

Users can transfer their own FID outside the marketplace sale flow. This uses a two-signature process.

1. 1Owner starts transfer session
2. 2Backend generates owner typed data
3. 3Backend generates recipient typed data
4. 4Owner signs
5. 5Recipient signs
6. 6Owner submits transfer
7. 7Backend re-checks nonce consistency
8. 8Relayer submits transferAndChangeRecoveryFor
9. 9Transfer completes on-chain

• Wallet does not own an FID
• Wallet is not the direct custody owner
• FID is attached to an active listing
• FID is in reserved checkout
• FID is in settlement
• Recipient wallet already owns a Farcaster FID
• Owner or recipient nonce changes after signing

• Account username page
• Signed username-change submission path
• Direct fname registry transfer request logic
• Audit trail for username actions
• Optional Farcaster hub service scaffolding

Registry-side fname logic and active Farcaster client propagation are not always the same thing.

• Registry transfer can update ownership/assignment state
• Hub message publishing helps propagate active username state to Farcaster clients
• Without hub configuration, full client-side propagation may remain unavailable
• External Farcaster clients may cache or delay username display updates

• Wallet does not directly own an FID
• FID is part of an active listing
• FID is in reserved checkout
• FID is in settlement flow

• Order creation
• Checkout activity
• Signature requested
• Payment confirmation
• Settlement success
• Settlement failure
• Needs review cases
• Offer received
• Funded offer accepted

• Notification bell
• Unread count
• Notification dropdown
• Notifications page
• Mark as read
• Mark all as read

Users can link Telegram from the notifications page. Telegram is used for operational alerts and transaction updates.

Telegram notifications are convenience alerts. Users should still rely on the web app and on-chain state for final transaction status.

• Inspect listings
• Inspect orders
• Inspect linked funded offers
• Inspect audit logs
• Retry settlement
• Retry escrow release
• Emergency refund
• Mark order as needs review
• Mark reviewed
• Cancel stuck order safely
• Cancel stuck listing safely
• Handle legacy/manual fname recovery actions

1. 1User requests nonce
2. 2User signs SIWE message
3. 3Backend verifies signature
4. 4Backend returns JWT
5. 5Frontend uses bearer token for authenticated requests

• Connected wallet
• Valid SIWE session
• JWT bearer token
• Wallet ownership checks where applicable

• Listing requires control of the FID
• Self-service transfer requires direct custody ownership
• Username actions require direct ownership and no active marketplace block
• Seller settlement actions require the seller wallet

# Core
NODE_ENV=
PORT=
FRONTEND_URL=
APP_BASE_URL=

# Database / Queue
DATABASE_URL=
REDIS_URL=

# Auth
JWT_SECRET=
JWT_EXPIRES_IN=
SIWE_DOMAIN=
SIWE_NONCE_TTL_SECONDS=
SIWE_URI=

# Chain
CHAIN_ID=
OPTIMISM_RPC_URL=
RELAYER_PRIVATE_KEY=
FARCASTER_ID_REGISTRY_ADDRESS=
FARCASTER_ID_GATEWAY_ADDRESS=
MARKETPLACE_CUSTODY_ADDRESS=

# Escrow / Offers
OFFER_ESCROW_CHAIN_ID=
OFFER_ESCROW_CONTRACT_ADDRESS=
WETH_TOKEN_ADDRESS=
ESCROW_CHAIN_ID=
ESCROW_CONTRACT_ADDRESS=
PLATFORM_FEE_RECIPIENT=

# Business Rules
DEFAULT_FEE_BPS=
RESERVATION_TTL_SECONDS=
INTENT_DEFAULT_DEADLINE_SECONDS=
ESCROW_REFUND_DELAY_SECONDS=

# Telegram
TELEGRAM_BOT_TOKEN=
TELEGRAM_BOT_USERNAME=
TELEGRAM_WEBHOOK_SECRET=

# Hub / Username
HUB_HTTP_URL=
HUB_API_KEY=

If hub values are empty, hub-backed username publish/read behavior remains unavailable.

NEXT_PUBLIC_API_URL=
NEXT_PUBLIC_SITE_URL=
NEXT_PUBLIC_FARCASTER_CHAIN_ID=
NEXT_PUBLIC_ID_REGISTRY_ADDRESS=
NEXT_PUBLIC_MARKETPLACE_CUSTODY_ADDRESS=
NEXT_PUBLIC_ESCROW_CHAIN_ID=
NEXT_PUBLIC_ESCROW_CONTRACT_ADDRESS=
NEXT_PUBLIC_ID_REGISTRY_VERSION=
NEXT_PUBLIC_LISTING_AUTH_WINDOW_SECONDS=
NEXT_PUBLIC_BUY_AUTH_WINDOW_SECONDS=
NEXT_PUBLIC_WETH_TOKEN_ADDRESS=
NEXT_PUBLIC_OFFER_ESCROW_CONTRACT_ADDRESS=
NEXT_PUBLIC_FARCASTER_ID_REGISTRY_ADDRESS=

Recommended production frontend domain:

https://www.fidmarket.com

Backend CORS and generated frontend links should account for the www domain if that is the canonical public URL.

• IdRegistry address is correct
• Escrow contract addresses are correct
• Offer escrow contract addresses are correct
• WETH token address is correct
• Relayer private key is configured
• Relayer wallet is funded for gas
• Frontend chain IDs match backend chain IDs
• No Sepolia references remain in production environment

• Wallet-based authentication
• JWT session protection
• On-chain custody verification
• Buyer authorization deadlines
• Seller authorization deadlines
• Nonce verification
• Signature verification
• Escrow funding verification
• Escrow release verification
• Settlement state machine
• Needs-review safety state
• Audit logging
• Admin safety controls
• Telegram operational visibility

• Custody state does not match expectations
• Buyer already owns an FID
• Seller no longer controls the FID
• Payment or escrow state is invalid
• Signatures are expired or invalid
• Settlement transaction reverts
• Escrow release fails
• Funded-offer release fails

FID marketplace transactions touch multiple systems: wallet signatures, Farcaster registry state, Optimism transactions, escrow contracts, backend order state, and external Farcaster username/client behavior.

Because of this, FidMarket uses NEEDS_REVIEW when a flow should stop for manual inspection instead of continuing automatically.

• Hub-backed username publish/read operations remain unavailable if no hub is configured
• Registry-side changes may not fully propagate to clients
• HUB_HTTP_URL and HUB_API_KEY may remain empty

• Correct FID must be passed into offer modal
• Typed-data construction must be correct
• Nonce and deadline must be correct
• Escrow verification must match expected values
• WETH allowance must be sufficient
• Funding transaction must be confirmed
• Backend confirmation must succeed

Custodial V2 remains supported but is not the default production marketplace path.

The default marketplace path is live-first LEGACY_V1.

This can happen if the deposit component is checking wallet state too strictly.

Expected deposit requirements:

• Wallet connected
• Buyer address available
• Connected as buyer
• Correct chain selected
• Escrow contract configured
• Payment not already confirmed

This means the processor detected something that should not continue automatically.

• Custody mismatch
• Release transaction reverted
• Funded-offer release reverted
• Escrow state does not match expected state

• Offer status should be OPEN
• Funding status should be FUNDED
• Listing should not be sold or cancelled
• Buyer authorization should not be expired
• Offer escrow slot should exist and match expected values

• Check registry-side request status
• Check hub configuration
• Check Farcaster client cache/propagation delay
• Check whether the FID is blocked by active marketplace state