human-rpc-sdk 0.1.0

Autonomous Payment Agent SDK for Solana x402 protocol

Human RPC SDK

Autonomous Payment Agent SDK for Solana x402 protocol. Automatically handles 402 Payment Required responses by making Solana payments (SOL or USDC) to unlock paywalled content.

Installation

pip install human-rpc-sdk

Quickstart

1. Set Environment Variables

# Required: Your Solana private key (base58-encoded)
export SOLANA_PRIVATE_KEY="your_base58_private_key_here"

# Optional: Custom RPC URL (defaults to public Solana RPCs)
export SOLANA_RPC_URL="https://your-rpc-provider.com"
# Or network-specific:
export SOLANA_MAINNET_RPC_URL="https://mainnet.helius-rpc.com"
export SOLANA_DEVNET_RPC_URL="https://devnet.helius-rpc.com"

# Optional: Human RPC endpoint (defaults to localhost)
export HUMAN_RPC_URL="https://your-human-rpc-endpoint.com/api/v1/tasks"

2. Basic Usage

from human_rpc_sdk import AutoAgent

# Initialize the agent
agent = AutoAgent()

# Make requests - payments are handled automatically!
response = agent.get("https://premium-api.com/data")
print(response.json())

# POST requests work too
response = agent.post(
    "https://api.example.com/endpoint",
    json={"query": "example"}
)

3. Human RPC Integration

from human_rpc_sdk import AutoAgent

agent = AutoAgent()

# Ask Human RPC to analyze text
result = agent.ask_human_rpc(
    text="Analyze this sentiment",
    agentName="MyAgent",
    reward="0.3 USDC",
    rewardAmount=0.3,
    category="Analysis",
    escrowAmount="0.6 USDC",
    context={
        "type": "sentiment_check",
        "summary": "Validate sentiment classification",
        "data": {
            "userQuery": "What is the sentiment?",
            "agentConclusion": "POSITIVE",
            "confidence": 0.75,
            "reasoning": "The text contains positive indicators..."
        }
    }
)

print(f"Sentiment: {result['sentiment']}")
print(f"Confidence: {result['confidence']}")

4. Integrated Analysis (AI + Human RPC)

from human_rpc_sdk import AutoAgent

agent = AutoAgent()

def my_ai_analysis(text: str) -> dict:
    # Your AI analysis logic here
    return {
        "userQuery": text,
        "agentConclusion": "POSITIVE",
        "confidence": 0.75,  # Low confidence triggers Human RPC
        "reasoning": "Analysis reasoning..."
    }

# Automatically uses Human RPC if confidence is below threshold
result = agent.integrated_analysis(
    text="Wow, great job team. Another delay. Bullish!",
    ai_analysis_callback=my_ai_analysis,
    confidence_threshold=0.99
)

Configuration

Environment Variables

Variable	Required	Description	Default
SOLANA_PRIVATE_KEY	Yes	Base58-encoded Solana private key	-
SOLANA_RPC_URL	No	Global RPC URL override	Public Solana RPCs
SOLANA_MAINNET_RPC_URL	No	Mainnet-specific RPC URL	https://api.mainnet-beta.solana.com
SOLANA_DEVNET_RPC_URL	No	Devnet-specific RPC URL	https://api.devnet.solana.com
HUMAN_RPC_URL	No	Human RPC endpoint	http://localhost:3000/api/v1/tasks

RPC URL Priority

1. SOLANA_RPC_URL (global override)
2. Network-specific (SOLANA_MAINNET_RPC_URL or SOLANA_DEVNET_RPC_URL)
3. Default public RPC URLs

How It Works

1. Request: You make a normal HTTP request using agent.get() or agent.post()
2. 402 Detection: If the server responds with 402 Payment Required, the SDK automatically:
   • Parses the payment invoice
   • Builds a Solana transaction (SOL or USDC)
   • Signs and encodes the transaction
   • Adds it to the X-PAYMENT header
   • Retries the request automatically
3. Success: Your request completes with the unlocked content

Troubleshooting

Insufficient Funds

Error: Insufficient Funds. Please send SOL/USDC to <wallet_address>

Solution: Fund your wallet with the required amount:

• For SOL payments: Send SOL to your wallet address
• For USDC payments: Send USDC to your wallet (it will be in an associated token account)

RPC Rate Limits

Error: RPC error: rate limit exceeded

Solution: Use a private RPC provider:

export SOLANA_RPC_URL="https://your-private-rpc-provider.com"

Invalid Private Key

Error: Failed to load private key from SOLANA_PRIVATE_KEY

Solution: Ensure your private key is:

• Base58-encoded
• A valid Solana keypair
• Set in the environment variable correctly

Payment Verification Failed

Error: Payment verification failed

Solution:

• Ensure your wallet has sufficient funds
• Check that the payment amount matches the invoice
• Verify the network (mainnet/devnet) matches the invoice

Requirements

• Python 3.9+
• Solana wallet with SOL/USDC balance
• Internet connection for RPC calls

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• GitHub Issues: https://github.com/yourusername/x402-solana/issues
• Documentation: https://github.com/yourusername/x402-solana