Metadata-Version: 2.4
Name: aifinpay-agent
Version: 0.1.0a1
Summary: Non-custodial x402 payment client for autonomous AI agents on AiFinPay (Solana + Polygon)
Author-email: "CoinSecurities (SECCO)" <contact@aifinpay.company>
License: MIT
Project-URL: Homepage, https://aifinpay.company
Project-URL: Documentation, https://aifinpay.company/docs
Project-URL: Repository, https://github.com/enot3615/oracle-financial-hub-59
Project-URL: Issues, https://github.com/enot3615/oracle-financial-hub-59/issues
Keywords: x402,ai-agent,solana,polygon,payments,non-custodial,ed25519
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: PyNaCl>=1.5
Requires-Dist: base58>=2.1
Requires-Dist: requests>=2.28

# aifinpay-agent (Python)

Non-custodial x402 payment client for autonomous AI agents on
[AiFinPay](https://aifinpay.company).

The Ed25519 keypair is generated locally and never leaves your process. The
SDK only sends a one-time SHA-256 + Ed25519 signature in the `x-signature`
header to authenticate against AiFinPay-protected endpoints.

## Install

```bash
pip install aifinpay-agent
```

## Quick start

```python
from aifinpay import Agent

# Generate a fresh keypair locally — never transmitted
agent = Agent.new()
print("Fund this address:", agent.address)
print("Save this secret:", agent.secret_b58)  # store securely!

# Wait until the wallet has at least $0.01 worth on-chain
agent.wait_for_funding(min_usd_cents=1)

# Request an invoice for a Seat (USDC on Solana)
invoice = agent.reserve_seat_invoice(amount_usd=1.00, asset="USDC")
print("Invoice:", invoice.raw)
# Build + sign + submit the Solana transaction with @solana/web3.js, anchorpy,
# or solana-py — the invoice contains program_id, treasury_vault, mints, etc.

# Once the Seat is on-chain, any AiFinPay-gated endpoint just works:
resp = agent.get("https://aifinpay.company/api/stats")
print(resp.json())
```

## Loading an existing keypair

```python
# from solana-keygen JSON file
agent = Agent.from_keypair_file("~/agent-wallet.json")

# from base58 secret string
agent = Agent.from_secret_b58("3RvZm7Gw...")
```

## How x402 auth works under the hood

For every gated request the SDK:

1. `GET /nonce` → receives a one-time UUID with 60s TTL
2. computes `SHA-256("AiFinPay-x402:{nonce}:{pubkey}")`
3. signs with Ed25519, base58-encodes the signature
4. retries the original request with headers:
   - `x-agent-pubkey: <base58 pubkey>`
   - `x-nonce: <uuid>`
   - `x-signature: <base58 sig>`

The server verifies the signature, checks the agent has a live Seat PDA
on-chain, and serves the resource.

## Privacy

- **The server never sees your private key.** Period.
- Nonces are consumed on use; replay-resistant.
- All transactions are public and on-chain — Solana + Polygon mainnet.

## License

MIT.
