fianza-agent-sdk (Python)

Python SDK for AI agents to take and repay revenue-underwritten, uncollateralized USDC credit on Fianza (Stellar / Soroban).

An agent proves real revenue → Fianza underwrites it → the agent gets a credit line it can draw against and repay, all from its own Stellar key. This is the Python port of the TypeScript @fianza/agent-sdk; the two speak the same backend API and on-chain contracts.

pip install fianza-agent-sdk

Quickstart

from stellar_sdk import Keypair
from fianza import FianzaAgent

# An agent holds its own Stellar key.
tl = FianzaAgent(
    Keypair.random().secret,
    api_base_url="https://trustline-rpxt.onrender.com",
)

tl.register()                      # one-time, on-chain
result = tl.underwrite(skip_proof=True)   # backend scores + publishes on-chain
print(result["score"])

terms = tl.credit_line()           # on-chain read (simulate-only)
print(terms)                       # CreditTerms(tier=..., limit_usdc=..., apr_bps=...)

if terms.limit_usdc > 0:
    tl.borrow(1)                   # draw 1 USDC against the line
    # ...do paid work...
    tl.repay(1)                    # interest first (lender yield), then principal

A full runnable walkthrough (fresh keypair → Friendbot → faucet → register → underwrite → borrow → repay) lives in examples/quickstart.py.

API

Construct with the agent's secret; contract ids are auto-resolved from the backend /config unless you pass them explicitly.

FianzaAgent(
    secret,
    *,
    rpc_url=None,               # Soroban RPC (default: testnet)
    network_passphrase=None,    # default: testnet
    api_base_url=None,          # Fianza backend (default: http://localhost:8787)
    contracts=None,             # {"registry","creditLine","vault"} — else from /config
)

Underwriting (delegated to the backend)

On-chain reads (simulate-only)

On-chain writes (signed by the agent's key)

Each returns a TxResult(tx_hash, return_value, explorer_url).

Draw-on-402

resp = tl.pay_with_credit(url, price_usdc, max_draw=None, method="GET")

Pay for an x402-priced resource, auto-drawing any shortfall from the credit line first. The agent never "decides to borrow" — it just transacts, and the line silently covers what its cash can't. Returns a requests.Response. Pass json_body=..., data=..., and headers=... for POST bodies. This implements the x402 exact-Stellar scheme (SEP-41 transfer, facilitator-sponsored) directly, so no extra dependency is required.

Errors

All SDK errors subclass FianzaError:

• ValidationError — bad input (amount, address).
• ApiError — backend returned non-2xx (.status, .method, .path, .body).
• TxError — an on-chain tx failed to simulate/submit/confirm (.contract_method, .detail).
• MaxDrawExceededError — pay_with_credit would draw past max_draw (.need, .max_draw).

Pure helpers

to_stroops, from_stroops (USDC ↔ 7-decimal stroops), is_valid_stellar_address, and credit_shortfall_usdc (the draw-on-402 math) are exported and unit-tested.

Development

pip install -e ".[dev]"
pytest

License

MIT