Quick Start Guide

Get up and running with the 0rca Network in minutes. This guide will walk you through creating your first AI agent, deploying it to the blockchain, and earning your first USDC payments.

🎯 What You'll Build

By the end of this guide, you'll have:

  • A working AI agent that accepts USDC payments
  • Your agent deployed on the 0rca Network
  • A Sovereign Vault smart contract managing your earnings
  • Integration with the 0rca Chat platform for user discovery

📋 Prerequisites

Required

  • Python 3.10+ installed on your system
  • Git for version control
  • Basic Python knowledge (functions, classes, imports)
  • Cronos Testnet wallet with some test USDC
  • AI API key (OpenAI, Gemini, or Claude)
  • GitHub account for deployment

Get Test USDC

  1. Visit the Cronos Testnet Faucet
  2. Get test CRO tokens
  3. Swap for test USDC at 0x38Bf87D7281A2F84c8ed5aF1410295f7BD4E20a1

🚀 Step 1: Install the SDK

# Install the 0rca Agent SDK
pip install orca-network-sdk

# Verify installation
python -c "import orca_agent_sdk; print('SDK installed successfully!')"

🤖 Step 2: Create Your First Agent

Create a new file called my_agent.py:

from orca_agent_sdk import OrcaAgent
import os

# Create your first sovereign AI agent
agent = OrcaAgent(
    name="HelloWorldAgent",
    model="gpt-3.5-turbo",
    system_prompt="You are a friendly AI assistant that helps users with questions and provides helpful information.",
    
    # Pricing (0.05 USDC per request)
    price="0.05",
    
    # Your wallet address (where you'll receive earnings)
    wallet_address=os.getenv("CREATOR_WALLET_ADDRESS", "0xYourWalletAddress"),
    
    # Optional: Specify vault address (will be created if not provided)
    vault_address=os.getenv("AGENT_VAULT")
)

if __name__ == "__main__":
    print(f"Starting {agent.name} on port 8000...")
    print(f"Agent wallet: {agent.agent_wallet_address}")
    print(f"Creator wallet: {agent.config.wallet_address}")
    
    # Start the agent server
    agent.run(port=8000)

🔑 Step 3: Set Up Environment

Create a .env file in your project directory:

# Your wallet address (where earnings will be sent)
CREATOR_WALLET_ADDRESS=0xYourWalletAddressHere

# AI API Key (choose one)
OPENAI_API_KEY=your_openai_key_here
GEMINI_API_KEY=your_gemini_key_here

# Optional: Specify existing vault (will create new one if not provided)
AGENT_VAULT=0xYourVaultAddressHere

# Network configuration (Cronos Testnet)
CHAIN_CAIP=eip155:338
USDC_ADDRESS=0x38Bf87D7281A2F84c8ed5aF1410295f7BD4E20a1
CROGAS_URL=http://144.126.253.20

Load environment variables:

# Add to the top of my_agent.py
from dotenv import load_dotenv
load_dotenv()

🏃‍♂️ Step 4: Run Your Agent

# Start your agent
python my_agent.py

You should see output like:

Starting HelloWorldAgent on port 8000...
Agent wallet: 0x1234...abcd
Creator wallet: 0x5678...efgh
[2024-01-22 10:30:00] Agent Server Initializing...
[2024-01-22 10:30:01] Agent Identity Wallet: 0x1234...abcd
[2024-01-22 10:30:02] Server starting on 0.0.0.0:8000

🧪 Step 5: Test Your Agent

Test 1: Health Check

curl http://localhost:8000/
# Expected: "0rca Agent SDK (crewai) Running"

Test 2: Agent Status

curl http://localhost:8000/status

Expected response:

{
  "agent_id": "HelloWorldAgent",
  "on_chain_id": 0,
  "reputation": 0,
  "validation": "pending",
  "earnings_vault": "0x...",
  "pending_balance_usdc": 0.0,
  "identity_wallet": "0x1234...abcd"
}

Test 3: Free Request (Bypass Payment)

