Ocean Request

An AI-powered marketplace for digital services with native x402 micropayments on Stellar.

Users discover APIs, AI models, and data feeds through a conversational AI agent, then purchase instant access with a single click — no sign-ups, no subscriptions, no intermediaries. Every payment is a real USDC transaction on Stellar, verified on-chain.

Video Demo | Live Demo | Built for the Stellar x402 Hackathon

---

The Problem

Agents are one of the biggest stories in tech, but most still hit the same wall: payments. They can reason, plan, and act — right up until they need to pay for an API call, unlock a tool, or access premium data. Meanwhile, humans face the same friction from a different angle: discovering and paying for digital services means navigating sign-up forms, billing dashboards, API key portals, and monthly invoices — just to make a single request.

Ocean Request removes that friction entirely. It replaces the subscription-and-API-key model with pay-per-request micropayments powered by x402 on Stellar. A user (human or agent) finds what they need, pays fractions of a cent in USDC, and gets instant access — all through standard HTTP.

---

What It Does

1. Connect your Stellar wallet (Freighter)
2. Ask the Navigator AI what you need — it searches 32 services and recommends the best fit
3. Buy with one click using x402 — your API key arrives instantly
4. Set a budget with Auto-Pay to skip wallet popups and buy multiple services seamlessly

Every purchase triggers a real USDC transaction on Stellar testnet, verifiable on stellar.expert.

---

Key Innovation: Auto-Pay Session Budget

The standout feature of Ocean Request is the Auto-Pay session budget — a pattern that makes x402 practical for high-frequency, multi-purchase workflows.

The problem with standard x402: every purchase requires a wallet popup for the user to sign the Soroban auth entry. This is acceptable for single purchases but breaks down when a user (or agent) wants to buy 5, 10, or 50 services in a session.

Our solution:

1. User sets a spending limit (e.g., max $0.05 USDC, max 5 purchases)
2. App generates a temporary Stellar keypair in-browser (never persisted to disk)
3. Funds it via friendbot (testnet XLM) and creates a USDC trustline (auto-signed)
4. User approves one single Freighter popup to transfer USDC to the session wallet
5. All subsequent purchases sign instantly using createEd25519Signer(hotSecret) — zero popups
6. When the session ends, remaining USDC returns automatically to the user's wallet

This transforms x402 from a single-purchase protocol into a session-based spending system — ideal for agent workflows, bulk API access, and rapid prototyping against paid services. The secret key lives only in a React useRef (never rendered, never in localStorage, never on-chain) and is discarded when the session ends.

---

Features

Navigator AI Agent

A conversational assistant (powered by Claude) that understands natural language requirements, searches the full service catalog, compares options across price/latency/features, and recommends services with inline cards that link directly to the purchase page.

x402 Native Payments

Every purchase uses the x402 protocol end-to-end. The browser sends a standard HTTP GET, receives a 402 response, signs a Soroban auth entry via Freighter, and retries — all handled transparently by @x402/fetch. No custom payment APIs, no webhooks, no callbacks.

32-Service Marketplace

Five categories of services with full metadata, ratings, latency specs, and pricing from $0.002 to $0.025 USDC per request:

Category	Count	Examples
Data & Information	7	NewsWire, MarketPulse, WeatherCast, GeoLocate
Compute & Infrastructure	7	ModelForge, GPURender, EmbedX, VisionPulse
Content & Media	6	ArticlePass, StockPixel, BeatStream, FontForge
Agent-to-Agent	7	TranslateAgent, FactCheck, CodeAssist, GuardRail
Professional Services	5	CodeReview, ContractAudit, IDVerify, PerfTest

Purchase History & Verification

Full history of every purchase tied to your wallet address. Each entry includes the API key, price paid, and a transaction hash linked to stellar.expert for on-chain verification.

Watchlist

Save services for later and filter the marketplace to show only your watched items.

---

Architecture

Browser (Freighter Wallet)
    │
    │  Signs auth entries via @creit.tech/stellar-wallets-kit
    ▼
Port 3000 — Next.js 16 (frontend + API routes)
    │
    │  /                    Landing page
    │  /explore             Marketplace + Navigator chat + Auto-Pay panel
    │  /explore/[id]        Service detail + x402 purchase flow
    │  /purchases           Purchase history with on-chain links
    │  /api/agent-chat      Streaming LLM endpoint (Anthropic Claude)
    ▼
Port 3001 — Express x402 Server
    │
    │  GET /api/purchase    Protected by x402 paymentMiddleware ($0.01 USDC)
    │  GET /health          Health check
    ▼
