Metadata-Version: 2.4
Name: gocreative-agent-api
Version: 0.1.0
Summary: Pay-per-call social profile enrichment for AI agents. Instagram, TikTok, X. Powered by x402 + USDC on Base.
Project-URL: Homepage, https://api.gocreativeai.com/v1/
Project-URL: Documentation, https://api.gocreativeai.com/v1/docs
Project-URL: Source, https://github.com/gocreative-ai/agent-api-sdk-python
Author-email: Colin Hughes <colinhughes2005@icloud.com>
License: MIT
Keywords: agent,ai,enrichment,instagram,scraping,social,tiktok,twitter,usdc,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: x402[evm]>=2.0.0
Description-Content-Type: text/markdown

# gocreative-agent-api

Pay-per-call social profile enrichment for AI agents. Instagram, TikTok, X — one Python client, one wallet, one unified schema. Powered by [x402](https://x402.org) on Base.

## Install

```bash
pip install gocreative-agent-api
```

## 30-second example

```python
import os
from gocreative_agent_api import GoCreativeClient

client = GoCreativeClient(wallet_private_key=os.environ["MY_WALLET_KEY"])

# Single profiles — $0.05 each
ig  = client.enrich.instagram("nasa")
tt  = client.enrich.tiktok("tiktok")
x   = client.enrich.x("elonmusk")

print(ig["followers"], ig["business_category"])
# 104410161 Government Agencies

# Hashtag search — up to 30 results, $0.05
posts = client.search.instagram_hashtag("realestate")
print(len(posts["posts"]), "posts")

# Recent tweets — up to 30, $0.05
tweets = client.posts.x("nasa")
print(tweets["tweets"][0]["text"])
```

Every call costs $0.05 USDC, pulled automatically from the wallet you pass in. The SDK handles the HTTP 402 → sign → retry dance under the hood — your code never sees it.

## Why

You're building an AI agent that needs to know "is this Instagram handle a real business with engagement?" or "what's trending on TikTok for #fitness?" — the existing options are:

- **Scrape it yourself**: maintain proxies, handle bans, build parsers for 3 platforms.
- **Sign up for 5 different SaaS APIs**: 5 different auth schemes, 5 invoices.
- **Use this**: one wallet, one client, three platforms, sub-cent gas.

## Configuration

| Constructor arg | Env var | Default |
|---|---|---|
| `wallet_private_key` | `GOCREATIVE_WALLET_KEY` | required |
| `base_url` | – | `https://api.gocreativeai.com/v1` |
| `max_payment_usd` | – | `1.00` (per-call safety cap) |
| `timeout` | – | `60.0` seconds |

## Endpoints

| Method | Cost | Returns |
|---|---|---|
| `client.enrich.instagram(username)` | $0.05 | followers, bio, verified, business category, profile pic |
| `client.enrich.tiktok(username)` | $0.05 | followers, bio, verified, post count |
| `client.enrich.x(username)` | $0.05 | followers, bio, verified, post count |
| `client.search.instagram_hashtag(tag)` | $0.05 | up to 30 top posts (caption, likes, comments) |
| `client.search.tiktok_hashtag(tag)` | $0.05 | up to 30 top videos (plays, likes, comments) |
| `client.posts.x(username)` | $0.05 | up to 30 recent tweets (text, likes, retweets, views) |

## Cost control

- `max_payment_usd=0.10` will refuse any 402 asking more than 10¢
- Server-side responses cache for 24h, so repeat calls for the same handle return instantly (and the server still bills $0.05 — that's the deal)

## License

MIT
