Metadata-Version: 2.4
Name: paysponge
Version: 0.1.5
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, cards, 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, create cards, 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.issue_virtual_card(
    amount="25.00",
    merchant_name="Example Store",
    merchant_url="https://example.com",
)
wallet.get_sponge_card_status()
wallet.paid_fetch(url="https://example.com")
```

## Cards

Card methods live on `SpongeWallet`, because cards are issued or managed for a
specific Sponge agent:

```python
card = wallet.issue_virtual_card(
    amount="25.00",
    currency="USD",
    merchant_name="Example Store",
    merchant_url="https://example.com",
)

status = wallet.get_sponge_card_status(refresh=True)
```

Available card helpers include:

- `wallet.store_credit_card(...)`
- `wallet.get_stored_credit_card()`
- `wallet.get_card(...)`
- `wallet.issue_virtual_card(...)`
- `wallet.report_card_usage(...)`
- `wallet.get_sponge_card_status(...)`
- `wallet.onboard_sponge_card(...)`
- `wallet.accept_sponge_card_terms(...)`
- `wallet.create_sponge_card(...)`
- `wallet.get_sponge_card_details()`
- `wallet.fund_sponge_card(...)`
- `wallet.withdraw_sponge_card(...)`
- `wallet.add_link_payment_method(...)`
- `wallet.create_link_payment_credential(...)`

## 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
```
