Skip to main content

Introduction

Welcome to Sphere! Navigating the complexities of blockchain technology can be daunting. Sphere is here to change that. We are a comprehensive developer platform designed to drastically simplify Web3 integration, empowering you to build innovative applications with ease. Our robust suite of tools and services abstracts away the low-level intricacies, allowing you to focus on creating exceptional user experiences.

Sphere provides everything you need to manage digital assets, facilitate seamless crypto payments, and interact with DeFi protocols.

Prerequisites: Setting Up Your Sphere Project​

Before you can start using the Sphere SDK, you need to create a project on the Sphere Dashboard and configure it properly.

1. Create Your Project​

  1. Visit the Sphere Dashboard: Go to https://dashboard.sphere-id.com
  2. Sign Up/Login: Create an account or log in if you already have one
  3. Create New Project: Click "Create Project" and provide:
    • Project name

2. Configure Allowed Origins​

After creating your project, you must configure allowed origins to prevent CORS issues:

  1. Navigate to Project Settings: In your project dashboard
  2. Add Allowed Origins: Add all domains/origins that will access your application:
    • http://localhost:3000 (for local development)
    • https://yourapp.com (for production)
    • https://your-staging.com (for staging)
    • Mobile app bundle IDs (for mobile apps)

⚠️ Critical: If you try to access the SDK from an origin that's not in your allowed origins list, it will be blocked by CORS. Make sure to add all domains where your application will run.

3. Get Your API Key​

  1. API Key Section: In your project dashboard, find the "API Keys" section
  2. Copy Your Key: Copy your project API key - you'll need this to initialize the Sphere SDK
  3. Keep It Secure: Store your API key securely and never expose it in client-side code in production

If you plan to use Payment Links functionality, you must deploy and configure a payment widget:

Why a Widget is Needed​

When users create payment links in your app and share them with others, the recipients need a way to interact with these links across different platforms (web, mobile, Telegram). Since there's no universal link format that works on all platforms, Sphere uses a widget-based approach:

  1. User clicks payment link → Redirected to your widget
  2. Widget asks user → "Which platform do you want to use?" (Web/Mobile/Telegram)
  3. Widget redirects → To the appropriate platform-specific app