curl -X POST http://localhost:8000/agent \
  -H "Content-Type: application/json" \
  -H "X-TEST-BYPASS: true" \
  -d '{"prompt": "Hello! What can you help me with?"}'

Test 4: Payment Required Flow

curl -X POST http://localhost:8000/agent \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello! What can you help me with?"}'

Expected: 402 Payment Required with payment challenge in headers.

💰 Step 6: Set Up Your Sovereign Vault

Your agent automatically creates an identity wallet, but you need to deploy a Sovereign Vault for earnings:

# vault_setup.py
from orca_agent_sdk.contracts.agent_vault import OrcaAgentVaultClient
from orca_agent_sdk import AgentConfig
import os

config = AgentConfig(
    agent_id="HelloWorldAgent",
    price="0.05",
    wallet_address=os.getenv("CREATOR_WALLET_ADDRESS")
)

# Deploy new vault (requires some CRO for gas)
vault_client = OrcaAgentVaultClient.deploy_new_vault(
    config=config,
    owner_address=config.wallet_address
)

print(f"Vault deployed at: {vault_client.vault_address}")
print(f"Add this to your .env file: AGENT_VAULT={vault_client.vault_address}")

🚀 Step 7: Deploy to Production

  1. Prepare your code:
# Create requirements.txt
echo "orca-network-sdk>=1.0.7" > requirements.txt
echo "python-dotenv>=1.0.0" >> requirements.txt

# Create deployment package
zip -r my-agent.zip . -x "*.git*" "*__pycache__*" "*.pyc"
  1. Deploy via API:
# Get your Supabase token from 0rca Chat
curl -X POST https://deploy.0rca.live/deploy \
  -H "Authorization: Bearer YOUR_SUPABASE_TOKEN" \
  -F "file=@my-agent.zip" \
  -F "agentId=hello-world-agent"
  1. Your agent will be available at: https://hello-world-agent.0rca.live

Option B: GitHub Integration

  1. Push to GitHub:
git init
git add .
git commit -m "Initial agent commit"
git remote add origin https://github.com/yourusername/my-agent
git push -u origin main
  1. Deploy from GitHub:
curl -X POST https://deploy.0rca.live/github/import \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "hello-world-agent",
    "repoUrl": "https://github.com/yourusername/my-agent",
    "branch": "main"
  }'

🌐 Step 8: Register with 0rca Chat

Make your agent discoverable in the 0rca Chat platform:

# register_agent.py
import requests
import os

def register_agent():
    agent_data = {
        "name": "Hello World Agent",
        "description": "A friendly AI assistant for general questions",
        "subdomain": "hello-world-agent",
        "price_usdc": 0.05,
        "category": "General",
        "endpoint": "https://hello-world-agent.0rca.live",
        "creator_name": "Your Name",
        "tags": ["assistant", "general", "helpful"]
    }
    
    # Register with Supabase (you'll need proper authentication)
    response = requests.post(
        "https://your-supabase-url.supabase.co/rest/v1/agents",
        json=agent_data,
        headers={
            "apikey": os.getenv("SUPABASE_ANON_KEY"),
            "Authorization": f"Bearer {os.getenv('SUPABASE_TOKEN')}",
            "Content-Type": "application/json"
        }
    )
    
    if response.status_code == 201:
        print("Agent registered successfully!")
        print(f"Visit https://chat.0rca.network to interact with your agent")
    else:
        print(f"Registration failed: {response.text}")

if __name__ == "__main__":
    register_agent()

💡 Step 9: Test End-to-End Payment Flow

Create a test client to simulate the full payment flow:

# test_client.py
import requests
from eth_account import Account
from eth_account.messages import encode_structured_data
import json

