langchain-send21 0.1.0__py3-none-any.whl

langchain_send21/__init__.py

@@ -0,0 +1,14 @@
+"""send21 tools for LangChain.
+
+send21 prepares payment instructions. It never holds keys or funds, never signs and
+never broadcasts. A key with drafts:write can create a pay link but cannot move money.
+"""
+from langchain_send21.tools import (
+    PayOption,
+    Send21Client,
+    Send21CreatePayLinkTool,
+    Send21GetPayLinkStatusTool,
+    Send21Toolkit,
+)
+
+__all__ = ["PayOption", "Send21Client", "Send21CreatePayLinkTool", "Send21GetPayLinkStatusTool", "Send21Toolkit"]

langchain_send21/tools.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import os
+import uuid
+from typing import Any, Literal, Optional
+from urllib.parse import urljoin
+
+import httpx
+from langchain_core.tools import BaseTool, BaseToolkit
+from pydantic import BaseModel, Field, PrivateAttr
+
+# Supported asset/network pairs. USDT only on Solana and Ethereum, no ETH on Polygon.
+SUPPORTED = {
+    "Btc": {"Mainnet"},
+    "Usdc": {"Solana", "Ethereum", "Base", "Arbitrum", "Polygon"},
+    "Usdt": {"Solana", "Ethereum"},
+    "Eurc": {"Solana", "Ethereum", "Base"},
+    "Sol": {"Solana"},
+    "Eth": {"Ethereum", "Base", "Arbitrum"},
+}
+
+
+class PayOption(BaseModel):
+    currency: Literal["Btc", "Usdc", "Usdt", "Eurc", "Sol", "Eth"]
+    network: Literal["Mainnet", "Solana", "Ethereum", "Base", "Arbitrum", "Polygon"]
+    address: str = Field(description="The receiver's own address, or Lightning address name@wallet.com")
+    method: Optional[Literal["MultiOutput", "Lightning"]] = None
+
+    def check(self) -> None:
+        if self.network not in SUPPORTED[self.currency]:
+            raise ValueError(f"{self.currency} is not supported on {self.network}")
+        if self.method == "Lightning" and self.currency != "Btc":
+            raise ValueError("Lightning is only for Btc")
+
+
+class Send21Client:
+    """Thin REST client. Uses a scoped send21 API key (https://send21.io/api-keys)."""
+
+    def __init__(self, api_key: str | None = None, base_url: str = "https://send21.io",
+                 http: httpx.Client | None = None) -> None:
+        self.api_key = api_key or os.environ.get("SEND21_API_KEY")
+        if not self.api_key:
+            raise ValueError("Set SEND21_API_KEY (create a scoped key at https://send21.io/api-keys)")
+        self.base_url = base_url.rstrip("/")
+        self.http = http or httpx.Client(timeout=30)
+
+    def _req(self, method: str, path: str, **kw: Any) -> dict:
+        headers = {"Authorization": f"Bearer {self.api_key}", **kw.pop("headers", {})}
+        r = self.http.request(method, self.base_url + path, headers=headers, **kw)
+        if r.status_code >= 400:
+            raise RuntimeError(f"send21 {r.status_code}: {r.text[:500]}")
+        return r.json()
+
+    def create_payment_request(self, body: dict) -> dict:
+        return self._req("POST", "/api/v1/payment-requests", json=body,
+                         headers={"Idempotency-Key": str(uuid.uuid4())})
+
+    def get_payment_request(self, pr_id: str) -> dict:
+        return self._req("GET", f"/api/v1/payment-requests/{pr_id}")
+
+
+class CreatePayLinkInput(BaseModel):
+    fiat_amount: float = Field(gt=0, description="Amount in the fiat currency")
+    fiat_currency: str = Field(min_length=3, max_length=3, description="ISO 4217 code, e.g. EUR")
+    order_id: Optional[str] = Field(None, description="Your reference, echoed in webhooks")
+    memo: Optional[str] = Field(None, max_length=500)
+    decline_note: Optional[str] = Field(None, max_length=200, description="Shown as 'If you don't pay:'")
+
+
+class Send21CreatePayLinkTool(BaseTool):
+    name: str = "send21_create_pay_link"
+    description: str = (
+        "Create a send21 pay link so a human can pay you. Returns a link; the payer picks a currency, "
+        "scans one QR and signs in their own wallet. This tool cannot move funds."
+    )
+    args_schema: type[BaseModel] = CreatePayLinkInput
+    receive_options: list[PayOption]
+    _client: Send21Client = PrivateAttr()
+
+    def __init__(self, client: Send21Client, receive_options: list[PayOption], **kw: Any) -> None:
+        super().__init__(receive_options=receive_options, **kw)
+        for o in receive_options:
+            o.check()
+        self._client = client
+
+    def _run(self, fiat_amount: float, fiat_currency: str, order_id: str | None = None,
+             memo: str | None = None, decline_note: str | None = None, **_: Any) -> dict:
+        pr = self._client.create_payment_request({
+            "fiatAmount": fiat_amount,
+            "fiatCurrency": fiat_currency.upper(),
+            "options": [o.model_dump(exclude_none=True) for o in self.receive_options],
+            "orderId": order_id,
+            "memo": memo,
+            "declineNote": decline_note,
+            "reuseOpenForOrder": True if order_id else None,
+        })
+        return {
+            "payment_request_id": pr["id"],
+            "pay_link": urljoin(self._client.base_url + "/", pr["payPath"].lstrip("/")),
+            "status": pr.get("status"),
+            "expires_at": pr.get("expiresAt"),
+        }
+
+
+class StatusInput(BaseModel):
+    payment_request_id: str
+
+
+class Send21GetPayLinkStatusTool(BaseTool):
+    name: str = "send21_get_pay_link_status"
+    description: str = "Get the status of a send21 pay link (Open, Completed, Cancelled, Expired)."
+    args_schema: type[BaseModel] = StatusInput
+    _client: Send21Client = PrivateAttr()
+
+    def __init__(self, client: Send21Client, **kw: Any) -> None:
+        super().__init__(**kw)
+        self._client = client
+
+    def _run(self, payment_request_id: str, **_: Any) -> dict:
+        pr = self._client.get_payment_request(payment_request_id)
+        return {"status": pr.get("status"), "draft_status": pr.get("draftStatus"),
+                "expires_at": pr.get("expiresAt"), "change_notes": pr.get("changeNotes") or []}
+
+
+class Send21Toolkit(BaseToolkit):
+    """Both tools. Receiving addresses are fixed by the app, never chosen by the model."""
+
+    receive_options: list[PayOption]
+    api_key: Optional[str] = None
+    base_url: str = "https://send21.io"
+
+    def get_tools(self) -> list[BaseTool]:
+        c = Send21Client(self.api_key, self.base_url)
+        return [Send21CreatePayLinkTool(c, self.receive_options), Send21GetPayLinkStatusTool(c)]

