@stellar-sharpy/sdk

TypeScript SDK for the Sharpy advanced split payment contract on Stellar Soroban. Wraps all contract interactions, wallet integration, and x402 agentic payment support into a clean, fully-typed API.

Architecture

graph LR
    App["sharpy-app\nNext.js 14"]
    SDK["@stellar-sharpy/sdk"]
    Freighter["Freighter Wallet"]
    RPC["Soroban RPC\nstellar-sdk 16.0.1"]
    Contract["Sharpy Contract\nProtocol 27"]

    App -->|"createInvoice / pay"| SDK
    Freighter -->|"signAuthEntry / signTransaction"| SDK
    SDK -->|"simulate + submit"| RPC
    RPC -->|"executes"| Contract

Install

npm install @stellar-sharpy/sdk

🎯 Live Testnet Transactions

See the SDK in action with real on-chain transactions:

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

Test Account: GD4Q2BH6...RS63

Quick Start

import { SharpyClient, connectWallet, deadlineFromDays, parseAmount, NETWORKS } from "@stellar-sharpy/sdk";

// Connect Freighter wallet
const publicKey = await connectWallet();

// Initialize client — testnet pre-configured
const client = new SharpyClient(NETWORKS.testnet);

// Create a split invoice — 60/40 between two recipients
const { invoiceId, txHash } = await client.createInvoice({
  creator: publicKey,
  recipients: [
    { address: "GABC...RECIPIENT1", amount: parseAmount("600") },
    { address: "GDEF...RECIPIENT2", amount: parseAmount("400") },
  ],
  token: "USDC_CONTRACT_ADDRESS",
  deadline: deadlineFromDays(7),
});

console.log(`Invoice #${invoiceId} created: ${txHash}`);

// Pay the invoice
await client.pay(publicKey, invoiceId, parseAmount("1000"));

// Fetch status
const invoice = await client.getInvoice(invoiceId);
console.log(invoice.status); // "Released"

API Reference

`SharpyClient`

new SharpyClient(config: SharpyClientConfig)

Field	Type	Description
`rpcUrl`	`string`	Soroban RPC endpoint
`networkPassphrase`	`string`	Stellar network passphrase
`contractId`	`string`	Deployed contract ID

Invoice Methods

Method	Returns	Description
`createInvoice(params)`	`Promise<{ invoiceId, txHash }>`	Create a new invoice with split rules and escrow options
`createBatch(creator, invoices[])`	`Promise<{ invoiceIds, txHash }>`	Create up to 10 invoices in one transaction
`createRecurring(params)`	`Promise<{ invoiceId, txHash }>`	Create recurring invoice with auto-generation on release
`cancelInvoice(caller, invoiceId)`	`Promise<{ txHash }>`	Creator cancels invoice and refunds all payments

Payment Methods

Method	Returns	Description
`pay(payer, invoiceId, amount)`	`Promise<{ txHash }>`	Pay toward an invoice
`poolPay(payer, payments[])`	`Promise<{ txHash }>`	Pay multiple invoices in one call
`releaseEscrow(caller, invoiceId)`	`Promise<{ txHash }>`	Release escrow-held funds after delay
`refund(caller, invoiceId)`	`Promise<{ txHash }>`	Refund invoice after deadline

Escrow & Dispute Methods

Method	Returns	Description
`disputeRelease(caller, invoiceId)`	`Promise<{ txHash }>`	Raise an escrow dispute
`resolveDispute(caller, invoiceId, release)`	`Promise<{ txHash }>`	Arbitrator resolves dispute

Read Methods

Method	Returns	Description
`getInvoice(id)`	`Promise<Invoice>`	Fetch full invoice state by ID
`getInvoiceStats(id)`	`Promise<InvoiceStats>`	Fetch funded/total/completion_bps/unique_payers
`getAuditLog(id)`	`Promise<AuditEntry[]>`	Full on-chain audit trail
`getPayerTotal(id, payer)`	`Promise<bigint>`	Total amount paid by a specific address
`getNextRecurring(id)`	`Promise<number \| null>`	Next invoice ID in recurring chain
`getInvoiceFingerprint(id)`	`Promise<string>`	SHA-256 content hash (Protocol 25/26)
`previewPayout(id, amount)`	`Promise<bigint[]>`	Preview exact per-recipient payouts with dust-correct rounding
`getInvoicesByCreator(creator)`	`Promise<number[]>`	Fetch all invoice IDs created by an address (on-chain index)
`getClaimableBalance(account, token)`	`Promise<bigint>`	Query internal credited balance after failed transfer

Fallback Recovery Methods

Method	Returns	Description
`claim(account, token)`	`Promise<{ amount, txHash }>`	Withdraw credited balance after failed recipient transfer
`getClaimableBalance(account, token)`	`Promise<bigint>`	Query claimable balance for account/token

Protocol 25/26 Methods

Method	Returns	CAP	Description
`bumpInvoiceTtl(caller, invoiceId)`	`Promise<{ txHash }>`	CAP-78	Extend invoice storage TTL to prevent archival
`getInvoiceFingerprint(invoiceId)`	`Promise<string>`	CAP-75/82	SHA-256 tamper-evident content hash
`previewPayout(invoiceId, amount)`	`Promise<bigint[]>`	CAP-82	Preview split distribution with checked arithmetic

Wallet Helpers

