subscription.subscribe

Create USDC subscriptions with spend permissions on Base network

Defined in the Base Account SDK

The subscribe function creates recurring USDC subscriptions using spend permissions on the Base network. This enables you to charge users periodically without requiring approval for each transaction. No fees for merchants or users.

Parameters

recurringCharge · string · required

Amount of USDC to charge per period (e.g., “10.50”). Maximum 6 decimal places.

subscriptionOwner · string · required

Ethereum address that will be the spender (your application’s address).

Pattern: ^0x[0-9a-fA-F]{40}$

periodInDays · number

The period in days for the subscription (e.g., 30 for monthly). Default: 30

testnet · boolean

Set to true to use Base Sepolia testnet instead of mainnet. Default: false

requireBalance · boolean

Check if the payer’s wallet has sufficient USDC balance before creating the subscription. If true, subscription creation will fail if the payer doesn’t have enough balance to cover the recurring charge. Default: true

telemetry · boolean

Whether to enable telemetry logging. Default: true

Returns

result · SubscriptionResult

Subscription details on success. The function throws an error on failure.

Show SubscriptionResult properties

id · string

The subscription ID (permission hash) - use this to manage the subscription.

subscriptionOwner · Address

Address that controls the subscription (your application).

subscriptionPayer · Address

Address that will be charged (the user).

recurringCharge · string

Recurring charge amount in USD.

periodInDays · number

Period in days for the subscription.

Errors

The subscribe function throws an error when subscription creation fails. The error object contains a message explaining what went wrong.

Basic Subscription

import { base } from '@base-org/account';

try {
  const subscription = await base.subscription.subscribe({
    recurringCharge: "9.99",
    subscriptionOwner: "0xYourSubscriptionOwnerWallet",
    periodInDays: 30
  });
  
  console.log(`Subscription ID: ${subscription.id}`);
  console.log(`Payer: ${subscription.subscriptionPayer}`);
  console.log(`Monthly charge: $${subscription.recurringCharge}`);
} catch (error) {
  console.error(`Subscription failed: ${error.message}`);
}

Success Response

{
  id: "0x71319cd488f8e4f24687711ec5c95d9e0c1bacbf5c1064942937eba4c7cf2984",
  subscriptionOwner: "0xYourSubscriptionOwnerWallet",
  subscriptionPayer: "0x742d35Cc4Bf53E0e6C42E5d9F0A8D2F6D8A8B7C9",
  recurringCharge: "9.99",
  periodInDays: 30
}

Error Handling

Always wrap calls to subscribe in a try-catch block:

try {
  const subscription = await base.subscription.subscribe({
    recurringCharge: "19.99",
    subscriptionOwner: "0xYourSubscriptionOwnerWallet",
    periodInDays: 30
  });
  // Subscription created successfully
  saveSubscriptionId(subscription.id); // Save for future charges
} catch (error) {
  // Handle subscription failure
  console.error(`Failed to create subscription: ${error.message}`);
}