nexus-agent-sdk 1.0.0
Official Python SDK for NEXUS AI Agent Marketplace - Discover, test, and integrate APIs for AI agents
License: MIT
Requires Python: >=3.8
Keywords: ai, agents, marketplace, mcp, x402, langchain, llamaindex, autogpt, sdk, api

# NEXUS AI Agent Marketplace - Python SDK

The official Python SDK for integrating AI agents with the NEXUS marketplace. Discover, test, and use 29+ premium APIs with simple pay-per-request pricing.

## Features

- 🔍 **Service Discovery** - Search and filter 29+ production-ready APIs
- 🆓 **Free Sandbox** - 50 free calls per tool to test before you pay
- 💰 **Pay-per-Request** - Only pay for what you use with x402 payments
- 🔌 **MCP Compatible** - Works with any MCP-compatible agent
- ⚡ **Async Support** - Both sync and async clients available
- 🔗 **Framework Integration** - LangChain, LlamaIndex, AutoGPT ready

## Installation

```bash
pip install nexus-agent-sdk
```

For async support:
```bash
pip install nexus-agent-sdk[async]
```

## Quick Start

```python
from nexus_sdk import NexusClient

# Initialize client
client = NexusClient()

# Discover available tools
tools = client.list_tools()
print(f"Found {len(tools['tools'])} tools")

# Try a tool for free (sandbox mode)
result = client.execute_sandbox(
    tool_name="weather-forecast-api",
    parameters={"location": "San Francisco"},
    agent_id="my-agent-001"
)
print(result)
```

## Available APIs

| Category | Examples | Price Range |
|----------|----------|-------------|
| **AI/ML** | Sentiment, Translation, NER, Summarization | 0.4 - 2.0 credits |
| **Finance** | Crypto prices, Stock data, Forex rates | 0.1 - 0.5 credits |
| **Data** | News, Company info, WHOIS lookup | 0.2 - 1.5 credits |
| **Utility** | Weather, Geocoding, Email validation | 0.1 - 0.8 credits |
| **Communication** | SMS, Email sending | 0.5 - 2.0 credits |

## Usage Examples

### Search for Services

```python
# Search by keyword
results = client.search(query="weather")

# Filter by category
ai_services = client.search(category="ai")

# Get sandbox-enabled services only
free_to_try = client.search(sandbox=True)

# Combined filters
results = client.search(
    protocol="mcp",
    category="finance",
    max_price=1.0,
    limit=10
)
```

### Use Sandbox (Free Tier)

Every tool offers 50 free sandbox calls:

```python
# No payment required!
result = client.execute_sandbox(
    tool_name="sentiment-analysis",
    parameters={"text": "I love this product!"},
    agent_id="my-agent"
)

print(result)
# {'sentiment': 'positive', 'score': 0.95, 'remaining_calls': 49}
```

### Make Paid Calls

```python
# Generate payment proof
proof = client.generate_payment_proof(
    agent_id="my-agent",
    amount=0.5
)

# Execute with payment
result = client.execute_tool(
    tool_name="weather-forecast-api",
    parameters={"location": "Tokyo"},
    agent_id="my-agent",
    payment_proof=proof['proof']
)
```

### Async Client

```python
import asyncio
from nexus_sdk import AsyncNexusClient

async def main():
    async with AsyncNexusClient() as client:
        # All methods are async
        tools = await client.list_tools()
        result = await client.execute_sandbox(
            tool_name="crypto-price-tracker",
            parameters={"symbol": "BTC"},
            agent_id="async-agent"
        )
        print(result)

asyncio.run(main())
```

## Framework Integrations

### LangChain

```python
from langchain.tools import Tool
from nexus_sdk import NexusClient

client = NexusClient()

# Create LangChain tools from NEXUS services
tools = []
for service in client.list_tools()['tools']:
    tool = Tool(
        name=service['name'],
        description=service['description'],
        func=lambda params, sid=service['service_id']: 
            client.execute_sandbox(sid, params, "langchain-agent")
    )
    tools.append(tool)
```

### LlamaIndex

```python
from llama_index.tools import FunctionTool
from nexus_sdk import NexusClient

client = NexusClient()

tools = []
for service in client.list_tools()['tools']:
    tool = FunctionTool.from_defaults(
        fn=lambda **kwargs: client.execute_sandbox(
            service['service_id'], kwargs, "llamaindex-agent"
        ),
        name=service['name'],
        description=service['description']
    )
    tools.append(tool)
```

## API Reference

### Client Methods

| Method | Description |
|--------|-------------|
| `list_tools()` | List all available MCP tools |
| `search(**filters)` | Search services with filters |
| `execute_sandbox(tool, params, agent_id)` | Free sandbox call |
| `execute_tool(tool, params, agent_id, proof)` | Paid tool execution |
| `trending(limit)` | Get trending services |
| `get_service(id)` | Get service details |
| `get_service_metrics(id)` | Get usage metrics |

### Error Handling

```python
from nexus_sdk import NexusClient, NexusError, NexusRateLimitError

client = NexusClient()

try:
    result = client.execute_sandbox(...)
except NexusRateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except NexusError as e:
    print(f"Error: {e.message}")
```

## Getting Started Credits

New agents automatically receive **100 free credits** on first API call, plus **50 free sandbox calls per tool**. No credit card required!

## Support

- 📖 [Documentation](https://docs.nexus-marketplace.com)
- 💬 [Discord Community](https://discord.gg/nexus-marketplace)
- 🐛 [Issue Tracker](https://github.com/nexus-marketplace/python-sdk/issues)
- 📧 [Email Support](mailto:support@nexus-marketplace.com)

## License

MIT License - see [LICENSE](LICENSE) for details.