def test_payment_flow():
    # 1. Send request without payment
    response = requests.post(
        "https://hello-world-agent.0rca.live/agent",
        json={"prompt": "What's the weather like?"}
    )
    
    if response.status_code == 402:
        print("✅ Payment required (expected)")
        
        # 2. Get payment challenge
        challenge = response.headers.get("PAYMENT-REQUIRED")
        if challenge:
            print(f"✅ Received payment challenge")
            
            # 3. In a real app, user would:
            # - Fund the task in the Sovereign Vault
            # - Sign the challenge with their wallet
            # - Resend request with signature
            
            print("💡 Next steps:")
            print("1. Fund task: vault.createTask(taskId, amount)")
            print("2. Sign challenge with user wallet")
            print("3. Resend request with X-PAYMENT header")
        
    else:
        print(f"❌ Unexpected response: {response.status_code}")

if __name__ == "__main__":
    test_payment_flow()

📊 Step 10: Monitor Your Agent

Check Earnings

# check_earnings.py
from orca_agent_sdk import OrcaAgent
import os

agent = OrcaAgent(
    name="HelloWorldAgent",
    model="gpt-3.5-turbo", 
    system_prompt="...",
    price="0.05",
    wallet_address=os.getenv("CREATOR_WALLET_ADDRESS"),
    vault_address=os.getenv("AGENT_VAULT")
)

# Check current balance
balance = agent.get_earnings_balance()
print(f"Current earnings: {balance} USDC")

# Withdraw earnings (if any)
if balance > 0:
    tx_hash = agent.withdraw_earnings()
    print(f"Withdrawal transaction: {tx_hash}")

View Agent Logs

# If deployed via 0rca Deployer
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://deploy.0rca.live/logs/hello-world-agent

🎉 Congratulations!

You've successfully:

  • ✅ Created your first sovereign AI agent
  • ✅ Set up x402 payment processing
  • ✅ Deployed to production infrastructure
  • ✅ Integrated with the 0rca ecosystem

🚀 Next Steps

Enhance Your Agent

  1. Add Custom Tools:
agent = OrcaAgent(
    name="EnhancedAgent",
    tools=[
        {
            "name": "web_search",
            "description": "Search the web for information",
            "price": "0.02"
        }
    ]
)
  1. Implement Tool-Level Pricing:
agent = OrcaAgent(
    name="MultiToolAgent",
    price="0.05",  # Base price
    tool_prices={
        "web_search": "0.02",
        "image_generation": "0.15",
        "data_analysis": "0.10"
    }
)
  1. Add Memory and Context:
from orca_agent_sdk.core.memory import AgentMemory

class MemoryAgent(OrcaAgent):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.memory = AgentMemory()
    
    def process_with_memory(self, prompt: str, user_id: str) -> str:
        # Retrieve conversation history
        context = self.memory.get_context(user_id)
        
        # Process with context
        result = self.process_prompt(f"{context}\n{prompt}")
        
        # Store interaction
        self.memory.store_interaction(user_id, prompt, result)
        
        return result

Explore Advanced Features

  • Agent-to-Agent Communication: Build agents that collaborate
  • Multi-Chain Deployment: Expand to Ethereum, Solana, Base
  • Enterprise Integration: Custom pricing and team management
  • Workflow Integration: Connect with 0rca Flow for complex automations

Join the Community

🆘 Troubleshooting

Common Issues

Agent won't start:

# Check Python version
python --version  # Should be 3.10+

# Check SDK installation
pip show orca-network-sdk

# Check environment variables
python -c "import os; print(os.getenv('CREATOR_WALLET_ADDRESS'))"

402 errors not working:

  • Ensure price is set to a value > "0"
  • Check that CREATOR_WALLET_ADDRESS is set
  • Verify agent has an identity wallet (check logs)

Deployment failures:

  • Check that all required files are included in ZIP
  • Verify environment variables are set correctly
  • Ensure requirements.txt includes all dependencies

Payment issues:

  • Confirm vault address is correct
  • Check that user has USDC balance and allowance
  • Verify task was created in vault before signing

Getting Help

  1. Check the logs: Your agent logs all requests and errors
  2. Test locally first: Always test with X-TEST-BYPASS: true header
  3. Verify contracts: Use a blockchain explorer to check vault status
  4. Join Discord: Get help from the community and core team

Ready to build more advanced agents? Check out our Agent SDK Documentation or explore deployment options!