# WaveSurge user guide

How to use WaveSurge at every step: signing in, creating a project, finding creators, outreach, contracts, delivery and reporting.

Updated 2026-10-10

## Getting started

WaveSurge is an AI creator-marketing platform. You describe what you need in plain language; the platform drafts the strategy, finds the right creators on TikTok, Instagram, YouTube and X, then runs outreach, negotiation, contracts, delivery, payment and reporting. All work happens inside a project and its Campaign.

1. Sign in to https://wavesurge.ai with Google. New accounts start with 58 credits.
2. On the home page click "Start your first project", give the project a name and open Chat.
3. In Chat, describe your brand website, target markets, budget, goals, platforms and the creators you want. You can also drop files straight in.
4. Once the requirements are complete, say "create a Campaign", or click "Find creators" to start searching.
5. Review the list in Creator, set collaboration terms in Rule, and contact and negotiate in Outreach.
6. After signing, track delivery and payment in Campaigns, then review results in Simulation and Analytics.

| Page | What it does |
| --- | --- |
| Overview | Budget, send progress, pending payments and items that need you, for the current Campaign |
| Chat | Describe requirements, upload files, generate reports, find creators, change collaboration rules |
| Creator | The Campaign's creator list: filter, view details, export, remove |
| Rule | Collaboration rules: payment milestones, price caps, follow-up cadence, usage rights, content review flow, brief assets |
| Outreach | First contact, replies, quote approval, negotiation |
| Campaigns | Post-signing delivery workspace: review content, request changes, message creators, payment milestones |
| Simulation | Model reach, visits and conversions for the creators you have agreed terms with |
| Analytics | Measured results, content performance and forecast vs actual |
| Money | Credit balance, activity, cost estimator and top-ups |

> **Before a project has a Campaign**: Every page except Chat is greyed out. Create the Campaign in Chat first; the other pages fill in from there.

## Chat: requirements and reports

- Every requirement you state is saved to the project brief, so it survives a refresh or another device. Chat proposes related requirements from what you have already said and saves only the ones you confirm.
- Drag, paste or attach files: up to 5 files per message, 100 MB each — PDF, Word, PowerPoint, Excel, CSV, text and images.
- When something is missing, chat asks for it in its reply, with an example answer. Chat can also search the web and read pages on its own.
- Strategy report (400 credits each): positioning, audience, platforms, creator direction, content and execution. Competitor report (500 credits each, however many competitors are scanned): how competitors perform on each platform and where the openings are. Both are optional.
- Give each competitor as a website or an X, TikTok, Instagram or YouTube profile; entries that are only a brand name are not scanned.
- Reports are horizontal slide decks that you can download as a web page or print to PDF. The report language can be switched next to the input box.
- Collaboration rules can be set in Chat too, e.g. "pay in three parts 30/40/30" or "hold payment 72 hours after posting".

> **Paid work always asks first**: Chat never starts paid work on its own. When you ask for a report or a creator search (or click "Generate strategy report", "Find creators" and similar buttons), the reply lists what will run, who pays and how many credits; nothing starts and nothing is charged until you reply to agree, for example "OK". Through the API, the same quote is POST …/confirmations and is approved by …/confirm.

## Creator: finding creators

- Set a count per platform: 1–2000 creators per platform and no more than 5000 across all platforms in one order.
- Criteria include creator persona, market, language, follower range, account type, exclusions, recent activity and whether a public contact is required.
- Searches run in the background and usually take a few hours — no need to wait on the page; you are notified when it finishes.
- Each delivered creator lists, condition by condition, whether your requirements are met, with the evidence and source links.
- Delivered creators come with an audience profile (gender, age, country), shown in card view. It is made automatically after delivery and charged at its measured cost (the data and model calls it makes, with our markup).
- Export the list as card PDFs (up to 1,000 cards) or Excel (no limit).
- To pull raw Instagram data through the API and screen it yourself, use the three GET endpoints under "API → Instagram raw user search API". The delivery and billing rules below apply to in-app Campaign searches.
- You can also upload your own creator list or add creators by hand. Removing a creator from the list is not charged.
- Billing: 10 credits per creator actually delivered, plus the real call costs of the search. The order amount is reserved up front and settled when the search ends; unused credits are refunded, and a search that does not run is refunded in full.

## Rule, Outreach and signed deals

- The rules set in Rule (payment milestones, price caps, usage rights, exclusivity, review flow and more) are shared by outreach, negotiation and contracts.
- Starting outreach charges 6 credits per contactable creator; nothing is charged if no one is contactable. Follow-ups and AI-drafted negotiation replies cost 1–1 credits each.
- When a creator quotes, the AI records the facts and waits for your decision; it never accepts or counters on your behalf.
- Once terms are agreed, a contract is generated and sent after you check the scope and funding. Signed creators move into the Campaigns delivery workspace.
- Review every content version in Campaigns and approve it or request changes. Content pre-review costs 4 credits per item.
- Every payout requires you to check the exact amount and approve it explicitly.
- Sending can be paused or resumed at any time from the Campaign menu.

