# Social shard — SociaVault ingest

Pay-per-request social media data via [SociaVault](https://docs.sociavault.com/) with x402 USDC.

**Origin:** `https://social.gedx402.com` (deployed)

**Discovery:** `GET https://gedx402.com/v1/models?bundle=social` · `GET https://social.gedx402.com/v1/models?bundle=social` · `GET https://social.gedx402.com/openapi.json`

## Full SociaVault API (x402 catalog)

**106 paid routes** at `/v1/sociavault/*` — one x402 payment per call, mirroring [SociaVault OpenAPI](https://docs.sociavault.com/api-reference/openapi.json). Same pattern as Firecrawl (`/v1/firecrawl/*`) and Tavily (`/v1/tavily/*`).

| Hero | Route | Method | Body / query |
|------|-------|--------|--------------|
| TikTok profile | `/v1/sociavault/tiktok/profile` | GET/POST | `{ handle }` or `?handle=` |
| TikTok videos | `/v1/sociavault/tiktok/videos` | GET/POST | `{ handle, cursor? }` |
| TikTok transcript | `/v1/sociavault/tiktok/transcript` | GET/POST | `{ url, use_ai_as_fallback? }` |
| Instagram profile | `/v1/sociavault/instagram/profile` | GET/POST | `{ handle }` |
| YouTube channel | `/v1/sociavault/youtube/channel` | GET/POST | `{ handle \| url }` |
| X profile | `/v1/sociavault/twitter/profile` | GET/POST | `{ handle }` |

All other documented scrape paths live under `/v1/sociavault/<platform>/…` (Facebook ad library, Reddit, LinkedIn, Pinterest, Twitch, etc.). Regenerate from upstream OpenAPI:

```bash
npm run sociavault:catalog:build
```

## Legacy convenience routes (aliases)

| Route | Method | Body | Price (floor) |
|-------|--------|------|---------------|
| `/v1/social/outcome/profile` | GET/POST | `{ platform, handle? \| user_id? \| url? }` | $0.02 |
| `/v1/social/outcome/posts` | POST | `{ platform, handle?, cursor? }` | $0.02 |
| `/v1/social/outcome/transcript` | POST | `{ platform, url, ai_fallback? }` | $0.02–$0.15 |
| `/v1/social/proxy` | POST | `{ path: "/v1/scrape/...", query?, body? }` | $0.02+ |

**Platforms (legacy `platform` field):** `tiktok`, `instagram`, `youtube`, `twitter`, `facebook`, `linkedin`, `reddit`, `threads`.

Prefer **`/v1/sociavault/*`** for new integrators — typed paths, OpenAPI discovery, same backend.

## Operator secrets

Keys live in **Cloudflare Secrets Store** — not `ged/.env`. See `ged/ged-vault.json`.

| Variable | Shard | Purpose |
|----------|-------|---------|
| `SOCIAVAULT_API_KEY` | **social** | SociaVault `X-API-Key` ([dashboard](https://sociavault.com/dashboard)) |
| `RESEND_API_KEY` | browser + social (optional) | Operator credit alert email |
| `OPERATOR_ALERT_WEBHOOK` | browser + social (optional) | JSON webhook when credits low/exhausted |
| `OPERATOR_ALERT_EMAIL` | var in `wrangler.toml` | `jvalamis@gmail.com` |

```bash
# From ged repo — inventory / rotation
npm run ged:vault -- --inventory
npm run ged:vault -- --push --sync-workers --from-env /path/to/secrets.env

cd ../ged-x402
npm run deploy -- --shard=social
npm run sociavault:probe
```

**COGS:** Starter plan **$0.0048/credit** ($29/6k). Most calls = **1 credit**; transcript AI fallback = **10 credits**. Free tier = 100 credits ([quickstart](https://docs.sociavault.com/quickstart)).

## Operator MCP (optional)

Customers use x402 routes above. For **Cursor operator** dev, [SociaVault MCP](https://docs.sociavault.com/mcp-server) (107 tools):

```bash
npm run ged:sociavault-setup   # vault-bootstrap on MCP start; wires .cursor/mcp.json
```

GED agent: `ged/.cursor/agents/sociavault.md`. No MCP install required for paying agents.

## Operator alerts

On SociaVault **5xx** upstream failures, the social worker emails via Cloudflare Email Sending / MailChannels. See `KEYS-SETUP.md` for `OPERATOR_ALERT_*` bindings.

## Example (external payer)

```bash
# Catalog route (preferred)
curl -X POST "https://social.gedx402.com/v1/sociavault/tiktok/profile" \
  -H "Content-Type: application/json" \
  -d '{"handle":"stoolpresidente"}'
# → 402 + x402 payment requirements

# Legacy hero
curl -X POST "https://social.gedx402.com/v1/social/outcome/profile" \
  -H "Content-Type: application/json" \
  -d '{"platform":"tiktok","handle":"stoolpresidente"}'
```

Hero: [social profile](https://gedx402.com/heroes/social-profile)

See [EXTERNAL-PAYER.md](./EXTERNAL-PAYER.md) for wallet flow.