Function	Returns	Description
`connectWallet()`	`Promise<string>`	Connect Freighter, return public key
`getWalletPublicKey()`	`Promise<string \| null>`	Get currently connected public key
`signTransaction(xdr, passphrase)`	`Promise<string>`	Sign a transaction XDR

Utilities

Function	Description
`parseAmount(value)`	Parse USDC string to stroops (bigint) — `"10.5"` → `105_000_000n`
`formatAmount(stroops)`	Format stroops as USDC string — `105_000_000n` → `"10.5"`
`deadlineFromDays(days)`	Unix timestamp N days from now
`isExpired(deadline)`	Check if a deadline has passed
`isValidAddress(address)`	Validate a Stellar G... address
`truncateAddress(address)`	Truncate for display: `GABC...XYZ`
`explorerUrl(network, id, type)`	Build Stellar Expert explorer URL

NETWORKS Constant

import { NETWORKS } from "@stellar-sharpy/sdk";

// Testnet — pre-configured with deployed contract ID
const client = new SharpyClient(NETWORKS.testnet);
// { rpcUrl, networkPassphrase, contractId }

// Mainnet
const client = new SharpyClient(NETWORKS.mainnet);

Error Handling

The SDK exports typed error classes for graceful handling:

import {
  InvoiceNotFoundError,
  DeadlinePassedError,
  InvoiceNotPendingError,
  OverpaymentError,
} from "@stellar-sharpy/sdk";

try {
  await client.pay(publicKey, invoiceId, parseAmount("100"));
} catch (e) {
  if (e instanceof DeadlinePassedError) {
    console.error("Invoice deadline has passed");
  } else if (e instanceof OverpaymentError) {
    console.error("Payment exceeds remaining balance");
  }
}

Types

interface Invoice {
  version: number;
  creator: string;
  recipients: string[];
  amounts: bigint[];
  tokens: string[];
  deadline: number;
  funded: bigint;
  status: "Pending" | "Released" | "Refunded" | "Cancelled";
  escrowEnabled: boolean;
  escrowReleaseDelay: number;
  completionTime?: number;
}

type SplitRule =
  | { type: "Fixed"; amount: bigint }
  | { type: "Percentage"; bps: number }
  | { type: "Tiered"; threshold: bigint; bps: number };

interface AuditEntry {
  action: string;
  actor: string;
  timestamp: number;
}

Build & Development

npm run build    # tsup — ESM + CJS + TypeScript declarations
npm run dev      # watch mode
npm run lint     # tsc --noEmit
npm test         # vitest

Module Overview

The SDK ships 35 focused utility modules alongside the core client:

Module	Description
`client.ts`	`SharpyClient` — all contract methods
`wallet.ts`	Freighter v3 wallet helpers
`utils.ts`	`parseAmount`, `formatAmount`, `deadlineFromDays`, etc.
`errors.ts`	Typed error classes
`retrylogic.ts`	Automatic retry for failed transactions
`batchoperations.ts`	Batch operation helpers
`eventlisteners.ts`	Contract event listener utilities
`walletdetection.ts`	Wallet detection utilities
`amountformatting.ts`	Amount formatting helpers
`addressutils.ts`	Address validation utilities
`transactionbuilder.ts`	Transaction builder utilities
`simulationhelpers.ts`	Transaction simulation helpers
`errorrecovery.ts`	Error recovery mechanisms
`cachelayer.ts`	Response caching layer
`paginationhelpers.ts`	Pagination utilities
`typeguards.ts`	TypeScript type guard functions
`networkswitching.ts`	Network switching utilities
`webhooksupport.ts`	Webhook payload builders
`invoicebuilders.ts`	Invoice builder patterns
`asynchelpers.ts`	Async operation helpers
`timeoutconfig.ts`	Configurable timeouts
`loggingutils.ts`	Debug logging utilities
`estimatefees.ts`	Fee estimation helpers
`memosupport.ts`	Transaction memo support
`sorobanutils.ts`	Soroban utility functions
`contractinterfaces.ts`	Contract interface types

Protocol Compatibility

stellar-sdk	Protocol	Status
16.0.1	27	✅ Current

Related Repos

Repo	Description
sharpy-contracts	Soroban smart contract (Rust)
sharpy-app	Next.js 14 frontend dApp

Contributing

See CONTRIBUTING.md for setup, standards, and commit conventions.

Security

See SECURITY.md for the vulnerability disclosure process.

License

MIT

Name		Name	Last commit message	Last commit date
.github		.github
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Navigation Menu

Uh oh!

Repository files navigation

@stellar-sharpy/sdk

Architecture

Install

🎯 Live Testnet Transactions

Quick Start

API Reference

`SharpyClient`

Invoice Methods

Payment Methods

Escrow & Dispute Methods

Read Methods

Fallback Recovery Methods

Protocol 25/26 Methods

Wallet Helpers

Utilities

NETWORKS Constant

Error Handling

Types

Build & Development

Module Overview

Protocol Compatibility

Related Repos

Contributing

Security

License

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

@stellar-sharpy/sdk

Architecture

Install

🎯 Live Testnet Transactions

Quick Start

API Reference

SharpyClient

Invoice Methods

Payment Methods

Escrow & Dispute Methods

Read Methods

Fallback Recovery Methods

Protocol 25/26 Methods

Wallet Helpers

Utilities

NETWORKS Constant

Error Handling

Types

Build & Development

Module Overview

Protocol Compatibility

Related Repos

Contributing

Security

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`SharpyClient`