Skip to content

Instantly share code, notes, and snippets.

Show Gist options
  • Select an option

  • Save pamorgan01/a04604fac866b4384b51c9acd36708b2 to your computer and use it in GitHub Desktop.

Select an option

Save pamorgan01/a04604fac866b4384b51c9acd36708b2 to your computer and use it in GitHub Desktop.
Technical deep dive on Solana Native Subscriptions and Allowances

Solana Native Subscriptions and Allowances: A Technical Deep Dive for Agentic Commerce

Executive summary

Solana's native Subscriptions and Allowances primitive turns recurring billing and bounded delegated spending into shared on-chain infrastructure. Instead of every SaaS app, API provider, AI-agent operator, or payroll product writing its own token approval and billing logic, the ecosystem now has a common program for three related payment patterns:

  1. Fixed allowances: a user authorizes a delegate to spend up to a fixed cap, optionally before an expiry.
  2. Recurring delegations: a user authorizes a delegate to spend up to a per-period cap that resets each cycle.
  3. Subscription plans: a merchant publishes billing terms, subscribers accept them, and authorized pullers collect according to the plan.

The most interesting part is not simply recurring payments. It is the separation between custody and permission. A user can keep custody of funds while giving a merchant, payroll counterparty, or autonomous agent a constrained right to pull funds under rules that are explicit, auditable, and revocable.

For AI agents, this is the missing budget rail: instead of handing an agent a funded hot wallet, a user can grant an allowance. The agent can act, but only inside the amount, expiry, token account, and delegation constraints the user approved.

Why this primitive matters now

Recurring revenue is ordinary in Web2. SaaS subscriptions, API credits, media plans, payroll, contractor retainers, and pay-as-you-go data products all rely on recurring or pre-authorized payments. On-chain payments have historically struggled here because wallets are designed around explicit user approvals. That is safe, but repetitive.

The new Solana primitive changes the integration pattern. The Solana announcement describes a shared audited program for recurring billing, delegated spending, and subscription plans, live on mainnet and designed to avoid custom billing infrastructure. The official repository describes the program as managed token delegations for SPL Token and Token-2022.

That matters because reusable payment primitives compound. Once wallet UIs, indexers, merchants, agents, and accounting tools understand the same delegation model, each new integration becomes cheaper and safer.

Architecture: one authority, many delegations

The official solana-foundation/subscriptions repository explains the core design: for each (user, mint) pair, the program creates a Subscription Authority PDA and sets that PDA as the single delegate on the user's token account with a high approval. That sounds broad at first, but the key safety property is that the Subscription Authority can only transfer tokens when a Delegation PDA authorizes the specific movement.

In plain terms:

  • The user's token account keeps one program-controlled delegate: the Subscription Authority.
  • Individual business relationships are represented by delegation accounts.
  • Transfer instructions check the relevant delegation account before moving funds.
  • Multiple simultaneous relationships can coexist without requiring multiple raw token delegates on the same token account.

This design solves a practical SPL Token limitation: token accounts normally have a single delegate. Without an intermediate program authority, multiple subscription merchants or agent allowances would fight over that one delegate slot. The Subscription Authority PDA becomes a controlled routing layer, while delegation PDAs encode who may pull, how much, and under what cadence.

The official program ID currently documented by the repository is:

De1egAFMkMWZSN5rYXRj9CAdheBamobVNubTsi9avR44

The three payment models

1. Fixed delegation / allowance

A fixed delegation authorizes a delegatee to spend up to a total amount. It may expire. This is the simplest model and the most useful for bounded AI-agent spending.

Example: a user grants an analytics agent a 25 USDC allowance for a week. The agent can buy API calls, pay for small data lookups, or purchase content access, but it cannot exceed the cap. If the agent becomes buggy or malicious, the remaining allowance can be revoked or allowed to expire.

Good use cases:

  • AI-agent tool budgets
  • prepaid API usage
  • per-project contractor budget envelopes
  • one-time merchant checkout with delayed fulfillment
  • capped content micropayments

