Skip to main content

API (beta)

Private beta

The /v1beta API is in private beta. Keys are issued by the Flip team — contact us to join. The surface below is what beta partners integrate against; it may evolve behind the Flip-Schema-Version header until GA.

Agent Integration Prompt​

The fastest integration path: copy the prompt, paste it into Claude Code, Cursor, or any coding agent, and let it build the compose box into your app. The prompt links the agent to everything it needs (llms.txt, the API Reference, this guide).

View the full prompt
Integrate Flip into my app.

Flip is a non-custodial AI copilot for onchain finance: users describe an
outcome in plain English ("move my idle USDC into the best stable yield")
and Flip plans it - streaming its reasoning, asking clarifying questions
when needed, and returning multi-step, cross-chain UNSIGNED transactions
that the user's own wallet or MPC signer signs. Flip never holds keys,
signs, or broadcasts.

WHAT YOU ARE BUILDING: a chat experience ("Compose-in-a-box"), NOT an API
console. Single chat column, composer at the bottom, compact wallet pills
in a top bar. Reasoning, clarification chips, and the plan render inline
in the thread. Never show raw intents[]/step JSON in the primary UI;
calldata goes behind a disclosure. No "Review plan" button: when /intent
returns intents[], AUTOMATICALLY call /plan and render the steps as
readable cards in the same Flip turn, then AUTOMATICALLY call /simulate
and show per-step results (including human-readable revert reasons from
steps[].error) in the card.

