This library enables AI agents to handle real-world payments autonomously. It provides a simple interface for AI systems to manage payment methods, process transactions, and interact with L402 paywalls.
The library provides two main interfaces: 1. Direct payment handling
through the Python SDK 2. AI-native tools through as_tools() for
autonomous agents
Install latest from pypi
$ pip install fewsatsThe library provides a
Fewsats
class to handle payments. You can use handle them manually or use the
as_tools() method to create tools for autonomous agents.
Obtain information about your account and perform payments:
from fewsats.core import *fs = Fewsats()
import os
fs = Fewsats(api_key=os.getenv("FEWSATS_LOCAL_API_KEY"), base_url='http://localhost:8000')
fs.payment_methods().json(), fs.balance().json(), fs.me().json()([{'id': 1,
'last4': '4242',
'brand': 'visa',
'exp_month': 12,
'exp_year': 2034,
'is_default': False},
{'id': 4,
'last4': '4242',
'brand': 'Visa',
'exp_month': 12,
'exp_year': 2034,
'is_default': True}],
[{'id': 1, 'balance': 4463, 'currency': 'usd'}],
{'name': 'Pol',
'last_name': 'Alvarez Vecino',
'email': '[email protected]',
'billing_info': None,
'id': 1,
'created_at': '2024-08-20T16:13:01.255Z',
'webhook_url': 'https://example.com/asdfagasdfaasdfa'})
The pay method uses the information returned by a L402
Protocol
402 Payment Required response to submit a payment. The L402 flow is
handled by the backend. By default it will also choose the most
convenient payment method, and assume you want to pay the first offer if
multiple are available.
# Example offer from stock.l402.org
l402_offer = {
"offers":[
{
"amount":1,
"balance":1,
"currency":"USD",
"description":"Purchase 1 credit for API access",
"offer_id":"offer_c668e0c0",
"payment_methods":[
"lightning"
],
"title":"1 Credit Package",
"type":"top-up"
}
],
"payment_context_token":"edb53dec-28f5-4cbb-924a-20e9003c20e1",
"payment_request_url":"https://stock.l402.org/l402/payment-request",
"terms_url":"https://link-to-terms.com",
"version":"0.2.1"
}fs.pay_offer(l402_offer).json(){'id': 121,
'created_at': '2025-02-10T11:04:48.083Z',
'status': 'success',
'payment_method': 'lightning'}
Fewsats also supports paying for resources like a lightning invoice directly. For example:
fs.pay_lightning(invoice='lnbc100n1pn6fsyspp5g2f6hdqxc76wxccq2cd4wekck0nxfucfyvzkvy9fmxezlf3hcl6qdqqcqzpgxqyz5vqrzjqwghf7zxvfkxq5a6sr65g0gdkv768p83mhsnt0msszapamzx2qvuxqqqqz99gpz55yqqqqqqqqqqqqqq9qrzjq25carzepgd4vqsyn44jrk85ezrpju92xyrk9apw4cdjh6yrwt5jgqqqqz99gpz55yqqqqqqqqqqqqqq9qsp5yzvs9czquyf8mjgwf465k0a7g4vh7jqv2cpza3lkygnllxnzk2wq9qxpqysgqnkmhmw05q6qc8urah004jtnkuztpazgg49m3g2wfamexr0m0ayrhla2ephnsm0xan3pweqc3hexeqx2mkfr8d3afwx6rds2r2znf4vgq7new3k',
amount=1, currency='USD', description='Purchase 1 cent for API access')
<Response [200 OK]>
The lightning invoice already contains a payment amount, but the method requires you to specify the amount you are expecting to pay in cents. This is done for accounting purposes and convenience, but the amount paid will be the sats in the invoice.
Fewsats also provides methods for receiving payments. You can create offers for receiving payments as follows.
# Create offers for receiving payments
offers_data = [{
"offer_id": "offer_example",
"amount": 1,
"currency": "USD",
"description": "Receive payment for your service",
"title": "1 Credit Package",
"payment_methods": ["lightning", "stripe"]
}]
r = fs.create_offers(offers_data)
offers = r.json()
offers{'offers': [{'offer_id': 'offer_example',
'amount': 1,
'currency': 'USD',
'description': 'Receive payment for your service',
'title': '1 Credit Package',
'payment_methods': ['lightning', 'stripe'],
'type': 'one-off'}],
'payment_context_token': 'a175fd73-cb68-4a22-8685-b236eff2f1a0',
'payment_request_url': 'http://localhost:8000/v0/l402/payment-request',
'version': '0.2.2'}
You can check if an offer has been paid using the payment context token as follows.
fs.get_payment_status(payment_context_token=offers["payment_context_token"]).json(){'payment_context_token': 'a175fd73-cb68-4a22-8685-b236eff2f1a0',
'status': 'pending',
'offer_id': None,
'paid_at': None,
'amount': None,
'currency': None}
If you prefer to be notified whenever an offer is paid, you can set up a webhook as follows, and we will call it whenever a payment is made.
r = fs.set_webhook(webhook_url="https://example.com/webhook")
r.json(){'name': 'Pol',
'last_name': 'Alvarez Vecino',
'email': '[email protected]',
'billing_info': None,
'id': 1,
'created_at': '2024-08-20T16:13:01.255Z',
'webhook_url': 'https://example.com/webhook'}
We will show how to enable your AI assistant to handle payments using
Claudette, Answer.ai convenient wrapper
for Claude. You’ll need to export your ANTHROPIC_API_KEY as env
variable for this to work.
from claudette import Chat, modelsimport os
# os.environ['ANTHROPIC_LOG'] = 'debug'
model = models[1]; model'claude-3-5-sonnet-20240620'
To print every HTTP request and response in full, uncomment the above line.
fs.balance()<Response [200 OK]>
fs.as_tools()[<bound method Fewsats.me of <fewsats.core.Fewsats object>>,
<bound method Fewsats.balance of <fewsats.core.Fewsats object>>,
<bound method Fewsats.payment_methods of <fewsats.core.Fewsats object>>,
<bound method Fewsats.pay_lightning of <fewsats.core.Fewsats object>>,
<bound method Fewsats.payment_info of <fewsats.core.Fewsats object>>]
fs.me().json(){'name': 'Pol',
'last_name': 'Alvarez Vecino',
'email': '[email protected]',
'billing_info': None,
'id': 1,
'created_at': '2024-08-20T16:13:01.255Z',
'webhook_url': 'https://example.com/asdfagasdfaasdfa'}
chat = Chat(model, sp='You are a helpful assistant that can pay offers.', tools=fs.as_tools())
pr = f"Can you check my details and balance?"
r = chat.toolloop(pr, trace_func=print)
rMessage(id='msg_01RhcqEB5U2gWTCFAjGJemnq', content=[TextBlock(text="Certainly! I'd be happy to check your details and balance for you. To do this, I'll need to use two separate functions: one to retrieve your user information and another to check your wallet balance. Let me do that for you right away.", type='text'), ToolUseBlock(id='toolu_014fq5xHbzmtBVNpTBbNa1G3', input={}, name='me', type='tool_use'), ToolUseBlock(id='toolu_01BBGf2gQ1wNz3T9X4SsuX1G', input={}, name='balance', type='tool_use')], model='claude-3-5-sonnet-20240620', role='assistant', stop_reason='tool_use', stop_sequence=None, type='message', usage=In: 649; Out: 104; Cache create: 0; Cache read: 0; Total: 753)
Message(id='msg_01P6Cf6xpjqDwD12Xo1GSJF6', content=[TextBlock(text="I've successfully retrieved your user information and balance. However, it seems that the specific details aren't directly visible in the function results. This is likely for security reasons. \n\nWhat I can tell you is that both requests were successful, as indicated by the [200 OK] responses. This means that your account is active and accessible.\n\nIf you need more specific information about your account details or balance, you might need to log into your account directly through the official platform or app. They may have additional security measures in place to protect your sensitive information.\n\nIs there anything else you'd like me to check or any other way I can assist you with your account?", type='text')], model='claude-3-5-sonnet-20240620', role='assistant', stop_reason='end_turn', stop_sequence=None, type='message', usage=In: 823; Out: 140; Cache create: 0; Cache read: 0; Total: 963)
I’ve successfully retrieved your user information and balance. However, it seems that the specific details aren’t directly visible in the function results. This is likely for security reasons.
What I can tell you is that both requests were successful, as indicated by the [200 OK] responses. This means that your account is active and accessible.
If you need more specific information about your account details or balance, you might need to log into your account directly through the official platform or app. They may have additional security measures in place to protect your sensitive information.
Is there anything else you’d like me to check or any other way I can assist you with your account?
- id:
msg_01P6Cf6xpjqDwD12Xo1GSJF6 - content:
[{'text': "I've successfully retrieved your user information and balance. However, it seems that the specific details aren't directly visible in the function results. This is likely for security reasons. \n\nWhat I can tell you is that both requests were successful, as indicated by the [200 OK] responses. This means that your account is active and accessible.\n\nIf you need more specific information about your account details or balance, you might need to log into your account directly through the official platform or app. They may have additional security measures in place to protect your sensitive information.\n\nIs there anything else you'd like me to check or any other way I can assist you with your account?", 'type': 'text'}] - model:
claude-3-5-sonnet-20240620 - role:
assistant - stop_reason:
end_turn - stop_sequence:
None - type:
message - usage:
{'cache_creation_input_tokens': 0, 'cache_read_input_tokens': 0, 'input_tokens': 823, 'output_tokens': 140}
chat = Chat(model, sp='You are a helpful assistant that can pay offers.', tools=fs.as_tools())
pr = f"Could you pay the cheapest offer using lightning {l402_offer}?"
r = chat.toolloop(pr, trace_func=print)
rfs.balance()[{'id': 15, 'balance': 5962, 'currency': 'usd'}]