API Endpoints

Introduction

Sphere is a payments API for digital currencies.

Overview

Sphere's mission is to accelerate the development of digital currencies.

To enable people from around the world to transact on cheaper, faster, and more accessible payment rails, we've begun with stablecoins and other digital currencies on decentralized networks.

Sphere provides an end-to-end payments experience — from on-ramp, to multi-chain and fiat transactions, to off-ramp — with best-in-class compliance, accounting, taxes, tooling, and billing reconciliation.

Pricing

0.3% flat fee on all payments, excluding network fees (wire, gas, etc.) which we pass at cost.

Features

We support one-time and recurring billing through payment links and subscriptions.

You have the flexibility to create your own frontend and UX, or use our pre-built checkout pages.

For subscriptions, you may choose between:

  1. Escrowed, where funds are locked up and periodically withdrawn from (traditional).
  2. Escrowless, where funds are automatically withdrawn from your customer's wallet each billing period.

Subscriptions don't require wrapping and unwrapping of tokens.

We support a variety of pricing models: including flat, per-seat, volume, graduated, and customer chooses.

Automated Invoices will be rolled out in Q1 2024.

Smart contracts are natively held on Solana and Ethereum. L2s, and side-chains coming soon.

How it works

Sphere uses three core objects for payments:

  1. product — the goods and services you're selling.
  2. price — the cost, defined by amount and currency, of those products.
  3. paymentLink or invoice — the payment method for a given set of product and price.

Fundamentally, you as the developer will:

  1. Create a product.
  2. Create and attach a price to your product.
  3. Create a paymentLink or invoice and attach them to a given set of product and price.
  4. The API will respond with a url for a pre-built checkout to redirect customers to, or build your own.
  5. A payment object will be auto-generated when a customer tries to pay.
  6. Create a webhook and listen for events on the payment object to carry out your business logic.

And that's it! Our guides give more details on specific examples and more complex use cases.

Important

Payments

A payment object is auto-generated each time a customer tries to pay for one of your products through a payment method — whether one-time vs. recurring, or via payment link vs. invoice.

It contains key information about the purchase, such as the customer, transaction, and involved line items, for you to consume on your backend and apply the appropriate business logic upon a purchase.

Subscriptions

subscription objects are auto-generated when your customers purchase products with a recurring price. Developers do not need to create subscription objects on their own.

This object contains useful information about the subscription, such as the remaining number of billing periods, amounts billed, and the start-and-end date of the current period.

At the end of each billing period, the subscription objects are billed by Sphere, and payment objects are created to record the recurring withdrawals from either the escrow account or customer wallet address.

If you are using metered billing, then you will need to submit usage records to bill for usage.

Webhooks

Webhooks are available for you to listen to a wide selection of events. For example, you may listen to the payment.successful event to credit a customer on your backend after a successful purchase.

Meta Fields

If there is additional information you'd like to include in a given object, for your own reference or to use later elsewhere, we provide a meta field for storing arbitrary JSON in most of our objects.

Some use-cases could be to include your own pre-existing id tags for reconciliation purposes, or to temporarily reference during a user flow instead of creating a new data model inside of your database.

Real-Time Price Updates

Sphere uses the Pyth oracle network to provide real-time updated price data to our smart contracts across all major supported chains. Whenever one of our programs that you invoke via API, or in select cases directly via cross-smart contract call, requires an exchange rate (e.g., to correctly price HNT/USDC), Pyth's streamed updates guarantee best pricing.