## Credits and pricing

| Action | Price |
| --- | --- |
| Chat, and the work done inside it (editing requirements, writing rules, creating a Campaign, reading uploaded files) | Each reply: its measured model cost with our markup. A hold is taken before the reply and the unused part is returned |
| Checking progress, opening results, reading the price | Not charged: no model runs |
| Strategy report | 400 credits per report |
| Competitor report | 500 credits per report |
| Finding creators | 10 credits per creator delivered + the real call costs of the run; + 4 per delivered creator with an email address. A delivered creator without one pays 2 + the email lookup's cost (at most 4) instead of the 10 |
| First outreach | 6 credits per contactable creator |
| Follow-up message | 1 credits per message |
| AI negotiation reply | 1 credits per reply |
| Content pre-review | 4 credits per item |

- The Money page shows your balance, spend by action, credit activity and a cost estimator, and sells credit packs (card or PayPal).
- When paid work fails or does not run, the reserved credits are returned; submitting the same task twice never charges twice.
- Creator fees, the platform service fee and the Campaign budget are settled in US dollars, separately from credits.
- Current prices are published at https://wavesurge.ai/api/v1/pricing.

## Team collaboration

- With a Campaign selected, click Team in the project switcher to invite members; several emails can be entered at once.
- Members join as Managers: they can operate the project, and paid actions are charged to the project Owner's wallet. A Manager can leave at any time.
- Only the Owner can delete the project and manage members.

## Connect Codex, Claude Code, Claude Desktop, Cursor or another AI tool

Connect an AI tool to your account and you can estimate, start, check and cancel a creator search from a conversation in it. Each search is a normal Campaign in your account, so its creators also appear on the Creator page. The page https://wavesurge.ai/app/connect-ai gives the same setup for each tool.

### Sign in (no key): Claude and Codex

