Metadata-Version: 2.4
Name: paysponge
Version: 0.1.2
Summary: Python SDK for PaySponge
Author-email: PaySponge <team@paysponge.com>
License-Expression: MIT
Project-URL: Homepage, https://docs.paysponge.com
Project-URL: Documentation, https://docs.paysponge.com
Project-URL: Repository, https://github.com/paysponge/sponge
Project-URL: Issues, https://github.com/paysponge/sponge/issues
Keywords: PaySponge,SDK,payments,wallets,agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: urllib3<3.0.0,>=2.1.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pydantic>=2
Requires-Dist: typing-extensions>=4.7.1

# paysponge

Python SDK for Sponge.

The `paysponge` package gives Python apps access to Sponge agent wallets,
platform provisioning, transfers, balances, and paid request workflows.

## Concepts

Sponge has two client types:

- `SpongeWallet` is the runtime client for one agent. Use it with an agent API
  key when that agent needs to inspect balances, get wallet addresses, transfer
  funds, or make paid requests.
- `SpongePlatform` is the control-plane client for your backend. Use it with a
  master/platform API key when you need to create agents or manage many agents
  for your product.

An agent is the Sponge identity that owns wallets and permissions. In a
multi-user app, you typically create one Sponge agent per user, bot, workflow,
or worker. Each agent gets its own agent API key. Your backend can use
`SpongePlatform` to provision those agents, then store the returned agent key
with your own user or worker record. At runtime, use `SpongeWallet` with that
agent key so actions are scoped to the correct agent.

## Install

```bash
pip install paysponge
```

## Quick Start

Use an agent API key with `SpongeWallet`. The wallet client acts on behalf of
one Sponge agent.

```python
from paysponge import SpongeWallet

wallet = SpongeWallet.connect(api_key="sponge_test_xxx")

agent = wallet.get_agent()
addresses = wallet.get_addresses()
balances = wallet.get_balances()

print(agent.id)
print(addresses)
print(balances)
```

An agent is the Sponge identity that owns the wallets and permissions used by
the SDK. `wallet.get_agent()` fetches the current agent for the API key and
stores its `agent.id` on the client, so later calls can use that agent by
default.

You can also read the API key from the environment:

```bash
export SPONGE_API_KEY=sponge_test_xxx
```

```python
from paysponge import SpongeWallet

wallet = SpongeWallet.connect()
print(wallet.get_addresses())
```

## Platform Usage

Use a master/platform API key with `SpongePlatform` when your backend needs to
create or manage agents. Platform keys are higher-trust credentials and should
stay on your server. They are for provisioning and administration, not for
day-to-day agent actions.

```python
from paysponge import SpongePlatform

platform = SpongePlatform.connect(api_key="sponge_master_xxx")
agent = platform.create_agent(name="Hackathon Agent")

print(agent.id)
```

Typical platform flow:

1. Your backend authenticates with `SpongePlatform` using a master key.
2. It creates a Sponge agent for a user, bot, or worker.
3. It stores the returned agent API key with your own application record.
4. Runtime code uses `SpongeWallet` with that agent API key.

## Examples

Source examples are available in the repository:

- `mobwallet/python/paysponge/examples/basic.py`
- `mobwallet/python/paysponge/examples/transfer.py`
- `mobwallet/python/paysponge/examples/basic_sdk.py`

From a clone of the repository:

```bash
cd mobwallet/python/paysponge
SPONGE_API_KEY=sponge_test_xxx uv run python examples/basic.py
SPONGE_API_KEY=sponge_test_xxx RECIPIENT_ADDRESS=0x... uv run python examples/transfer.py
```

## Common Methods

```python
wallet.get_agent()
wallet.get_addresses()
wallet.get_balances()
wallet.get_wallets()
wallet.transfer(chain="base", to="0x...", amount="1.00", currency="USDC")
wallet.paid_fetch(url="https://example.com")
```

## Links

- Documentation: https://docs.paysponge.com
- Repository: https://github.com/paysponge/sponge
- Issues: https://github.com/paysponge/sponge/issues

## Tests

From a clone of the repository:

```bash
cd mobwallet/python/paysponge
uv run python -m unittest discover -s tests
```