2. Recurring delegation

A recurring delegation adds a period and reset behavior. The delegate can pull up to a configured amount each cycle. This is useful where the relationship is ongoing but should remain bounded.

Example: a company authorizes a contractor to pull up to 1,000 USDC every two weeks after deliverables are approved. The cap resets each period, making it closer to payroll or retainer logic than a one-time budget.

Good use cases:

  • payroll and contractor retainers
  • recurring AI-agent operating budgets
  • per-month API credits
  • recurring creator payments
  • spend controls for teams or departments

3. Subscription plan

A subscription plan is merchant-centric. The merchant publishes a plan with terms, the subscriber accepts those terms, and authorized pullers can collect according to the plan. Plan terms are snapshotted at subscribe time, which matters for consumer trust: a merchant changing its public plan later should not silently change what an existing subscriber accepted.

Good use cases:

  • SaaS tiers
  • paid API plans
  • stablecoin invoice collection
  • membership products
  • on-chain media subscriptions

TypeScript client surface

The repository documents a TypeScript client package, @solana/subscriptions, with a high-level SubscriptionsClient. The listed methods show the operational shape of the program:

  • initSubscriptionAuthority and closeSubscriptionAuthority
  • createFixedDelegation and transferFixed
  • createRecurringDelegation and transferRecurring
  • createPlan, updatePlan, and deletePlan
  • subscribe, cancelSubscription, resumeSubscription, and transferSubscription
  • revokeDelegation
  • query helpers such as getDelegationsForWallet, getPlansForOwner, and isSubscriptionAuthorityInitialized

That surface is useful because it makes the primitive feel like application infrastructure, not a research artifact. A builder should be able to model a payment relationship, call the client, and then let wallets/indexers display the resulting state.

What gets better than custom approvals

Better UX

A user should not have to approve every monthly SaaS invoice manually. They also should not have to give a merchant or agent unlimited authority. Subscriptions and allowances allow the middle path: approve a bounded relationship once, then let expected payments happen.

Better safety for agents

The agent story is the strongest. A funded agent wallet is a custody risk. A delegated allowance is a permission risk, and permission risk is easier to bound. The user can define the maximum loss before the agent acts.

A healthy agent stack could combine:

  • a fixed delegation for a weekly operating budget
  • a local policy engine that rejects unexpected merchants or programs
  • a recurring delegation for routine service costs
  • human review for anything over a threshold
  • automatic revocation after abnormal behavior

Better accounting

Because the relationship is represented on-chain, indexers can attribute pulls to plans or delegations rather than treating every token transfer as an opaque payment. This helps merchants, DAOs, accounting tools, and compliance workflows.

Better composability

The program supports SPL Token and Token-2022, and the repository notes integration tests for Squads multisig and Swig smart wallet flows. That is important because real users often do not hold funds in a simple keypair wallet. Team spending and agent spending both need smart-wallet compatibility.

Tradeoffs and risks

1. Delegated spending still needs clear wallet UX

A technically safe delegation can still be dangerous if users do not understand it. Wallets should show:

  • delegate identity
  • token mint
  • total cap or per-period cap
  • expiry
  • merchant or plan identity
  • revoke action
  • historical pulls

Without a good wallet interface, users may treat a capped delegation as either scarier or safer than it really is.

2. Merchants need failure handling

Pull payments can fail. The user's balance may be too low. The delegation may be expired or revoked. A recurring cap may already be consumed for the period. Merchants need retry, dunning, grace periods, and clear account states.

This is normal in billing, but on-chain systems make failures more explicit and less reversible.

3. Agents need policy above the primitive

The primitive limits amount and cadence. It does not understand intent. An allowance can stop an agent from overspending, but it cannot know whether a particular API call, swap route, or merchant is wise. Agent operators still need policy engines, allowlists, risk scoring, simulation, and human escalation.

4. Rent and account lifecycle matter