1. Claude (desktop or web): open Plugins in the left sidebar, click Add, then Add custom connector (older versions: Settings → Connectors → Add custom connector). Name it WaveSurge, set the MCP server URL to https://wavesurge.ai/api/v1/mcp/creator-search, click Continue, leave the sign-in option as it is, then click Add. If the WaveSurge sign-in page does not open, find WaveSurge under Your plugins and click Connect.
2. Click Connect. A WaveSurge page opens; sign in if asked and click Allow. You return to Claude, connected.
3. Codex app: open Plugins in the sidebar, click Add, then choose Add MCP server (not "Add custom MCP server"; older versions: Settings → MCP servers → Add server). Name it WaveSurge, choose Streamable HTTP, enter the same MCP server URL and save. Under My MCPs, click Restart, then Authenticate next to WaveSurge; the same WaveSurge page opens; click Allow.
4. Codex in the terminal (the app and the terminal share one setup, so either way is enough): run the command below once. Your browser opens the same WaveSurge page; click Allow.
5. Check it: start a new conversation and say "List my WaveSurge projects." If they appear, you are connected; this spends no credits. To disconnect a tool, revoke its key named "<tool> (signed in)" on the Connect AI tools page (https://wavesurge.ai/app/connect-ai).

Codex sign-in. If you added wavesurge with a key before, run codex mcp remove wavesurge first.:

```bash
codex mcp add wavesurge --url https://wavesurge.ai/api/v1/mcp/creator-search
```

### With an API key: Cursor and other tools

1. Sign in, open https://wavesurge.ai/app/connect-ai and create an API key. The page fills the key into the setup for each tool; the full key is shown only once, so if you lose it, revoke it and create another.
2. Copy the setup for your tool below (or from that page) and replace YOUR_API_KEY with your key.
3. Open a new conversation in the tool. The WaveSurge tools appear only in a new one. Never paste the key into a conversation.

Codex, macOS (on Linux with bash, change ~/.zshrc to ~/.bashrc). Codex reads the key from the WAVESURGE_API_KEY environment variable.:

```bash
echo 'export WAVESURGE_API_KEY=YOUR_API_KEY' >> ~/.zshrc && export WAVESURGE_API_KEY=YOUR_API_KEY && codex mcp add wavesurge --url https://wavesurge.ai/api/v1/mcp/creator-search --bearer-token-env-var WAVESURGE_API_KEY
```

Codex, Windows PowerShell:

```bash
setx WAVESURGE_API_KEY YOUR_API_KEY; $env:WAVESURGE_API_KEY = 'YOUR_API_KEY'; codex mcp add wavesurge --url https://wavesurge.ai/api/v1/mcp/creator-search --bearer-token-env-var WAVESURGE_API_KEY
```

Claude Code (macOS, Linux or Windows):

```bash
claude mcp add --scope user --transport http wavesurge https://wavesurge.ai/api/v1/mcp/creator-search --header "Authorization: Bearer YOUR_API_KEY"
```

Claude Desktop: open the Claude menu, then Settings… → Developer → Edit Config (it opens the config file, and creates it if missing). Paste this in, save, then quit and reopen Claude Desktop. Needs Node.js. The file is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows.:

```bash
{
  "mcpServers": {
    "wavesurge": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://wavesurge.ai/api/v1/mcp/creator-search", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer YOUR_API_KEY" }
    }
  }
}
```

Cursor (~/.cursor/mcp.json) and other tools with a JSON config:

```bash
{
  "mcpServers": {
    "wavesurge": {
      "url": "https://wavesurge.ai/api/v1/mcp/creator-search",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

A tool without a JSON config takes the same two values: type Streamable HTTP (some call it HTTP), the address above, and the header Authorization: Bearer followed by your key.

> **If the tool only says the WaveSurge tools are unavailable**: The key is wrong or revoked. For Codex, WAVESURGE_API_KEY must also be set in the terminal that started it; open a new terminal after running the command.

| Tool | What it does |
| --- | --- |
| list_projects / create_project | Your projects, or a new one with its requirements, as in the web app. |
| get_project / update_requirements | The project's requirements and what finding creators still needs, the same list the web page shows. The tool asks you those questions in one message, or gives you a link to fill the same form on the web. Saving answers works like the requirements form. |
| estimate_report / start_report | Quote a strategy or competitor report, then generate it only after you approve its scope and total credits. Both use the same prices and payment rules as the web app. |
| get_report / read_report | Check the exact report task and read its delivered content, including saved language versions. Viewing starts no paid work. |
| estimate_creator_search | The likely cost and the most it can cost for finding creators on this project, for both a fast search (Fit and Influence) and a deep search (adds contacts and audience profiles), as the web app shows them. Nothing is created or reserved. |
| start_creator_search | Starts a fast or deep search, like the two start buttons in the web app, up to the most credits you allow. If the price is above your amount, nothing starts. |
| list_project_members | Read the owner, team and your permissions for a draft or activity. |
| prepare_project_member_change / apply_project_member_change | Review and save collaborator changes, including drafts before paid work. Draft additions send no invitation notice. |
| prepare_project_transfer / transfer_project_ownership | Review and transfer ownership to an existing signed-in account. Clear old team grants and preserve historical bills; protected obligations can block transfer. |
| prepare_project_deletion / delete_project | Review and remove a project, retaining protected history or archiving when required. |
| get_creator_search | Whether the search is working, needs you or is done; when done, the creators exactly as its web page lists them, closest Fit first; influence is 0-100 against creators on the same platform and empty when there are too few posts, each with its fit (1-10 against this brief) and fitReason (one sentence on why), plus competitorRisk (one sentence) on a creator whose recent posts are paid promotion for a competitor the brief names, with its saved shortlist/maybe/reject selection and that page's link. A creator with backup: true filled a short count because the project allowed backups: every requirement met, the description only partly; listed after the matching creators and billed the same. |
| cancel_creator_search | Stops a running search. Creators already found are charged at actual cost; the rest of the credits return. |
| estimate_audience_profiles | Quotes continuing budget-paused audience profiles, with the number of creators, charges so far, additional cap and new maximum total. Starts nothing. |
| confirm_audience_profiles | Continues the quoted profiles only after approval. Uses the unchanged signed quote; repeating the same confirmation never adds another charge. |

- The tool works on the same projects you see in the web app, with the same requirements, prices and results. Every answer includes the page link; open it signed in to see the same thing.
- Your WaveSurge account can be different from your AI assistant account. Check the WaveSurge name and email on the authorization page before allowing the connection.
- A key has no spending limit of its own: your credit balance is the limit. If the balance cannot cover a search, it waits, holding nothing, and starts by itself after you add credits, as in the web app.
- All prices are in credits. The estimate is the most a search can reserve; the credits it actually used are charged and the rest are returned. A search that delivers nobody can still charge what the run cost. Automatic audience profiles share this total; any additional budget requires confirmation on the creator list or through estimate_audience_profiles followed by confirm_audience_profiles with the unchanged quote. Both show charges so far and the new maximum total; a budget change needs a fresh quote and approval.
- A search keeps running if you close the tool. Ask it to check again later.
- A short delivery is final. Another search needs your request; the tool should not start one on its own.
- No email addresses or other contact values come back through this connection. Contact details stay in the web product, and each result links to its Campaign there.