langchain_send21-0.1.0.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.5
+Name: langchain-send21
+Version: 0.1.0
+Summary: send21 tools for LangChain: prepare non-custodial pay links. The payer signs in their own wallet.
+Project-URL: Homepage, https://send21.io
+Project-URL: Documentation, https://send21.io/docs
+Project-URL: Source, https://github.com/send21io/send21-examples/tree/main/integrations/langchain
+Author-email: send21 <info@send21.io>
+License: MIT
+Keywords: bitcoin,langchain,lightning,non-custodial,payments,send21,tools,usdc
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: langchain-core<2,>=0.3
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# langchain-send21
+
+send21 tools for LangChain. Let an agent prepare a pay link and check its status without holding keys.
+
+send21 is non-custodial software that prepares payment instructions. It never holds keys or funds, never signs and never broadcasts. The scoped API key this package uses can create a pay link but cannot move money: the payer signs in their own wallet.
+
+Not an official LangChain package. Questions: info@send21.io
+
+## Install
+
+```sh
+pip install langchain-send21
+export SEND21_API_KEY=s21_...   # scopes: drafts:write, drafts:read (https://send21.io/api-keys)
+```
+
+## Use
+
+```python
+from langchain.agents import create_agent
+from langchain_send21 import PayOption, Send21Toolkit
+
+tools = Send21Toolkit(receive_options=[
+    PayOption(currency="Usdc", network="Solana", address="<your-solana-address>"),
+    PayOption(currency="Btc", network="Mainnet", address="name@wallet.com", method="Lightning"),
+]).get_tools()
+
+agent = create_agent("openai:gpt-5-mini", tools=tools)
+agent.invoke({"messages": [{"role": "user", "content": "Create a pay link for 40 EUR for order inv-1042."}]})
+```
+
+- `send21_create_pay_link(fiat_amount, fiat_currency, order_id?, memo?, decline_note?)` returns `pay_link`, `payment_request_id`, `status`, `expires_at`. Receiving addresses come from your code, never from the model. Each call uses a fresh idempotency key, and with an `order_id` a retry returns the open link instead of creating a second one.
+- `send21_get_pay_link_status(payment_request_id)` returns `Open`, `Completed`, `Cancelled` or `Expired` plus any "what changed" notes.
+
+Supported pairs: BTC on Bitcoin and Lightning; USDC on Solana, Ethereum, Base, Arbitrum, Polygon; USDT on Solana and Ethereum; EURC on Solana, Ethereum, Base; SOL; ETH on Ethereum, Base, Arbitrum. Others are refused before any API call.
+
+Already using MCP? `langchain-mcp-adapters` can load all 11 tools from https://send21.io/mcp directly.
+
+## Develop
+
+```sh
+pip install -e '.[test]' && pytest   # offline, mocked HTTP
+```
+
+MIT

langchain_send21-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+langchain_send21/__init__.py,sha256=CTeFfrvrsvhks2wLtuWc8gDSBj3-yCOPRan3s6T9fsY,474
+langchain_send21/tools.py,sha256=VCQezw4dKH3hyIJZZ2xtqnmz7FBBzja7Qh2Q2XdU4cE,5682
+langchain_send21-0.1.0.dist-info/METADATA,sha256=wF2-V4rUaG9ijlh3SYCQPrP49RMS3eUXlxFktz8Lsek,2699
+langchain_send21-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+langchain_send21-0.1.0.dist-info/RECORD,,

langchain_send21-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any