DocsPython SDK Reference

Python SDK Reference

v0.8.1

The official Python SDK (modexiaagentpay) provides a lightweight client for wallets, intent-based payments, cross-chain transfers, and high-frequency channels. It is designed to be easily integrated as a tool in LangChain, LlamaIndex, or custom agent loops.

ModexiaClient

The client automatically validates your API key by performing a handshake request to /api/v1/user/me. If the key is invalid or expired, it raises ModexiaAuthError immediately.

Automatic Environment Detection

The client auto-detects your environment based on the API key prefix. Keys starting with mx_test_ connect to the Sandbox (test credits). Keys starting with mx_live_ connect to Production (main network, real value transfers).

Parameter	Type	Description
`api_key`	str	Your Modexia API key.
`timeout`	int	Per-request timeout in seconds (default: 15).

python

from modexia import ModexiaClient

# Synchronous client (tests automatically connect to testnet)
client = ModexiaClient(api_key="mx_test_...")

client.retrieve_balance() -> str

Returns the current available balance of your agent account as a decimal string. Useful for pre-flight checks before attempting a payment.

python

balance = client.retrieve_balance()
print(f"Agent balance: {balance} credits")

Intents (v2 API)

The Intent-to-Pay API is the recommended method for standard payments. It uses HMAC-signed tokens to securely declare an intent before executing it, returning rich compliance metadata and actionable rejection suggestions.

client.pay(recipient, amount, memo=None) -> IntentResult

Creates a signed intent, submits it to the Gateway, and polls for finality automatically.

python

result = client.pay(
    recipient="0x742d35Cc6634C0532925a3b844...",
    amount=10.0,
    memo="Monthly API access"
)

print(result.status) # "executed"
print(result.txId)   # Circle Tx ID
print(result.txState) # "COMPLETE"

Rich Error Suggestions

If a payment fails (e.g. hits a spending limit), the IntentResult will contain a suggestion field explaining exactly why it failed (e.g., "Daily limit exceeded. Remaining: $2.50").

client.create_intent / client.submit_intent

For advanced use cases, you can split the intent creation and submission phases.

python

# 1. Sign locally
token = client.create_intent(recipient="0x...", amount=5.0)

# 2. Submit to gateway
result = client.submit_intent(token)

Cross-Chain Transfers

Powered by Squid Router, you can natively bridge and swap USDC from your agent's Base wallet to any destination chain (e.g., Ethereum, Solana, Akash) seamlessly.

client.cross_chain_transfer(to_chain, to_token, recipient, amount) -> PaymentReceipt

python

# Send 50 USDC from Base directly to an Ethereum address
receipt = client.cross_chain_transfer(
    to_chain="1", # Ethereum Mainnet
    to_token="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", # ETH USDC
    recipient="0xabc...",
    amount=50.0
)

# Cross-chain transfers take several minutes, so this returns PENDING immediately.
print(receipt.status) # "PENDING"

Nanopayments & Gateway

The Nanopay API is the recommended way to negotiate x402 paywalls and make rapid micro-transactions off-chain via Circle Gateway EIP-3009 signatures.

client.nanopay_deposit(amount)

Move USDC from your agent's main SCA wallet into the Gateway. (Run client.nanopay_activate() first).

python

# Activate gateway (idempotent)
client.nanopay_activate()

# Deposit $10.00 to the Gateway for off-chain nanopayments
client.nanopay_deposit(10.0)

client.nanopay(url, **kwargs)

Fetch any URL and automatically negotiate payment if the server returns HTTP 402. This uses your Gateway balance to generate zero-gas EIP-3009 signatures instead of on-chain transactions.

python

# Automatically negotiates the 402 using off-chain signatures
result = client.nanopay("https://api.premium-data.com/report")

if result.success:
    print(result.data) # The premium payload

Vaults (High-Frequency Channels)

Vaults use cryptographic payment channels to allow agents to process thousands of transactions per second off-chain with zero latency and zero network fees.

client.open_channel / consume_channel / settle_channel

python

# 1. Open a channel with a max capacity of 1.00 credit
channel = client.open_channel(
    provider="0x1c56...", 
    deposit=1.00, 
    duration_hours=24.0
)

# 2. Fire High-Frequency Consume Calls (1,000 sub-second txs)
for i in range(1000):
    client.consume_channel(
        channel_id=channel['channelId'],
        amount=0.001
    )

# 3. Finalize on the ledger and refund unused balance
client.settle_channel(channel_id=channel['channelId'])

Legacy Methods (v1 API)

These methods are fully supported and functional, but newer patterns (like Intents and Nanopay) are generally recommended for new integrations.

client.transfer(recipient, amount, wait=True)

Directly executes an on-chain transfer. We recommend client.pay() instead for better error handling and compliance tracking.

python

receipt = client.transfer(
    recipient="0xabc...",
    amount=10.0,
    wait=True
)

client.smart_fetch(method, url, **kwargs)

An earlier implementation of paywall negotiation that uses on-chain transfer() instead of off-chain Gateway signatures. We recommend client.nanopay(url) for lower gas fees.

client.get_history(limit=5)

Fetch the transaction history for your authenticated agent.

python

history = client.get_history(limit=5)
for tx in history.transactions:
    print(f"[{tx.createdAt}] {tx.amount} -> {tx.providerAddress}")