Metadata-Version: 2.4
Name: coinrailz-solana
Version: 1.0.2
Summary: Solana AI Agent Payment Processing SDK - Non-custodial SOL/USDC payments for AI agents
Author-email: Coin Railz <support@coinrailz.com>
License: MIT
Project-URL: Homepage, https://coinrailz.com
Project-URL: Documentation, https://coinrailz.com/docs/sdk/solana
Project-URL: Repository, https://github.com/coinrailz/agent-payments-solana
Project-URL: Issues, https://github.com/coinrailz/agent-payments-solana/issues
Keywords: ai-agent,payments,solana,sol,usdc,spl-token,crypto,fintech,x402,eliza,agentkit,mcp,blockchain,non-custodial
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Dynamic: license-file

# coinrailz-solana

Solana AI Agent Payment Processing SDK by Coin Railz LLC - Non-custodial SOL/USDC payments for AI agents.

## Installation

```bash
pip install coinrailz-solana
```

## Get Your API Key

**Instant API Key** - Pay $1 (USDC/USDT on Base or Solana) and get your API key immediately. No account required!

1. Visit https://coinrailz.com/api-keys
2. Send $1 to the platform wallet
3. Verify your transaction and receive your key + $5 starter credits

**Key Persistence**: Your API key is permanent and works across ALL Coin Railz services. One key = unlimited access (credits are deducted per use). You can top up credits anytime with the same key.

## Quick Start

```python
from coinrailz_solana import CoinRailzSolana, SendPaymentParams

client = CoinRailzSolana(api_key="your-api-key")

# Send USDC on Solana
result = client.send(SendPaymentParams(
    to="9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    amount=10.00,
    currency="USDC"
))

print(result)
# SendPaymentResult(
#     success=True,
#     transaction_id='sol_abc123',
#     signature='5abc...',
#     amount=Amount(gross=10.00, fee=0.16, net=9.84),
#     explorer_url='https://solscan.io/tx/5abc...'
# )
```

## Features

- **SOL Transfers** - Native SOL payments
- **USDC Transfers** - SPL Token USDC on Solana
- **Wallet Creation** - Generate new Solana wallets
- **Balance Queries** - Check SOL balances
- **Transaction Status** - Track payment confirmations

## API Reference

### Constructor

```python
client = CoinRailzSolana(
    api_key="your-api-key",      # Required: Your API key
    base_url="https://...",       # Optional: API base URL
    timeout=30.0                  # Optional: Request timeout in seconds
)
```

### Methods

#### send(params)
Send SOL or USDC payment.

```python
from coinrailz_solana import SendPaymentParams

result = client.send(SendPaymentParams(
    to="SolanaAddress...",
    amount=10.00,
    currency="USDC",  # "SOL" or "USDC"
    memo="Payment for service"
))
```

#### get_balance(address)
Get SOL balance for an address.

```python
balance = client.get_balance("SolanaAddress...")
# BalanceResult(balance=Balance(sol=1.5, lamports=1500000000))
```

#### create_wallet()
Create a new Solana wallet.

```python
wallet = client.create_wallet()
# WalletResult(wallet=WalletInfo(address='...'), private_key='...')
```

#### get_transaction(signature)
Get transaction status.

```python
tx = client.get_transaction("5abc...")
# TransactionResult(signature='5abc...', status='confirmed')
```

#### status()
Check service status.

```python
status = client.status()
# StatusResult(status='operational', network='mainnet-beta')
```

## Error Handling

All API errors return machine-readable structured responses for programmatic handling:

```python
result = client.send(SendPaymentParams(to="...", amount=10.00))

if not result.success:
    print(f"Error code: {result.error.code}")
    print(f"Hint: {result.error.agent_hint}")
    
    # Programmatic error handling
    if result.error.code == "PAYMENT_INVALID_TX_HASH_LENGTH":
        # Solana signatures should be 87-88 base58 chars
        pass
    elif result.error.code == "SOLANA_VERIFICATION_FAILED":
        # On-chain verification failed
        pass
    elif result.error.code == "INSUFFICIENT_CREDITS":
        # Top up credits at coinrailz.com/api-keys
        pass
```

### Error Codes Reference

| Code | Description | Recoverable |
|------|-------------|-------------|
| `PAYMENT_INVALID_TX_HASH_LENGTH` | Transaction hash wrong length | Yes |
| `PAYMENT_INVALID_TX_HASH_FORMAT` | Invalid characters in hash | Yes |
| `SOLANA_VERIFICATION_FAILED` | Solana on-chain verification failed | No |
| `PAYMENT_VERIFICATION_EXCEPTION` | Verification threw an error | Maybe |
| `INSUFFICIENT_CREDITS` | Not enough credits for operation | Yes |
| `INVALID_API_KEY` | API key not found or expired | No |

## Context Manager

```python
with CoinRailzSolana(api_key="your-api-key") as client:
    result = client.send(SendPaymentParams(to="...", amount=10.00))
```

## Pricing

| Tier | Volume | Processing Fee |
|------|--------|----------------|
| Starter | $0-$10K/mo | 1.5% + $0.01 |
| Growth | $10K-$100K/mo | 1.25% + $0.01 |
| Platform | $100K+/mo | 0.9% + $0.01 |

**Minimum transaction**: $0.05

## Use Cases

- **AI Agent Payments** - Autonomous agent-to-agent payments on Solana
- **ElizaOS Integration** - Payment processing for ElizaOS agents
- **AgentKit** - Coinbase AgentKit payment plugin
- **MCP Tools** - Model Context Protocol payment tools

## Support

- Documentation: https://coinrailz.com/docs/sdk/solana
- Discord: https://discord.gg/coinrailz
- Email: support@coinrailz.com

## License

MIT