The repository documents rent costs for creating Subscription Authorities, plans, and delegation accounts. Rent is recoverable when accounts are closed, but builders still need to handle account lifecycle cleanly. Otherwise, users will accumulate stale accounts and confusing state.

5. Indexing is not optional for good products

Events and account state make the primitive inspectable, but production-grade apps need indexers. Users and merchants will expect dashboards: active plans, upcoming renewals, remaining allowance, failed pulls, and revocations.

New businesses this enables

Agent app stores with capped spend

An agent marketplace can let users install paid skills with per-skill allowances. The user might authorize 10 USDC/month for research APIs, 5 USDC/week for image generation, and 50 USDC/month for execution tools. The agent can work autonomously without holding the user's wallet.

On-chain API subscriptions

The Solana announcement mentions pay.sh as a pay-as-you-go API layer. Subscriptions and allowances let an API provider offer recurring access tiers or bounded per-call budgets. This is a clean fit for AI agents that need to discover services, call them, and settle in stablecoins.

Contractor retainers

A DAO or startup can authorize recurring payments to a contributor under a defined cap. If the contributor relationship ends, the payer cancels the delegation. If the contributor over-delivers, the payer can raise the cap with a new authorization.

Usage-based media

Content products can offer a monthly allowance for articles, datasets, or video access. Users avoid a full subscription commitment, while publishers get a programmable spending relationship.

Canadian relevance

Shopify-style merchant subscriptions

Canada has deep commerce infrastructure. A Shopify-like merchant stack could use Solana subscription plans for stablecoin-denominated recurring commerce: memberships, replenishment products, creator subscriptions, and B2B software. The interesting part is not replacing every card payment; it is serving merchants and customers who already operate globally and want stablecoin settlement.

Cohere-style AI agent budgets

Canadian AI companies and agent platforms need safe tool-use budgets. A model-powered agent that can purchase data, call APIs, or trigger workflows should not hold an unconstrained hot wallet. Fixed allowances and recurring delegations are a practical budget layer for that world.

Wealthsimple-style personal finance controls

Canadian fintech products could expose recurring delegations as user-visible spending controls: subscriptions, family allowances, payroll-like payouts, and automated savings flows. The product challenge would be clean UX and strong consumer protection language.

Canadian creator and media businesses

Canadian media and creator communities could use allowances for pay-per-read or monthly content budgets. Instead of forcing every reader into a full subscription, a publication could let users authorize a small monthly stablecoin allowance and draw per article.

Implementation checklist for builders

  1. Decide which model fits the relationship: fixed allowance, recurring delegation, or subscription plan.
  2. Initialize the user's Subscription Authority for the relevant mint if needed.
  3. Create the delegation or subscription account with explicit cap, period, expiry, and recipient semantics.
  4. Surface the delegation in product UI with revoke and history controls.
  5. Use transferFixed, transferRecurring, or subscription transfer flows only after local product checks pass.
  6. Index events and account state for billing dashboards.
  7. Build failure handling for expired, revoked, depleted, or underfunded delegations.
  8. For agents, add a policy layer above the primitive: merchant allowlists, per-action limits, simulation, anomaly detection, and human escalation.

A concrete agent pattern

A safe agent wallet architecture can look like this:

User wallet
  -> grants fixed 25 USDC weekly allowance
  -> Subscription Authority PDA controls transfer route
  -> Fixed Delegation PDA defines cap and expiry
  -> Agent proposes action
  -> Local policy checks merchant/category/slippage
  -> If safe, transferFixed executes
  -> If suspicious, action is rejected or escalated

This gives the agent autonomy without giving it custody. That distinction is the heart of the primitive.

Final take

Solana Native Subscriptions and Allowances are not just a billing feature. They are a permission system for money movement. The immediate market is SaaS and API billing, but the bigger unlock is autonomous commerce: agents can spend, merchants can collect, and users can remain in control.

The primitive will succeed if wallets, SDKs, indexers, and application developers make the delegation state easy to understand. The chain can enforce caps and periods. Products still need to explain them.

Sources

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment