niche

name	niche
description	Trading card marketplace with partial USDC deposits. Browse cards, deposit partial amounts, and complete purchases with secure on-chain escrow.

Niche v1 — Trading Card Marketplace with Partial Deposits

A peer-to-peer trading card marketplace where users list, discover, and transact cards with partial USDC deposits on Base Sepolia. Meet in person to inspect cards before completing payment.

Architecture

Hosted backend on Supabase Edge Functions. The CLI is a thin HTTP client — all heavy logic (auth, signing, escrow, on-chain transactions) runs server-side.

CLI (thin client)          →  Edge Functions (Supabase)
  fetch() + open()              niche-api   (REST API)
  ~/.niche/auth.json            niche-ui    (hosted HTML pages)
  @supabase/supabase-js         niche-sign  (passkey signing)
  open (browser launcher)       niche-escrow (on-chain ops)

Hosted UI: https://niche-ddq89ltdk-clement-sutjiatmas-projects.vercel.app

Anyone with the link can browse cards — no install needed.

Why Partial Deposits + In-Person Inspection

• Partial deposits — Hold a card with just $10-50 deposit, not full price
• Meet & inspect — See the card condition in person before final payment
• Atomic payment — Buyer confirms + pays remaining amount in single action
• USDC escrow — All funds secured on-chain, released when both confirm
• Buyer cancellation — Get full refund before seller confirms meetup
• Passkey signing — Touch ID / Face ID to authorize transactions
• Gas sponsored — No ETH needed for transactions
• Shareable links — Send card URLs to anyone, no app needed

Trading Card Flow

1. Seller lists "Charizard Base Set" for $50 with $10 min deposit
2. Buyer deposits $10 USDC → card is held for buyer
3. Buyer can cancel anytime before seller confirms → full $10 refund
4. Both parties meet in person to inspect card
5. Seller confirms they showed up
6. Buyer confirms AND pays $40 remaining (atomic action)
7. Backend releases total $50 to seller

Commands

Browse (no account needed)

niche search --category "Pokemon" --max-price 100
niche browse                              # Open listings in browser
niche browse --category "Magic"           # Filtered browser view
niche view <id>                           # Open card detail in browser
niche show <id>                           # View card detail in terminal

Authentication

niche login       # Opens browser → email OTP → passkey → wallet created
niche logout      # Clear local session
niche whoami      # Show identity + wallet + USDC balance

Login happens entirely in the hosted UI. The browser handles:

1. Email → OTP verification (Privy)
2. Passkey registration (Touch ID / Face ID)
3. Embedded wallet creation (server-side)

Listings

niche post --item-name "Charizard Base Set" --price 50 --min-deposit 10 --category "Pokemon"
niche list                    # Your listings
niche cancel <id>             # Cancel listing

Watches

niche watch --category "Pokemon,Magic" --max-price 100
niche watches                 # List active watches
niche unwatch <id>            # Remove watch
niche check-matches           # Check for new matches (cron)

Deposits & Payments

niche interest <id>           # Opens deposit page in browser (passkey signing)
niche confirm <id>            # Confirm meetup + pay remaining (buyer) OR confirm meetup (seller)
niche cancel <id>             # Cancel deposit and get refund (buyer only, before seller confirms)
niche dispute <id>            # File dispute, hold funds
niche escrow [id]             # View payment status
niche balance                 # Check wallet USDC + ETH balance
niche fund [amount]           # Open Circle faucet for testnet USDC

Testing

niche post --item-name "Pikachu" --price 25 --min-deposit 5 --simulate seller1
niche interest abc123 --simulate buyer1
niche confirm abc123 --simulate buyer1
niche confirm abc123 --simulate seller1

Authentication Requirements

Action	Without Login	With Login
Search / browse	✅ Works	✅ Works
Post listings	✅ With simulate	✅ Works
Place deposit	❌ REQUIRES LOGIN	✅ Real USDC deposit
Confirm + pay	❌ REQUIRES LOGIN	✅ Completes purchase
Cancel deposit	❌ REQUIRES LOGIN	✅ Get refund
Dispute	❌ REQUIRES LOGIN	✅ Holds funds
Fund wallet	❌ REQUIRES LOGIN	✅ Faucet

User Journey

1. BROWSE — niche search / niche browse (no account)
2. VIEW   — niche view <id> (opens hosted page)
3. LOGIN  — niche login (browser: email → OTP → passkey → wallet)
4. FUND   — niche fund 50 (Circle faucet → testnet USDC)
5. DEPOSIT — niche interest <id> (browser: passkey signs $10 deposit)
6. MEET   — Schedule in-person inspection
7. SELLER CONFIRMS — niche confirm <id> (seller acknowledges meetup)
8. BUYER CONFIRMS + PAYS — niche confirm <id> (buyer: passkey signs $40 remaining)
9. RELEASED — Backend releases total $50 to seller

Example Agent Interactions

First-Time User

User: "Find me a Charizard card under $100"

Agent runs: niche search --category "Pokemon" --item-name "Charizard" --max-price 100

