| name | flipagent-onboarding |
| description | Set up flipagent — ONE API for online reselling — for the user. Handles signup, API key retrieval, MCP / SDK / HTTP configuration, and verification with a first call. Fetch this when the user asks to "use flipagent", "set up flipagent", "find me deals on eBay using flipagent", or similar. |
flipagent agent onboarding
flipagent is one API for the online reselling cycle: search active +
sold listings, score deals, quote forwarder cost, place orders, list
inventory, ship, track payouts. Today it covers eBay; future adapters
will cover Amazon, Mercari, Poshmark via the same paths.
You are an AI agent helping a user wire flipagent into their workflow.
Follow the steps in order. Don't skip Step 4 (verification) — silent
failures here become silent failures later.
Step 1 — Identify the user's runtime
Pick one based on what you know about the user. Default to MCP if the
user is talking to you through an MCP-capable host (Claude Code is the
primary). Default to SDK if the user is building Node / TypeScript
code. Default to HTTP otherwise.
| Runtime | Path |
|---|
| MCP-capable host (Claude Code, etc.) | Step 3a |
| Node / TypeScript app | Step 3b |
| Python / Go / Rust / other | Step 3c |
If unsure, ask the user.
Step 2 — Get an API key
First check FLIPAGENT_API_KEY in the environment. If present and
matching ^fa_(free|hobby|standard|growth)_[A-Za-z0-9]{16,}$, skip ahead
to verification (curl -H "Authorization: Bearer $FLIPAGENT_API_KEY" https://api.flipagent.dev/v1/keys/me should return 200).
If absent or invalid:
- Direct the user to
https://flipagent.dev/signup (open the URL if
you have a browser tool; otherwise instruct the user to open it).
Tell them: "Free tier is a one-time 1,000 credits (≈1,000 searches or 12 evaluations — credits don't refill on Free), no card."
- Ask the user to paste back the key (
fa_free_*).
- Verify:
curl -s -H "Authorization: Bearer <KEY>" https://api.flipagent.dev/v1/keys/me
Expect HTTP 200 with {"tier":"free", ...}. If 401, the key is
wrong — ask again. If network error, retry once.
- Save the key:
- For MCP / CLI flows: write to env (handled automatically by the
flipagent-cli init --mcp command in Step 3a).
- For Node projects: append
FLIPAGENT_API_KEY=<key> to .env and
ensure .env is in .gitignore.
- For shell scripts:
export FLIPAGENT_API_KEY=<key>.
Step 3 — Configure for the user's runtime
3a. MCP-capable host
Run the one-command installer. It detects the MCP host config on the
machine and writes the flipagent server entry:
npx -y flipagent-cli init --mcp
Pass --keys to skip the interactive key prompt and use the
FLIPAGENT_API_KEY env var:
FLIPAGENT_API_KEY=fa_free_xxx npx -y flipagent-cli init --mcp --keys
After the CLI exits, tell the user to restart the host. Tools
won't appear until restart.
Manual fallback — patch the host's mcpServers config:
{
"mcpServers": {
"flipagent": {
"command": "npx",
"args": ["-y", "flipagent-mcp"],
"env": { "FLIPAGENT_API_KEY": "fa_free_xxx" }
}
}
}
3b. Node / TypeScript app
npm install @flipagent/sdk
In code:
import { createFlipagentClient } from "@flipagent/sdk";
const client = createFlipagentClient({
apiKey: process.env.FLIPAGENT_API_KEY!,
});
Available namespaces (every endpoint at api.flipagent.dev/v1/*):
| Namespace | Use for |
|---|
client.items.* | active + sold marketplace search + detail |
client.categories.* | taxonomy tree + suggestions + per-category aspects |
client.products.* | flipagent-native cross-marketplace Products: list / get / resolve (ProductRef → Product) |
client.marketplaces.ebay.catalog.* | eBay's authoritative catalog (EPID), used to fill aspects before listing |
client.evaluate.* | Product/listing intelligence — pass a ProductRef (id / external listing / free-text query). Returns full MarketView + (when ref points to a specific listing) buy-decision overlay (rating / expectedNet / bidCeiling / risk). |
client.ship.* | forwarder quote + provider catalog (Operations pillar) |
client.purchases.* | buy flow — REST passthrough or bridge transport (needs /v1/connect/ebay) |
client.listings.* | seller-side inventory + offer + publish (needs /v1/connect/ebay) |
client.sales.* | seller orders + ship + refund + cancel (needs /v1/connect/ebay) |
client.payouts.* / client.transactions.* | finance — cents-int Money + lifecycle status |
client.disputes.* | returns / cases / cancellations / inquiries / payment disputes |
client.policies.* | fulfillment / payment / return policies (needs /v1/connect/ebay) |
client.forwarder.* | Planet Express inbound packages (via bridge) |
client.webhooks.*, client.capabilities.* | webhook subscriptions + agent capability discovery |
client.agent.* | OpenAI Responses-API stateful chat (preview) |
client.http.* | escape hatch for any /v1/* path not yet typed |
3c. Other languages (Python, Go, Rust, ...)
There's no language-specific SDK yet. Use HTTP directly:
curl "https://api.flipagent.dev/v1/items/search?q=canon+50mm&limit=10" \
-H "Authorization: Bearer $FLIPAGENT_API_KEY"
The OpenAPI spec is at https://api.flipagent.dev/openapi.json. Feed it
to your language's codegen (e.g. openapi-python-client,
openapi-generator) for typed bindings.
Step 4 — Verify with one harmless call
Run exactly one call to confirm the wiring is alive. Pick by runtime:
MCP (3a): Tell the user to ask their AI client "search eBay for
canon ef 50mm using flipagent". The flipagent_search_items tool should
fire and return results. If the tool doesn't appear, the client wasn't
restarted.
SDK (3b):
const r = await client.items.search({ q: "canon ef 50mm", limit: 1 });
console.log(r.items?.length ?? 0, "result(s)");
Expect 1 result(s).
HTTP (3c):
curl -s "https://api.flipagent.dev/v1/items/search?q=canon+50mm&limit=1" \
-H "Authorization: Bearer $FLIPAGENT_API_KEY" | jq .total
Expect a non-zero number.
If verification fails:
| HTTP status | Meaning | Fix |
|---|
| 401 | Key invalid or revoked | Re-do Step 2 |
| 429 | Credit budget hit (error: "credits_exceeded") or burst rate limit (error: "burst_rate_limited") | For credits_exceeded: paid tiers reset on the 1st UTC (resetAt in body); Free is a one-time grant — only path forward is upgrade at /v1/billing/checkout. For burst: back off then retry. |
| 502 | Upstream eBay transient | Retry once. If repeats, log and surface to user |
| 503 | Service-side env not configured (unusual on hosted) | Check https://api.flipagent.dev/healthz |
Step 5 — Tell the user what's possible
After verified setup, summarize the agent's new capabilities:
- Find candidates:
client.items.search({ q, status: "active" })
for live listings, status: "sold" for the sold comp set. Same
shape, one knob. Filter by price / category / GTIN / EPID at the
query level.
- Decide on a single listing:
client.evaluate.listing({ itemId })
→ composite (server fetches detail + sold + active) → rating
buy/skip + successNet/expectedNet/maxLoss + risk + recommendedExit.
This is the scoring primitive — call it per-candidate to rank.
- Estimate landed cost:
client.ship.quote({ item, forwarder }) →
total delivered cost via Planet Express (more forwarders coming).
- Sell-side (after
/v1/connect/ebay): create inventory items,
publish offers, list orders, mark shipped, fetch payouts.
The user will likely ask you to do real work (e.g. "find me canon
lenses under $100 with positive margin"). The full chain looks like:
items.search({ q: "canon lens", filter: "price:[..100]", limit: 20 })
↓ (active candidates)
for each candidate: evaluate.listing({ itemId })
↓ (server scores buy/skip + recommendedExit + risk)
ship.quote({ item: top.item, forwarder: { destState, weightG } })
↓
present top 3 to user with rationale
Reference
Compliance note
eBay's User Agreement (effective 2026-02-20) restricts unattended AI
agent access. flipagent's hosted operations are within scope; the
caller bears responsibility for their own use. If the user asks you to
auto-purchase items without human review, decline and explain the ToS
issue.
