With Pay.sh

You can set up subscriptions via Pay.sh by setting up a Pay client on your device or by setting up a Pay server. Install Pay with:

brew install pay

or

npm install -g @solana/pay

Verify the installation with:

pay --version

The toolchain will set up your address for you. Run the following to setup and topup your wallet:

pay setup

Subscriptions as a client

Users subscribe to subscription-gated API endpoints by invoking pay like normal. It is on the API to send the subscription details in the initial 402 Status Response. Pay handles the subscription automatically, including instruction invocation on the Solana SPL Subscriptions Program.

Users can manage their subscriptions using the following commands:

pay subscriptions                       # default: list + show available subcommands
pay subscriptions list                  # same, scriptable
pay subscriptions list --network mainnet
pay subscriptions list --json

You can learn more about managing your subscriptions as a user in the Pay.sh > Using Pay > Manage Subscriptions docs.

Managing subscriptions as a provider (demo)

Pay servers allow for configuring subscribers and their subscriptions for each endpoint. The following is an endpoint example that uses pay you can try with your project:

# monthly.yml
name: Subscriptions Example
subdomain: subscriptions-example
title: "Subscription Example"
description: "Demo Subscriptions"
category: ai_ml
version: v1
routing:
  type: respond
operator:
  currencies:
    usd: ["USDC", "USDT", "CASH"]
  network: "localnet"
  fee_payer: true
  challenge_binding_secret: d858d9104afd728f58a1f73d806dd75d8f32ebd37c9707145816b490e8631d41
  # insert your own challenge_binding_secret here. use `openssl rand -hex 32`

endpoints:
  - method: GET
    path: "api/v1/pro/feed"
    resource: "pro-feed"
    description: "Pro feed — monthly subscription, 30-day billing period."
    subscription:
      period: "30d"
      price_usd: 9.99
      currency: USDC
      plan_id_numeric: 1

Pay handles subscriptions using the subscription: attribute in its endpoints YAML specification. This is opposed to the metering: attribute for pay-per-use endpoints.

Starting the server in the above example creates an endpoint called api/v1/pro/feed that requires a user to make recurring payments of 9.99 USDC to it every 30 days.

You can try it by running the following command:

pay server start monthly.yml

Running this command will prompt you to create a plan. This creates a plan and updates the yml file. If you're going to use it again, remember the plan address and use that in your config as you're making changes.

You can test that the subscriptions work by running the following commands as a client on another terminal:

# First call — activates the subscription, $9.99 USDC charge settles.
pay --sandbox curl http://127.0.0.1:1402/api/v1/pro/feed

# Same call within 30 days — no payment prompt, just the response.
pay --sandbox curl http://127.0.0.1:1402/api/v1/pro/feed

You should see an OK status as a response like this:

{ "status": "ok" }

You can learn more about managing subscriptions on a Pay server via the Pay.sh > Building with Pay > Subscriptions > YAML Specification docs.