Agent: "Found 2 Charizard cards! Here are the results:
  1. [a1b2c3d4] Charizard Base Set 1st Edition - $50 (min deposit: $10)
  2. [e5f6g7h8] Charizard EX Full Art - $85 (min deposit: $20)

Want to see any in your browser? Or interested in one?"

User: "I'm interested in #1"

Agent runs: niche whoami

Agent: "You'll need to login first. Opening the login page..."

Agent runs: niche login

Agent: "Complete the email verification and passkey setup in your browser.
        Once done, run `niche whoami` to verify."

Deposit Flow

User: "Place deposit on listing a1b2c3d4"

Agent runs: niche interest a1b2c3d4

Agent: "Opening the deposit page in your browser.
        Sign with your passkey (Touch ID) to deposit $10 USDC.
        You'll pay the remaining $40 when you meet and confirm."

Buyer Confirmation + Payment

User: "I met the seller and the card is perfect. Complete the purchase."

Agent runs: niche confirm a1b2c3d4

Agent: "Opening the confirmation page in your browser.
        Sign with your passkey to:
        1. Confirm you inspected the card
        2. Pay the remaining $40 USDC

        The seller will receive the total $50 once both confirm."

Cancellation

User: "I need to cancel my deposit on listing a1b2c3d4"

Agent runs: niche cancel a1b2c3d4

Agent: "Cancelling your deposit. You'll get your full $10 USDC back.
        (Note: You can only cancel before the seller confirms meetup)"

Tips for Agents

1. Auto-login for deposits — Before niche interest, check niche whoami. If not logged in, run niche login.
2. Always check setup — Run niche whoami to see if user is configured.
3. Offer to watch — If search returns no results, offer niche watch.
4. Show listing IDs — Users need IDs for interest/confirm/view.
5. Explain partial deposits — Users deposit minimum amount, pay rest at meetup.
6. Prompt before confirming — Confirming as buyer = paying remaining amount (real funds).
7. Prompt before interest — Deposits real USDC to escrow.
8. --simulate is for demos only — Only use when user explicitly asks to test.
9. Browser commands — niche login, niche interest, niche confirm (buyer), niche fund, niche browse, niche view all open the browser.
10. Terminal commands — niche search, niche show, niche whoami, niche balance, niche confirm (seller) stay in terminal.
11. Cancellation window — Buyers can cancel anytime before seller confirms meetup.

Sample Trading Cards (15 Available)

Pokemon (5 cards):

• Charizard Base Set 1st Edition - $50 (min: $10)
• Blastoise Base Set - $30 (min: $8)
• Pikachu Illustrator - $150 (min: $50)
• Mewtwo EX Full Art - $25 (min: $5)
• Rayquaza VMAX Rainbow - $40 (min: $10)

Magic: The Gathering (4 cards):

• Black Lotus Alpha - $200 (min: $75)
• Mox Sapphire - $100 (min: $30)
• Tarmogoyf Future Sight - $35 (min: $10)
• Liliana of the Veil - $45 (min: $12)

Sports (4 cards):

• Michael Jordan 1986 Fleer Rookie - $120 (min: $40)
• Tom Brady 2000 Playoff Contenders Auto - $80 (min: $25)
• Mike Trout 2009 Bowman Chrome Auto - $60 (min: $20)
• LeBron James 2003 Topps Chrome Rookie - $55 (min: $15)

Yu-Gi-Oh (2 cards):

• Blue-Eyes White Dragon 1st Edition - $28 (min: $8)
• Dark Magician Girl MFC 1st - $22 (min: $6)

Testnet & On-Chain

All transactions use real on-chain USDC on Base Sepolia testnet. No real funds at risk.

• USDC (Base Sepolia): 0x036CbD53842c5426634e7929541eC2318f3dCF7e
• Gas is sponsored — users don't need ETH
• Get testnet USDC: https://faucet.circle.com (select Base Sepolia)

Error Handling

Error	Agent Response
Not logged in	Run niche login to open browser auth.
No wallet	Login creates a wallet automatically.
Insufficient USDC	Run niche fund to get testnet USDC from Circle faucet.
Listing not found	Check ID, or run niche search again.
Already confirmed	Waiting for other party.
Cannot cancel	Seller already confirmed. Buyer can only cancel before seller confirms.
On-chain tx failed	Try again; escrow Edge Function handles retries.

Data Storage

• Supabase Postgres — Users, listings, watches, escrows (with partial deposit tracking)
• Supabase Vault — Privy secrets, escrow private key
• Edge Functions — All server-side logic (Deno runtime)
• Local — ~/.niche/auth.json (auth token + wallet), ~/.niche/config.json (legacy)

Key Differences from v0 (Housing)

• Partial deposits — Deposit only minimum amount, not full price
• Atomic confirmation + payment — Buyer confirms and pays remaining in single action
• Buyer cancellation — Full refund before seller confirms
• In-person inspection — Meet to verify card condition before completing purchase
• Trading cards — Pokemon, Magic, Sports, Yu-Gi-Oh instead of housing
• Categories — Card categories instead of neighborhoods
• Simplified UI — Less "escrow" jargon, clearer payment flow