# fewsats
<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
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
Install latest from the GitHub
[repository](https://github.com/Fewsats/fewsats-python):
``` sh
$ pip install git+https://github.com/Fewsats/fewsats-python.git
```
or from [pypi](https://pypi.org/project/fewsats-python/)
``` sh
$ pip install fewsats
```
## Getting Started
The library provides a
[`Client`](https://Fewsats.github.io/fewsats-python/core.html#client)
class to handle payments. You can use handle them manually or use the
`as_tools()` method to create tools for autonomous agents.
``` python
from fewsats.core import *
```
``` python
fs = Client()
fs.payment_methods()
```
[{'id': 5,
'last4': '4242',
'brand': 'Visa',
'exp_month': 12,
'exp_year': 2034,
'is_default': True}]
``` python
fs.balance()
```
[{'id': 15, 'balance': 6471, 'currency': 'usd'}]
``` python
fs.me()
```
{'name': 'Fewsats',
'last_name': 'Tester',
'email': 'test@fewsats.com',
'billing_info': None,
'id': 15,
'created_at': '2024-12-18T18:19:00.531Z'}
The `pay` method uses the information returned by a [L402
Protocol](https://github.com/l402-protocol/l402?tab=readme-ov-file#402-response-format)
`402 Payment Required` response to submit a payment.
``` python
# Example offer from stock.l402.org
ofs = {
"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"
}
```
``` python
fs.pay(ofs['payment_request_url'], ofs['payment_context_token'], **ofs['offers'][0], pm='lightning')
```
{'id': 240,
'created_at': '2024-12-26T10:24:03.486Z',
'status': 'success',
'payment_request_url': 'https://stock.l402.org/l402/payment-request',
'payment_context_token': 'edb53dec-28f5-4cbb-924a-20e9003c20e1',
'invoice': 'lnbc100n1pnk6tkrpp5pkshrxfyvxuqphwxvax8dfaemhh287lnefrjr68cy494fppe5l0sdq6xysyxun9v35hggzsv93kkct8v5cqzpgxqrzpnrzjqwghf7zxvfkxq5a6sr65g0gdkv768p83mhsnt0msszapamzx2qvuxqqqqz99gpz55yqqqqqqqqqqqqqq9qrzjq25carzepgd4vqsyn44jrk85ezrpju92xyrk9apw4cdjh6yrwt5jgqqqqz99gpz55yqqqqqqqqqqqqqq9qsp5070fsrfdknwpv2rfeju44k37uj362xcrzmey4se70kpzusy6c0pq9qxpqysgqcj990yc9lg5wje9u6myceakzff95q8qdwrslx69xh526y764dwlxt4v90qhwtmesukfaute6hkh9952t5f5gqjmrry3c6y0k7y2ltkcphyxfp2',
'preimage': '9de11f4b1bbaf9c18b8b28ee0747fdd64d124b7ee05090f4edc377e73393c2dc',
'amount': 1,
'currency': 'usd',
'payment_method': 'lightning',
'title': '1 Credit Package',
'description': 'Purchase 1 credit for API access',
'type': 'top-up'}
### AI Agent Integration
We will show how to enable your AI assistant to handle payments using
[Claudette](https://claudette.answer.ai), Answer.ai convenient wrapper
for Claude. You’ll need to export your `ANTHROPIC_API_KEY` as env
variable for this to work.
``` python
from claudette import Chat, models
```
``` python
import os
# os.environ['ANTHROPIC_LOG'] = 'debug'
```
To print every HTTP request and response in full, uncomment the above
line.
``` python
fs.balance()
```
[{'id': 15, 'balance': 6470, 'currency': 'usd'}]
``` python
chat = Chat(models[1], sp='You are a helpful assistant that can pay offers.', tools=fs.as_tools())
pr = f"Could you pay the cheapest offer using lightning {ofs}?"
r = chat.toolloop(pr, trace_func=print)
r
```
Message(id='msg_01SmWra463n6Q5wivTQS41B9', content=[TextBlock(text="Certainly! I can help you pay for the cheapest offer using Lightning. Based on the information you've provided, there's only one offer available, so we'll proceed with that one. Let's use the `pay` function to complete this transaction.\n\nFirst, let's organize the information we have:\n\n1. There's one offer for 1 credit at $0.01 (1 cent).\n2. The payment method is Lightning.\n3. We have a payment context token and a payment request URL.\n\nNow, let's call the `pay` function with the required parameters:", type='text'), ToolUseBlock(id='toolu_016nRMYdemRYBEuVq8JkWPe4', input={'purl': 'https://stock.l402.org/l402/payment-request', 'pct': 'edb53dec-28f5-4cbb-924a-20e9003c20e1', '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'}, name='pay', type='tool_use')], model='claude-3-5-sonnet-20240620', role='assistant', stop_reason='tool_use', stop_sequence=None, type='message', usage=In: 1002; Out: 395; Cache create: 0; Cache read: 0; Total: 1397)
Message(id='msg_011KopqDeH4CNLt8bKTLyGQD', content=[TextBlock(text="Great news! The payment has been successfully processed. Here's a summary of the transaction:\n\n1. Payment Status: Success\n2. Amount Paid: 1 cent (USD)\n3. Payment Method: Lightning\n4. Title: 1 Credit Package\n5. Description: Purchase 1 credit for API access\n6. Type: Top-up\n7. Transaction ID: 241\n8. Created At: 2024-12-26T10:24:13.845Z\n\nThe payment has been completed successfully, and you should now have 1 credit for API access added to your account. Is there anything else you would like to know about this transaction or any other assistance you need?", type='text')], model='claude-3-5-sonnet-20240620', role='assistant', stop_reason='end_turn', stop_sequence=None, type='message', usage=In: 1942; Out: 155; Cache create: 0; Cache read: 0; Total: 2097)
Great news! The payment has been successfully processed. Here’s a
summary of the transaction:
1. Payment Status: Success
2. Amount Paid: 1 cent (USD)
3. Payment Method: Lightning
4. Title: 1 Credit Package
5. Description: Purchase 1 credit for API access
6. Type: Top-up
7. Transaction ID: 241
8. Created At: 2024-12-26T10:24:13.845Z
The payment has been completed successfully, and you should now have 1
credit for API access added to your account. Is there anything else you
would like to know about this transaction or any other assistance you
need?
<details>
- id: `msg_011KopqDeH4CNLt8bKTLyGQD`
- content:
`[{'text': "Great news! The payment has been successfully processed. Here's a summary of the transaction:\n\n1. Payment Status: Success\n2. Amount Paid: 1 cent (USD)\n3. Payment Method: Lightning\n4. Title: 1 Credit Package\n5. Description: Purchase 1 credit for API access\n6. Type: Top-up\n7. Transaction ID: 241\n8. Created At: 2024-12-26T10:24:13.845Z\n\nThe payment has been completed successfully, and you should now have 1 credit for API access added to your account. Is there anything else you would like to know about this transaction or any other assistance you need?", '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': 1942, 'output_tokens': 155}`
</details>
``` python
fs.balance()
```
[{'id': 15, 'balance': 6469, 'currency': 'usd'}]
Raw data
{
"_id": null,
"home_page": "https://github.com/Fewsats/fewsats-python",
"name": "fewsats",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "nbdev jupyter notebook python",
"author": "Jordi Montes, Pol Alvarez",
"author_email": "jordi@fewsats.com, pol@fewsats.com",
"download_url": "https://files.pythonhosted.org/packages/07/f1/a6c0d39c6dd14ba5c809984d4d090336bbc77e1afc828959a57a79c0a909/fewsats-0.0.11.tar.gz",
"platform": null,
"description": "# fewsats\n\n\n<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->\n\nThis library enables AI agents to handle real-world payments\nautonomously. It provides a simple interface for AI systems to manage\npayment methods, process transactions, and interact with L402 paywalls.\n\nThe library provides two main interfaces: 1. Direct payment handling\nthrough the Python SDK 2. AI-native tools through `as_tools()` for\nautonomous agents\n\n## Install\n\nInstall latest from the GitHub\n[repository](https://github.com/Fewsats/fewsats-python):\n\n``` sh\n$ pip install git+https://github.com/Fewsats/fewsats-python.git\n```\n\nor from [pypi](https://pypi.org/project/fewsats-python/)\n\n``` sh\n$ pip install fewsats\n```\n\n## Getting Started\n\nThe library provides a\n[`Client`](https://Fewsats.github.io/fewsats-python/core.html#client)\nclass to handle payments. You can use handle them manually or use the\n`as_tools()` method to create tools for autonomous agents.\n\n``` python\nfrom fewsats.core import *\n```\n\n``` python\nfs = Client()\nfs.payment_methods()\n```\n\n [{'id': 5,\n 'last4': '4242',\n 'brand': 'Visa',\n 'exp_month': 12,\n 'exp_year': 2034,\n 'is_default': True}]\n\n``` python\nfs.balance()\n```\n\n [{'id': 15, 'balance': 6471, 'currency': 'usd'}]\n\n``` python\nfs.me()\n```\n\n {'name': 'Fewsats',\n 'last_name': 'Tester',\n 'email': 'test@fewsats.com',\n 'billing_info': None,\n 'id': 15,\n 'created_at': '2024-12-18T18:19:00.531Z'}\n\nThe `pay` method uses the information returned by a [L402\nProtocol](https://github.com/l402-protocol/l402?tab=readme-ov-file#402-response-format)\n`402 Payment Required` response to submit a payment.\n\n``` python\n# Example offer from stock.l402.org\nofs = {\n \"offers\":[\n {\n \"amount\":1,\n \"balance\":1,\n \"currency\":\"USD\",\n \"description\":\"Purchase 1 credit for API access\",\n \"offer_id\":\"offer_c668e0c0\",\n \"payment_methods\":[\n \"lightning\"\n ],\n \"title\":\"1 Credit Package\",\n \"type\":\"top-up\"\n }\n ],\n \"payment_context_token\":\"edb53dec-28f5-4cbb-924a-20e9003c20e1\",\n \"payment_request_url\":\"https://stock.l402.org/l402/payment-request\",\n \"terms_url\":\"https://link-to-terms.com\",\n \"version\":\"0.2.1\"\n}\n```\n\n``` python\nfs.pay(ofs['payment_request_url'], ofs['payment_context_token'], **ofs['offers'][0], pm='lightning')\n```\n\n {'id': 240,\n 'created_at': '2024-12-26T10:24:03.486Z',\n 'status': 'success',\n 'payment_request_url': 'https://stock.l402.org/l402/payment-request',\n 'payment_context_token': 'edb53dec-28f5-4cbb-924a-20e9003c20e1',\n 'invoice': 'lnbc100n1pnk6tkrpp5pkshrxfyvxuqphwxvax8dfaemhh287lnefrjr68cy494fppe5l0sdq6xysyxun9v35hggzsv93kkct8v5cqzpgxqrzpnrzjqwghf7zxvfkxq5a6sr65g0gdkv768p83mhsnt0msszapamzx2qvuxqqqqz99gpz55yqqqqqqqqqqqqqq9qrzjq25carzepgd4vqsyn44jrk85ezrpju92xyrk9apw4cdjh6yrwt5jgqqqqz99gpz55yqqqqqqqqqqqqqq9qsp5070fsrfdknwpv2rfeju44k37uj362xcrzmey4se70kpzusy6c0pq9qxpqysgqcj990yc9lg5wje9u6myceakzff95q8qdwrslx69xh526y764dwlxt4v90qhwtmesukfaute6hkh9952t5f5gqjmrry3c6y0k7y2ltkcphyxfp2',\n 'preimage': '9de11f4b1bbaf9c18b8b28ee0747fdd64d124b7ee05090f4edc377e73393c2dc',\n 'amount': 1,\n 'currency': 'usd',\n 'payment_method': 'lightning',\n 'title': '1 Credit Package',\n 'description': 'Purchase 1 credit for API access',\n 'type': 'top-up'}\n\n### AI Agent Integration\n\nWe will show how to enable your AI assistant to handle payments using\n[Claudette](https://claudette.answer.ai), Answer.ai convenient wrapper\nfor Claude. You\u2019ll need to export your `ANTHROPIC_API_KEY` as env\nvariable for this to work.\n\n``` python\nfrom claudette import Chat, models\n```\n\n``` python\nimport os\n# os.environ['ANTHROPIC_LOG'] = 'debug'\n```\n\nTo print every HTTP request and response in full, uncomment the above\nline.\n\n``` python\nfs.balance()\n```\n\n [{'id': 15, 'balance': 6470, 'currency': 'usd'}]\n\n``` python\nchat = Chat(models[1], sp='You are a helpful assistant that can pay offers.', tools=fs.as_tools())\npr = f\"Could you pay the cheapest offer using lightning {ofs}?\"\nr = chat.toolloop(pr, trace_func=print)\nr\n```\n\n Message(id='msg_01SmWra463n6Q5wivTQS41B9', content=[TextBlock(text=\"Certainly! I can help you pay for the cheapest offer using Lightning. Based on the information you've provided, there's only one offer available, so we'll proceed with that one. Let's use the `pay` function to complete this transaction.\\n\\nFirst, let's organize the information we have:\\n\\n1. There's one offer for 1 credit at $0.01 (1 cent).\\n2. The payment method is Lightning.\\n3. We have a payment context token and a payment request URL.\\n\\nNow, let's call the `pay` function with the required parameters:\", type='text'), ToolUseBlock(id='toolu_016nRMYdemRYBEuVq8JkWPe4', input={'purl': 'https://stock.l402.org/l402/payment-request', 'pct': 'edb53dec-28f5-4cbb-924a-20e9003c20e1', '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'}, name='pay', type='tool_use')], model='claude-3-5-sonnet-20240620', role='assistant', stop_reason='tool_use', stop_sequence=None, type='message', usage=In: 1002; Out: 395; Cache create: 0; Cache read: 0; Total: 1397)\n Message(id='msg_011KopqDeH4CNLt8bKTLyGQD', content=[TextBlock(text=\"Great news! The payment has been successfully processed. Here's a summary of the transaction:\\n\\n1. Payment Status: Success\\n2. Amount Paid: 1 cent (USD)\\n3. Payment Method: Lightning\\n4. Title: 1 Credit Package\\n5. Description: Purchase 1 credit for API access\\n6. Type: Top-up\\n7. Transaction ID: 241\\n8. Created At: 2024-12-26T10:24:13.845Z\\n\\nThe payment has been completed successfully, and you should now have 1 credit for API access added to your account. Is there anything else you would like to know about this transaction or any other assistance you need?\", type='text')], model='claude-3-5-sonnet-20240620', role='assistant', stop_reason='end_turn', stop_sequence=None, type='message', usage=In: 1942; Out: 155; Cache create: 0; Cache read: 0; Total: 2097)\n\nGreat news! The payment has been successfully processed. Here\u2019s a\nsummary of the transaction:\n\n1. Payment Status: Success\n2. Amount Paid: 1 cent (USD)\n3. Payment Method: Lightning\n4. Title: 1 Credit Package\n5. Description: Purchase 1 credit for API access\n6. Type: Top-up\n7. Transaction ID: 241\n8. Created At: 2024-12-26T10:24:13.845Z\n\nThe payment has been completed successfully, and you should now have 1\ncredit for API access added to your account. Is there anything else you\nwould like to know about this transaction or any other assistance you\nneed?\n\n<details>\n\n- id: `msg_011KopqDeH4CNLt8bKTLyGQD`\n- content:\n `[{'text': \"Great news! The payment has been successfully processed. Here's a summary of the transaction:\\n\\n1. Payment Status: Success\\n2. Amount Paid: 1 cent (USD)\\n3. Payment Method: Lightning\\n4. Title: 1 Credit Package\\n5. Description: Purchase 1 credit for API access\\n6. Type: Top-up\\n7. Transaction ID: 241\\n8. Created At: 2024-12-26T10:24:13.845Z\\n\\nThe payment has been completed successfully, and you should now have 1 credit for API access added to your account. Is there anything else you would like to know about this transaction or any other assistance you need?\", 'type': 'text'}]`\n- model: `claude-3-5-sonnet-20240620`\n- role: `assistant`\n- stop_reason: `end_turn`\n- stop_sequence: `None`\n- type: `message`\n- usage:\n `{'cache_creation_input_tokens': 0, 'cache_read_input_tokens': 0, 'input_tokens': 1942, 'output_tokens': 155}`\n\n</details>\n\n``` python\nfs.balance()\n```\n\n [{'id': 15, 'balance': 6469, 'currency': 'usd'}]\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Python SDK for Fewsats",
"version": "0.0.11",
"project_urls": {
"Homepage": "https://github.com/Fewsats/fewsats-python"
},
"split_keywords": [
"nbdev",
"jupyter",
"notebook",
"python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5d5e1f802c79c8a6315c9884ac865b0fd8464fb91e098d6216441dec03a23050",
"md5": "0854be46917f097d52f569b1ec122439",
"sha256": "188d94952076c229ba53db01aa9289456eee4ef52275f4f663e762ab4b00916e"
},
"downloads": -1,
"filename": "fewsats-0.0.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0854be46917f097d52f569b1ec122439",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 12688,
"upload_time": "2025-02-02T04:04:01",
"upload_time_iso_8601": "2025-02-02T04:04:01.038132Z",
"url": "https://files.pythonhosted.org/packages/5d/5e/1f802c79c8a6315c9884ac865b0fd8464fb91e098d6216441dec03a23050/fewsats-0.0.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "07f1a6c0d39c6dd14ba5c809984d4d090336bbc77e1afc828959a57a79c0a909",
"md5": "e8d49e651fa33c3e8dc214105f7d997a",
"sha256": "3b3080c3a4d1de82e1a671128285c7d838f1b027f5536d055c283cc0631727f1"
},
"downloads": -1,
"filename": "fewsats-0.0.11.tar.gz",
"has_sig": false,
"md5_digest": "e8d49e651fa33c3e8dc214105f7d997a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 15792,
"upload_time": "2025-02-02T04:04:02",
"upload_time_iso_8601": "2025-02-02T04:04:02.029664Z",
"url": "https://files.pythonhosted.org/packages/07/f1/a6c0d39c6dd14ba5c809984d4d090336bbc77e1afc828959a57a79c0a909/fewsats-0.0.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-02 04:04:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Fewsats",
"github_project": "fewsats-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fewsats"
}