x402 Facilitator (https://x402.org/facilitator)
    │
    │  Verifies payment → submits Stellar transaction
    ▼
Stellar Testnet — real USDC transfer from buyer to provider

Two processes run because @x402/express requires Express middleware and cannot run inside Next.js API routes.

---

x402 Payment Flow

Normal Mode (Freighter confirmation per purchase)

1. Browser calls GET /api/purchase (port 3001)
2. Server returns HTTP 402 + payment requirements (price, payTo, network)
3. @x402/fetch intercepts the 402 and parses the requirements
4. ExactStellarScheme calls signAuthEntry() → Freighter popup opens
5. User approves the Soroban auth entry in Freighter
6. Client retries the request with payment proof in headers
7. Server forwards proof to facilitator → Stellar tx submitted on-chain
8. Server returns 200 + API key + tx hash

Auto-Pay Mode (zero confirmations after setup)

1. Session setup: generate keypair → fund via friendbot → create USDC trustline
2. User approves ONE Freighter popup to transfer USDC to session wallet
3. For each purchase: createEd25519Signer(hotSecret).signAuthEntry() → instant
4. Same x402 flow as above, but signing is immediate (no popup)
5. Budget tracker enforces spending limits client-side
6. End session: remaining USDC auto-returns to user wallet

---

How x402 Is Used

This project demonstrates x402 as the native payment layer for a service marketplace:

• Server-side: @x402/express paymentMiddleware protects GET /api/purchase with a $0.01 USDC price on stellar:testnet. The middleware handles 402 responses, payment verification via the facilitator, and settlement automatically.

• Client-side: @x402/fetch wrapFetchWithPayment wraps the browser's native fetch() to transparently handle 402 responses. When the server returns 402, the client parses the payment requirements, signs with the user's wallet, and retries with payment proof.

• Signing: @x402/stellar ExactStellarScheme handles Soroban USDC contract authorization. In normal mode, it delegates to Freighter via @creit.tech/stellar-wallets-kit. In Auto-Pay mode, it uses createEd25519Signer with an in-memory hot wallet keypair for instant signing.

• Settlement: The x402 facilitator at https://x402.org/facilitator verifies the signed auth entry and submits the Stellar transaction on-chain.

---

Tech Stack

Layer	Technology
Frontend	Next.js 16, React 19, TypeScript 5.8
Wallet	@creit.tech/stellar-wallets-kit 2.1 (Freighter module)
Payments	x402 protocol (@x402/fetch 2.9, @x402/stellar 2.9, @x402/express 2.9)
Blockchain	Stellar testnet, USDC (issuer: GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5)
AI	Anthropic Claude (Sonnet 4.5) via @anthropic-ai/sdk, streaming SSE
Server	Express 4 with x402 paymentMiddleware
Audio	Web Audio API (synthesized payment and chat sounds)
Styling	Custom CSS, dark ocean theme (no framework)

---

Setup

Prerequisites

• Node.js 18+
• npm
• Freighter wallet browser extension (set to Testnet)
• An Anthropic API key (console.anthropic.com)

1. Clone the repository

git clone https://github.com/<your-org>/ocean-request.git
cd ocean-request

2. Create a Stellar testnet wallet for the provider

The provider is the API seller that receives payments. The buyer is the user's Freighter wallet.

1. Go to Stellar Lab and generate a keypair
2. Fund it at Stellar Lab - Fund
3. Add a USDC trustline:
   • Asset Code: USDC
   • Issuer: GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5
4. (Optional) Get testnet USDC at Circle Faucet (select Stellar testnet)

3. Fund your Freighter wallet

1. Open Freighter, switch to Testnet
2. Fund your account with friendbot (Freighter has a built-in button)
3. Add USDC trustline (same issuer as above)
4. Get testnet USDC from Circle Faucet

4. Configure environment variables

Root project — .env.local:

cp .env.local.example .env.local

ANTHROPIC_API_KEY=sk-ant-...                          # Your Anthropic API key
NEXT_PUBLIC_X402_SERVER_URL=http://localhost:3001      # x402 server URL

Server — server/.env:

cp server/.env.example server/.env

PROVIDER_STELLAR_ADDRESS=G...        # Provider wallet public key (from step 2)
X402_SERVER_PORT=3001

5. Install dependencies

npm install
cd server && npm install && cd ..

6. Run

npm run dev:all

This starts both processes concurrently:

• Next.js → http://localhost:3000
• x402 Express server → http://localhost:3001

---

Usage Walkthrough

Basic purchase (Freighter confirmation)

1. Open http://localhost:3000
2. Click "Connect Wallet" → Freighter opens → select your wallet
3. Click "Explore Services" → browse the marketplace
4. Chat with Navigator: "I need a fast embeddings API under $0.01" → get recommendations
5. Click a recommendation → opens the service detail page
6. Click "Buy with Freighter" → Freighter popup → sign → payment processes → API key delivered

Auto-Pay purchase (no confirmations)

1. On /explore, click "Set Budget" in the Auto-Pay bar
2. Set max spending ($0.05) and max purchases (5)
3. Click "Start Session" → one Freighter popup to fund the session wallet
4. Navigate to any service → button says "Buy Instantly (Auto-Pay)"
5. Click → purchase completes instantly with no popup, budget bar updates
6. When done, click "End Session" → remaining USDC returns to your wallet

Verify on-chain

# The x402 server returns 402 when called without payment
curl -i http://localhost:3001/api/purchase
# → HTTP/1.1 402 Payment Required

# Health check
curl http://localhost:3001/health
# → {"status":"ok","payTo":"G...","network":"stellar:testnet"}

After any purchase, click the transaction hash to verify on stellar.expert.

---

Project Structure

ocean_request/
├── app/
│   ├── page.tsx                      # Landing page
│   ├── layout.tsx                    # Root layout with provider chain
│   ├── globals.css                   # All styles (dark ocean theme)
│   ├── explore/
│   │   ├── page.tsx                  # Marketplace + Navigator + filters
│   │   └── [id]/page.tsx             # Service detail + purchase flow
│   ├── purchases/page.tsx            # Purchase history
│   └── api/agent-chat/route.ts       # Streaming LLM endpoint
├── components/
│   ├── wallet-context.tsx            # Stellar wallet provider
│   ├── session-budget-context.tsx    # Auto-Pay session wallet logic
│   ├── use-x402-payment.ts           # x402 purchase hook
│   ├── agent-chat-panel.tsx          # Navigator AI chat UI
│   ├── session-budget-panel.tsx      # Budget setup/status UI
│   ├── connect-wallet-button.tsx     # Connect/disconnect button
│   ├── purchases-context.tsx         # Purchase history (localStorage)
│   ├── watchlist-context.tsx         # Watchlist state
│   ├── agent-card.tsx                # Service card component
│   ├── app-providers.tsx             # Provider bridge
│   ├── audio-engine.ts              # Synthesized sound effects
│   ├── confetti.tsx                  # Success animation
│   ├── floating-mascot.tsx          # Landing page mascot
│   └── footer.tsx                   # Footer
├── data/
│   ├── services.ts                   # 32 services with full metadata
│   └── agent-prompts.ts             # Navigator system prompt + catalog
├── server/
│   ├── x402-server.ts               # Express + x402 paymentMiddleware
│   └── package.json                 # Server dependencies
└── public/
    ├── logo.png                     # Ocean Request logo
    └── ocean-bg.jpg                 # Background image

---

What's Real vs. What's Simulated

Transparency matters. Here's what's fully functional and what's representative:

Aspect	Status	Details
x402 payments	Real	Every purchase triggers a real USDC transaction on Stellar testnet, verified on-chain via the x402 facilitator
Wallet integration	Real	Freighter signs real Soroban auth entries for USDC transfers
Auto-Pay session wallet	Real	Generates real Stellar keypairs, real trustlines, real USDC transfers
Navigator AI	Real	Live Claude API calls with streaming responses
Service catalog (32 services)	Simulated	Services have realistic metadata but don't connect to actual backend APIs. The purchase flow (payment + API key generation) is real; the API key itself is a demo token
Purchase history	Real	Persisted per wallet in localStorage with real tx hashes
Ratings & reviews	Simulated	Static data for marketplace realism

---

Future Vision

Ocean Request demonstrates the pattern — here's where it goes next:

• Real service backends — Connect API keys to actual services (LLMs, data feeds, compute) so purchased keys unlock real functionality
• Dynamic pricing — Let service providers set and update prices on-chain via Soroban smart contracts
• Agent-to-agent purchasing — Agents that autonomously discover, evaluate, and purchase services from other agents using Auto-Pay sessions
• Mainnet deployment — Replace stellar:testnet with stellar:pubnet, real USDC, real spending limits
• Encrypted session persistence — Recover Auto-Pay sessions across browser tabs using encrypted localStorage
• Provider dashboard — Let service providers list, manage, and monitor their offerings and revenue
• MPP integration — Explore stellar-mpp-sdk for machine-to-machine payment flows alongside x402

---

Team

Built by:

• @karu_giann
• @ar3lisa
• @Anouk_Rimola

---

License

MIT