Deploy Your Widget​

  1. Get the Template: Clone the widget template from https://github.com/stratosphere-network/sphere-widget
  2. Configure with Your API Key: Add your project API key to the widget configuration
  3. Deploy the Widget: Deploy to a public URL (e.g., https://widget.yourapp.com)
  4. Register Widget URL: In your Sphere dashboard, register your widget URL

Widget Configuration Example​

// widget configuration
const config = {
  projectApiKey: "your-project-api-key", // Required for fetching redirect links
  supportedPlatforms: ["web", "mobile", "telegram"],
  styling: {
    // Your custom styling options
  },
};

The widget will use your API key to fetch the registered redirect URLs for different platforms and present users with appropriate options.

What is Sphere? The Problem We Solve​

The promise of Web3 is immense, but its underlying technologies can present steep learning curves and integration challenges. Sphere tackles these head-on by offering:

  • Simplified Abstractions: Interact with complex blockchain operations through an intuitive SDK, without needing to become a blockchain expert.
  • Unified Platform: Access a wide array of Web3 functionalities—from wallet creation to DeFi swaps—through a single, coherent ecosystem.
  • Accelerated Development: Significantly reduce your development time and resources with ready-to-use components and clear documentation.

Our core pillars include:

  • Smart Wallet Infrastructure: Easy-to-integrate user wallets.
  • Versatile Payment Solutions: Powerful tools for crypto payments and monetization.
  • Seamless DeFi Access: Simplified interactions with decentralized finance protocols.

Why Choose Sphere? Key Benefits​

Choosing Sphere means choosing a faster, more efficient path to Web3:

  • Superior Developer Experience: Our SDKs (TypeScript first, with Python, Go, and Rust coming soon!) are designed for clarity and ease of use, backed by comprehensive documentation and examples.
  • Focus on Your Product, Not Plumbing: We handle the blockchain complexities so you can concentrate on your application's unique value proposition.
  • Scalability and Reliability: Built to support applications as they grow, ensuring a stable experience for your users.
  • Versatility for All Builders: Whether you're a solo developer, a startup, or an established enterprise, Sphere provides the tools to meet your Web3 needs.

Core Features & Capabilities​

Sphere equips you with a powerful toolkit:

  • Smart Wallet Infrastructure:
    • Effortless User Onboarding: Integrate smart wallets into your application with user-friendly methods like OTP (One-Time Password) verification.
    • Multi-Chain Asset Management: Allow users to securely manage their tokens and native assets across multiple supported blockchains.
    • Gasless Sending: Sending transactions is gasless by default, meaning users don't need to worry about gas fees or native gas tokens for these operations.
  • Payments & Monetization:
    • Flexible Payment Links: Easily create and share links for requesting crypto payments—ideal for invoices, one-time sales, or donations.
    • Pre-Authorized Flows (Permit): Implement systems for recurring payments, subscriptions, or future-dated transactions with user pre-approval.
    • Global Crypto Commerce: Enable your platform to accept cryptocurrency payments from a worldwide audience.
  • DeFi Integration:
    • Simplified Token Swaps: Integrate token swapping capabilities directly within your application, powered by leading DeFi protocols. You can choose whether swaps are gasless or standard.

Use Cases: What Can You Build?​

Sphere's versatility unlocks a multitude of possibilities:

  • Decentralized Applications (dApps):
    • Seamlessly onboard users with embedded smart wallets.
    • Enable in-dApp purchases, feature unlocks, or governance participation using crypto.
    • Integrate direct DeFi swaps or other financial services.
  • NFT Marketplaces & Platforms:
    • Simplify wallet creation and connection for new art collectors and traders.
    • Facilitate primary sales and secondary market transactions for NFTs.
  • Web3 Gaming Platforms:
    • Manage in-game economies with tokenized assets and currencies.
    • Enable NFT-based item ownership, trading, and interoperability.
    • Distribute tournament prizes or player rewards in cryptocurrency.
  • Creator Economy & SocialFi:
    • Allow fans to tip creators or subscribe to exclusive content using crypto.
    • Build token-gated communities and experiences.
    • Facilitate decentralized social interactions and rewards.
  • SaaS & Traditional Businesses Entering Web3:
    • Accept global cryptocurrency payments for existing products and services.
    • Expand your customer base to the rapidly growing crypto-native audience.
    • Experiment with tokenized loyalty programs or community incentives.

Core Workflows (Visualized)​

Below are diagrams illustrating common workflows you can implement using the Sphere SDK.

(Note: Ensure your Docusaurus project is configured to render Mermaid diagrams. This is typically enabled by default in recent versions with the classic preset, but may require specific configuration as detailed in the Docusaurus documentation if issues persist.)

User Authentication Flow​

User authentication in Sphere is a straightforward process involving OTP verification. The login method directly returns user details (including user ID, addresses, and access token) in its response, making the authentication flow simple and synchronous.

Making a Transaction (Gasless by Default)​

Once a user is authenticated, they can perform transactions such as sending tokens. These are gasless by default.

Sphere's PaymentLinksService allows users to create Payment Requests (to receive funds) and Send Links (to send funds, either to a specific recipient or openly).

Here's a simplified flow for creating a Payment Request:

Embark on Your Web3 Journey​

This introduction has only scratched the surface of what's possible with Sphere. We invite you to explore further and see how Sphere can accelerate your Web3 development:

  • Dive into the Sphere SDK Quickstart for hands-on setup and detailed examples of each feature.
  • Consult the API Reference Documentation (link to your full API docs if available) for in-depth information on all modules, methods, and data types.
  • Browse the examples folder in our SDK repository on GitHub (link to specific folder if applicable) for practical implementation patterns.
  • Visit the Sphere Developer Portal (link to your main developer portal) for comprehensive resources, guides, and community interaction.

We're thrilled to support your development efforts and can't wait to see the innovative applications you build with Sphere! If you have questions or feedback, join our Discord community or raise an issue on GitHub.