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

pip install paysponge

Quick Start

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

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:

export SPONGE_API_KEY=sponge_test_xxx

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.

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:

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

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:

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:

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