Gather context from (read llms.txt first - it carries the SSE event
contract, the clarification resend template, wallet field expectations,
the simulation pattern with its bridge caveat, and the signing rules):
- Machine-readable API index: https://app.fliplabs.ai/llms.txt
  (also served at https://docs.fliplabs.ai/llms.txt)
- API Reference: https://docs.fliplabs.ai/api-reference
- Integration guide: https://docs.fliplabs.ai/for-integrators/api
- OpenAPI spec: https://app.fliplabs.ai/flip-openapi.yaml

My Flip API key is in the FLIP_API_KEY env var. Call the API server-side
(proxy browser requests through my backend so the key never ships to the
client). Log Flip request/response bodies server-side with calldata
truncated - it makes support fast. Metering is per partner key via GET
/usage; handle 402 insufficient_credits server-side / in partner ops - do
not surface a credits balance or refill CTA to end users.

Build (Tier A - plan only, no signing):
1. A chat panel that POSTs /intent (base: https://app.fliplabs.ai/api/v1beta)
   with Accept: text/event-stream and streams the reasoning live into the
   Flip bubble.
2. Multi-turn via conversation_context and clarification chips via
   clarify_follow_up, per llms.txt.
3. Auto-/plan on intents, auto-/simulate on the plan, step cards inline.
   Never sign or broadcast in Tier A.

If I asked for signing (Tier B), also:
4. A per-step Sign action using my existing signer (MetaMask/Phantom/MPC),
   executing steps in ascending order - approve confirms before swap;
   soft-disable later steps until prerequisites clear; respect
   wait_for_bridge before simulating or signing post-bridge steps.
5. ALWAYS POST /steps/reencode immediately before signing and hand the
   FRESH calldata to the wallet (actual_amount = step.amount, or
   step.chained.estimate_amount for chained steps - decimal token units,
   never derived from hex). If reencode returns an HTTP error or ok:false,
   DO NOT fall back to plan-time calldata: show unsupported_reason in the
   chat and stop. Browser-wallet warnings like "insufficient ETH for gas"
   or "likely to fail" are usually mislabels for stale quotes - trust
   Flip's simulate/reencode errors first.
6. After broadcast, show the tx hash + explorer link. Never imply Flip
   signed or broadcast anything.

If I asked for agents (Tier C - standing monitors, independent of A/B):
7. Agents are Flip's persistent monitors - price, yield, health factor,
   portfolio move, schedule, plus plain-English conditions ("notify me when
   my health factor drops below 1.5"). Phase A is READ-ONLY and notify-only:
   they observe and emit an event, they never sign, and they work on any
   address with no connected session. Create with POST /agents (REST) or the
   flip_agent_create tool (MCP) — either typed ({kind, wallets, ...}) or
   plain English ({request, wallets}). Field names are snake_case on BOTH
   surfaces.
8. Fires reach you two ways. The PULL rail - GET /agent-events, or
   flip_agent_events over MCP - always works and needs zero setup, so build
   that first. Registering a receiver (POST /webhook-endpoints /
   flip_webhook_endpoint_create) is OPTIONAL but PREFERRED: pushes are HMAC-signed
   (verify against the RAW body) and at-least-once, so dedup on the event id.
9. Read https://docs.fliplabs.ai/for-integrators/agents before building
   either rail - it carries the things that otherwise cost an evening: the
   public id scheme (w_{type}_{id}, store and pass back verbatim, never
   rebuild it from `kind`), the clarification round-trip (a 200, not a 201 -
   branch on the body), signature verification, and the firing semantics
   (~5 min evaluation, edge-triggered, first check only sets a baseline).
10. Verify with POST /agents/{id}/test (or flip_agent_test) - deterministic,
   immediate, and it
   exercises the identical delivery path a real trigger uses. Never wait on a
   natural market move to prove an integration works.

Prefer to read the contract yourself? The API Reference documents every endpoint: required and optional inputs, response structures, and error codes — generated from the OpenAPI spec.

MCP server​

Agent-native integrations can skip raw HTTP: a hosted MCP server exposes the same engine as tools (flip_intent, flip_plan, flip_simulate, flip_reencode, flip_usage), plus the full agent/webhook surface (flip_agent_*, flip_webhook_endpoint_*) covered on Agents — REST or MCP, same capabilities. One command to add it:

claude mcp add --transport http flip https://app.fliplabs.ai/api/mcp \
  --header "Authorization: Bearer fk_beta_..."

Cursor — project .cursor/mcp.json (gitignore it; the header value is the full Bearer fk_... string):

{
  "mcpServers": {
    "FlipLabs": {
      "url": "https://app.fliplabs.ai/api/mcp",
      "headers": { "Authorization": "Bearer fk_..." }
    }
  }
}

Works with any MCP client that speaks Streamable HTTP (Claude Code, Cursor, Claude Desktop). Same key, same metering, and the same non-custodial boundary: tools return data and unsigned transactions only — nothing is ever signed or broadcast. The tools are the engine — a host UI built on them should still be chat-shaped (see the UI guidelines below).

What the API does​

Turn a plain-English outcome into a ready-to-sign, multi-step, cross-chain transaction plan. Flip is non-custodial: the API returns unsigned transactions (EVM calldata + Solana messages) and your own wallet or MPC signer signs and broadcasts. Flip never holds keys, signs, or broadcasts.

  • Base URL: https://app.fliplabs.ai/api/v1beta
  • Auth: Authorization: Bearer fk_... (keep the key server-side)
  • Format: JSON in/out, all fields snake_case; every error uses one envelope { error, friendly_message, issues[] }
  • Metering: 5 credits per delivered call, per-tenant balance

The flow​

  1. POST /intent — natural language in, structured intents[] out (or clarifications[] when the request is ambiguous). Streams as SSE with Accept: text/event-stream.
  2. POST /plan — the intents[] in, unsigned steps[] (real calldata) out.
  3. POST /steps/reencode — re-quote a single step at sign time (required for chained/max amounts and expiring routes).
  4. Optionally POST /simulate to dry-run the steps before signing.
curl https://app.fliplabs.ai/api/v1beta/intent \
  -H "Authorization: Bearer fk_beta_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt":"move my idle USDC into the best stable yield","wallets":[{"address":"0x8f2a...d5","chain":"ethereum"}]}'

Agents & webhooks​

Programmatic alerts — price / yield / health-factor / portfolio-move / schedule / a plain-English condition — also ship in this /v1beta API: POST /agents to create one, GET /agent-events to pull triggers, and POST /webhook-endpoints to have triggers pushed to you (signed, recommended) instead of polling. Full walkthrough, the typed-kind field reference, and the signature-verification snippet: Agents.

UI guidelines — build a Compose, not a console​

Flip's product surface is a chat experience: prompt → streamed reasoning → clarifications → plan → sign. Integrations should feel like Compose-in-a-box.

  • Single chat column, composer pinned at the bottom — not a multi-panel dashboard. Wallet connect stays compact (top-bar pills), never a sidebar.
  • Reasoning, clarification chips, and the unsigned plan render inline in the thread, under the Flip message that produced them.
  • Auto-/plan when intents[] arrives, and auto-/simulate on the result — no manual "Review plan" click on the happy path. Render each step as a readable card (title, chain, protocol); calldata goes behind a disclosure, never a wall of hex.
  • Don't put intents[]/step JSON in the primary UI — structured payloads belong in logs.
  • Copy sounds like chat ("Message Flip…"), with 2–3 example prompts as empty-state chips.

Anti-patterns: two-column "Wallets | Compose" dashboards · a required "Review plan" click · primary UI that is mostly OpenAPI-shaped JSON.

Signing (Tier B)​

Tier A integrations prove the engine plan-only and never sign. When you add a signer:

  • Execute steps in ascending order — approve confirms before swap; soft-disable later Sign actions until prerequisites clear (allowance, bridged funds, chained amounts); respect wait_for_bridge. Guidance, not server-enforced — but out-of-order signing produces wallet failures.
  • Always re-encode before signing (POST /steps/reencode), hand the fresh calldata to the wallet, and sign promptly — responses carry quoted_at; quotes are perishable, re-encode again if the user idles.
  • Hard-fail on re-encode failure: if /steps/reencode returns an HTTP error or ok: false, do not fall back to plan-time calldata — show unsupported_reason in the chat and stop. Plan-time calldata embeds quote-time amounts and deadlines.
  • Trust Flip's errors over the wallet's. Browser wallets often mislabel stale quotes and reverts as "insufficient ETH for gas" / "likely to fail". Run /simulate and surface steps[].error in the chat card before opening the wallet.
  • actual_amount for re-encode = step.amount (decimal token units), or step.chained.estimate_amount for chained steps — never derived from raw hex.
  • Log Flip request/response bodies server-side (calldata truncated) plus a thin UI event log — that's what makes support handoffs fast.

Simulation​

/intent and /plan return planner/encoder estimates; the fork dry-run lives behind POST /simulate ({ chain, sender, steps[] }, one call per chain, 5 credits). Intended pattern, matching Flip's own UI: intent → auto-plan → auto-simulate → render per-step results (human-readable revert reasons in steps[].error) before sign; re-simulate after a re-encode. Bridge caveat: a batch simulates against current chain state — steps funded by a bridge that hasn't landed will falsely revert; skip them with an honest "can't simulate until the bridge arrives".

Multi-turn conversations​

/intent is stateless. Carry prior turns in conversation_context: a string of newline-joined turns, one per line, each User: <text> or Flip: <text>, most recent last, ~8 turns max. The current message always goes in prompt, never in the block.

User: what's the best stable yield on Base right now?
Flip: Aave v3 USDC on Base pays the best stable rate across your chains right now.
User: move my idle USDC there

Clarifications​

When a request is ambiguous, /intent returns intents: [] plus clarifications[], each { id, kind, question, options: [{ id, label }] }. Render the options; when the user picks one, re-send /intent with clarify_follow_up: true and prompt = the original prompt + a blank line + the answer block:

deploy my idle USDC

Clarification — Which wallet should fund this?: Main treasury (Ethereum)

The flag makes the planner acknowledge the answer and continue — it never re-asks the same clarification.

Coming soon​

  • Action agents — a trigger pre-plans a transaction for you to review and sign, not just a notification. Agents covers what ships today (Phase A, notify-only).
  • End-user push notifications — beyond the webhook delivery above (which pushes to your backend), native push notifications surfaced directly to your users through your own app, so the agent can proactively surface opportunities, not just answer prompts. Designed for guaranteed delivery: acknowledgement, retry, and dead-letter handling are part of the API contract.

Tell us if you want early access to either.

Reference​