fewsats 0.0.5

Python SDK for Fewsats Hub

fewsats

What’s this all about?

L402 enables internet-native payments using the HTTP status code 402 Payment Required. It’s built on the Lightning Network, a layer on top of Bitcoin, making it extremely fast. But there’s a catch: not many people have Bitcoin to spend.

That’s where Hub comes in. It lets you use dollars to buy L402 links, keeping the advantages of L402 without needing cryptocurrency.

This library helps your AI agents leverage Hub to access paywalled content programmatically. No crypto knowledge required.

Install

pip install fewsats

How to use

Before using the library, you need to sign up at https://paywithhub.com. Verify your email, and then generate an API key.

First, import the Fewsats class:

from fewsats import Fewsats

Initialize the Fewsats client:

client = Fewsats(api_key="nJ2ro5V9x69JDEhEGyjnzfg6kTkk4LQjukIbfDmuOec",
                 base_url="http://localhost:8000")
# Leave base_url blank to use the default production URL
# You can also set the HUB_API_TOKEN environment variable instead of passing the api_key directly

Get Payment Methods

You can retrieve the user’s payment methods using the get_payment_methods method:

payment_methods = client.get_payment_methods()
payment_methods

[{'id': 1,
  'last4': '4242',
  'brand': 'visa',
  'exp_month': 12,
  'exp_year': 2034,
  'is_default': True}]

Note: The default payment method is always used when making purchases.

Preview a purchase

You can preview a purchase using the preview_purchase method:

l402_url = "https://api.fewsats.com/v0/storage/download/de8d4c19-5a88-47fc-afa1-e514b1cdc9e8"
preview = client.preview_purchase(l402_url)
preview

{'invoice': {'description': 'LN Nodes by Median Fee',
  'amount_usd': 99,
  'amount_btc': 1686,
  'macaroon': 'AgELZmV3c2F0cy5jb20CQgAAXTNbwmnvNDOZX9MinU0glsObHI02zniMY1EBsvQCKDEDNlwDmu8HNIZuHE6U1rVDNLWk8CBlqtewn8NAfr360wACLGZpbGVfaWQ9ZGU4ZDRjMTktNWE4OC00N2ZjLWFmYTEtZTUxNGIxY2RjOWU4AAIfZXhwaXJlc19hdD0yMDI1LTA4LTI0VDE4OjQ3OjE2WgAABiAtmy8gDmcF9dL930VqQItQILckZ5xtdfSmYpQWgcPuRg==',
  'invoice': 'lnbc16860n1pndps35pp5t5e4hsnfau6r8x2l6v3f6nfqjmpek8ydxm883rrr2yqm9aqz9qcsdpyf38zqnn0v3jhxgrz0ysy6etyd9skugzxv4jscqzzsxqyz5vqsp5gn24te60qayyzqcxq6fyp58ukvtl69jqyujsmrfd2kxe2dwxwfeq9qxpqysgq36lfzryhz97jdhhzg05xlq05p30u36g6lr0p2ch7unu79dmg2w7kdeza4h8e8md7y3w2zxk862xu9ztue69f2mrnyrmlq95685py6rsqc3awvr'},
 'transaction': {'current_balance': 1999,
  'balance_to_apply': 99,
  'amount_to_charge': 0,
  'final_balance': 1900},
 'already_purchased': False,
 'purchase': None}

Make a purchase

To make a purchase, use the purchase method:

purchase = client.purchase(l402_url)
purchase

{'id': 3,
 'created_at': '2024-08-28T14:47:26.904Z',
 'l402_url': 'https://api.fewsats.com/v0/storage/download/2e54ac29-5945-4b5f-93db-998a535a5a49',
 'macaroon': 'AgELZmV3c2F0cy5jb20CQgAADkZv2VQjgOG+iwoFB5CXg5yInkncy5xEGQZKrkphETmU9+MjeNM4bsj1j5l5KKvildd2pHdtrW+ChXQOQ/fZzgACLGZpbGVfaWQ9MmU1NGFjMjktNTk0NS00YjVmLTkzZGItOTk4YTUzNWE1YTQ5AAIfZXhwaXJlc19hdD0yMDI1LTA4LTIzVDE0OjQ3OjI1WgAABiBIoB5sUXEXijxuyL2cjn0WIgLpOCtt8UcGaGn9N/8n0Q==',
 'invoice': 'lnbc170n1pnv7wrapp5perxlk25ywqwr05tpgzs0yyhswwg38jfmn9ec3qeqe92ujnpzyusdq024f5kgzgda6hxegcqzzsxqyz5vqsp54ceypjapjxntxrtnhkyfrds7m5u9stn8x6gkmf5dx6z56ksy6l3q9qxpqysgqnkxdtwqxhkvrav3d3wv83yxn45yrdywxu2mnyh4p7ecncuqsv4gn0xrfl6w57hd9lnc5eghdf536dqy5gf2uuly04nrtdjcwvezkt6cqtttnzj',
 'preimage': 'b184b87e7a4f802bf41cd26c82d9d883b9cf7bb86f8dcfc4f394634ff711f628',
 'amount': 1,
 'currency': 'usd',
 'description': 'USK House'}