sharpy-app

Next.js 14 frontend dApp for Sharpy — advanced on-chain split payment on Stellar. Supports recurring invoices, escrow-protected payments, batch operations, agentic x402 payments, CCTP cross-chain USDC bridging, and public on-chain verification.

Live App

https://sharpy-sigma.vercel.app

Pitch Deck

Demo Video

Live Testnet Transactions

See Sharpy in action with real on-chain transactions:

Create Invoice #3 — Basic invoice creation
Batch Creation — Multiple invoices in one transaction
Multi-recipient Split — Payment split to multiple addresses
Escrow Protection — Invoice with time-locked escrow
Recurring Billing — Subscription invoice setup

Test Account: GD4Q2BH6...RS63

Recommended Wallet for Testing

Freighter — Browser-based, instant signing, no phone required.
Freighter Setup Guide | 🧪 Testing Guide

Architecture

graph TD
    User["User / Browser"]
    Agent["AI Agent / HTTP Client"]
    Freighter["Freighter Wallet"]
    App["sharpy-app\nNext.js 14 · Vercel"]
    SDK["@stellar-sharpy/sdk\nTypeScript SDK"]
    X402["x402 Protocol\n/api/x402/[id]"]
    RPC["Soroban RPC\nstellar-sdk 16.0.1"]
    Contract["Sharpy Contract\nSoroban · Protocol 27"]
    Stellar["Stellar Network"]
    Horizon["Horizon API"]

    User -->|"connects wallet"| Freighter
    User -->|"interacts with UI"| App
    Agent -->|"GET /api/x402/[id]"| X402
    X402 -->|"settle via facilitator"| SDK
    App -->|"calls methods"| SDK
    Freighter -->|"signs transactions"| SDK
    SDK -->|"simulate + submit"| RPC
    RPC -->|"executes"| Contract
    Contract -->|"state + events"| Stellar
    Stellar -->|"event polling"| Horizon
    Horizon -->|"invoice history"| App

Features

Invoice Management

Create invoices with Fixed, Percentage, or Tiered split rules
Multi-recipient — split to any number of recipients
Multi-token — USDC, XLM, AQUA, yXLM per recipient
Recurring invoices — auto-generate next invoice on release
Batch creation — up to 10 invoices in one transaction
Cancel & refund — creator cancels and refunds all payers
Payout preview — see exact per-recipient breakdown before signing
Split rules display — visual breakdown of Fixed / Percentage / Tiered rules
Recurring invoice timeline — vertical chain visualization of subscription history
Invoice stats tab — completion ring, payer count, payment history bar chart

Payments

Pay toward any invoice with Freighter wallet
Pool payments — pay multiple invoices in one call
Transaction confirmation step indicators (Signing → Submitting → Confirming → Done)
QR code for sharing invoice payment links
Copy-to-clipboard for invoice URLs and contract address
Deadline countdown timer — live updates every second
Verified badge — displayed when invoice is fully funded

Escrow

Enable escrow on any invoice with configurable release delay
Escrow release management page
Dispute mechanism with optional arbitrator
CCTP cross-chain status banner with localStorage persistence

x402 Agentic Payments

Public /pay/[id] page with three payment modes: Wallet, x402 / Agent, Cross-chain (CCTP)
/api/x402/[id] endpoint — AI agents pay invoices via HTTP 402 protocol
GET returns structured payment requirements, POST verifies and settles
CCTP cross-chain tab — bridge USDC from Arbitrum, Ethereum, or Base to Stellar via Circle CCTP; generates hookData from connected wallet, polls Circle attestation API, completes inbound transfer via Freighter

Verification & Transparency

Public /verify/[id] — on-chain verification with no login required (SSR)
SHA-256 invoice fingerprint display (Protocol 25/26 CAP-75/82)
Audit log tab showing full on-chain history
Export invoice as image (html2canvas)
Share button with Twitter/Email integration

UX

Dashboard with search, filter by status, and Created/Paid tabs
Dark/light mode with system preference detection
Fully responsive — mobile-first layouts
Skeleton loading states on all async pages
Error boundary with graceful fallback
Empty state illustrations for dashboard and invoice list
Network indicator (testnet/mainnet)
Token icon display per recipient

Tech Stack

Layer	Technology
Framework	Next.js 14 (App Router)
Language	TypeScript 5
Styling	Tailwind CSS 3 + CSS custom properties
Fonts	Inter (body) + Space Grotesk (display)
Wallet	Freighter (`@stellar/freighter-api` v3)
Contract SDK	`@stellar-sharpy/sdk` (local workspace)
x402	`@x402/stellar` v2.17.0
Deploy	Vercel

Pages & Routes

Route	Type	Description
`/`	Static	Landing page with feature highlights and CTAs
`/dashboard`	Client	Wallet-gated invoice list with search and filter
`/invoice/new`	Client	Create invoice — single, escrow, or recurring
`/invoice/[id]`	Dynamic	Invoice detail, funding progress, pay button, QR code
`/invoice/[id]/escrow`	Dynamic	Escrow release and dispute management
`/invoice/[id]/recurring`	Dynamic	Recurring invoice chain viewer
`/invoice/[id]/cancel`	Dynamic	Creator cancel and refund
`/verify/[id]`	SSR	Public on-chain verification with fingerprint
`/pay/[id]`	Client	Public shareable payment page — wallet, x402, and CCTP cross-chain
`/api/x402/[id]`	API	x402 HTTP endpoint (GET: requirements, POST: settle)

Local Setup

Prerequisites

Node.js 20+
Freighter wallet browser extension

Install & Run

git clone https://github.com/stellar-sharpy/sharpy-app.git
cd sharpy-app
npm install
cp .env.example .env.local
# Edit .env.local with your values
npm run dev

Open http://localhost:3000.

Environment Variables

NEXT_PUBLIC_STELLAR_NETWORK=testnet
NEXT_PUBLIC_CONTRACT_ID=CAYTIFPD6RFWVHMK5SPPUUIWWAAANHKOJB6GOAJS5SR5MBKZMEY2UODZ
NEXT_PUBLIC_RPC_URL=https://soroban-testnet.stellar.org
NEXT_PUBLIC_USDC_CONTRACT_ID=CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA

Variable	Description
`NEXT_PUBLIC_STELLAR_NETWORK`	`testnet` or `mainnet`
`NEXT_PUBLIC_CONTRACT_ID`	Deployed Sharpy contract ID
`NEXT_PUBLIC_RPC_URL`	Soroban RPC endpoint URL
`NEXT_PUBLIC_USDC_CONTRACT_ID`	Native USDC contract ID on network

Build

npm run build    # builds SDK workspace then Next.js
npm run start    # production server
npm run lint     # ESLint + TypeScript check
npm run test:e2e # Playwright end-to-end tests

Project Structure

sharpy-app/
├── packages/
│   └── sdk/                    # @stellar-sharpy/sdk (local workspace)
│       ├── src/
│       │   ├── client.ts       # SharpyClient — all contract methods
│       │   ├── wallet.ts       # Freighter v3 wallet helpers
│       │   ├── utils.ts        # parseAmount, formatAmount, etc.
│       │   ├── errors.ts       # Typed error classes
│       │   └── index.ts        # Public exports + NETWORKS constant
│       └── package.json
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── page.tsx            # Landing page
│   │   ├── layout.tsx          # Root layout
│   │   ├── globals.css         # Tailwind + CSS design system
│   │   ├── dashboard/
│   │   ├── invoice/
│   │   │   ├── new/
│   │   │   └── [id]/
│   │   │       ├── page.tsx
│   │   │       ├── escrow/
│   │   │       ├── recurring/
│   │   │       └── cancel/
│   │   ├── pay/[id]/           # Public shareable payment page
│   │   ├── verify/[id]/        # SSR public verification
│   │   └── api/x402/[id]/      # x402 HTTP payment endpoint
│   ├── components/
│   │   ├── Navbar.tsx          # Sticky navbar with theme toggle
│   │   ├── WalletProvider.tsx  # Freighter wallet context
│   │   ├── Providers.tsx       # ThemeProvider + WalletProvider
│   │   ├── TokenSelector.tsx   # Multi-token dropdown
│   │   └── CopyButton.tsx      # Copy to clipboard
│   └── lib/
│       ├── client.ts           # SDK client setup from env vars
│       ├── tokens.ts           # Token registry (USDC, XLM, AQUA, yXLM)
│       └── utils.ts            # Formatting helpers
├── public/
│   ├── logo.svg
│   ├── logo.png
│   └── favicon.ico
├── .env.example
├── next.config.js
├── tailwind.config.js
└── package.json

Protocol Compatibility

stellar-sdk	Protocol	Status	Features
16.0.1	27	✅ Current	CAP-71 auth delegation ready

Protocol 25/26 Integration

Feature	Route	Description
Invoice fingerprint (CAP-75/82)	`/verify/[id]`	SHA-256 content hash displayed with copy button
TTL extension (CAP-78)	SDK `bumpInvoiceTtl`	Available via SDK for long-lived invoice maintenance

Related Repos

Repo	Description
sharpy-contracts	Soroban smart contract (Rust)
sharpy-sdk	TypeScript SDK

Contributing

See CONTRIBUTING.md. Always test with Freighter connected to testnet before opening a PR.

Security

See SECURITY.md for the vulnerability disclosure process.

License

MIT

Name		Name	Last commit message	Last commit date
.github		.github
packages/sdk		packages/sdk
public		public
src		src
.env.example		.env.example
.gitignore		.gitignore
.npmrc		.npmrc
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
FREIGHTER_SETUP.md		FREIGHTER_SETUP.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
TESTING.md		TESTING.md
next.config.js		next.config.js
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json

Navigation Menu

Uh oh!

Repository files navigation

sharpy-app

Live App

Live Testnet Transactions

Recommended Wallet for Testing

Architecture

Features

Invoice Management

Payments

Escrow

x402 Agentic Payments

Verification & Transparency

UX

Tech Stack

Pages & Routes

Local Setup

Prerequisites

Install & Run

Environment Variables

Build

Project Structure

Protocol Compatibility

Protocol 25/26 Integration

Related Repos

Contributing

Security

License

About

Releases

Packages

Used by

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

sharpy-app

Live App

Live Testnet Transactions

Recommended Wallet for Testing

Architecture

Features

Invoice Management

Payments

Escrow

x402 Agentic Payments

Verification & Transparency

UX

Tech Stack

Pages & Routes

Local Setup

Prerequisites

Install & Run

Environment Variables

Build

Project Structure

Protocol Compatibility

Protocol 25/26 Integration

Related Repos

Contributing

Security

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages