Flip API (1beta)

Wraps the app's /api/intent planner — same model routing, tools, and clarification logic. Natural language in; a structured intents[] plan out (or clarifications[] when ambiguous). Costs 5 credits per delivered call.

Multi-turn: pass prior turns in conversation_context — newline-joined User: <text> / Flip: <text> lines, most recent last, ~8 turns max — with the current message in prompt (see the followUp example).

Clarification round-trip: when clarifications[] comes back, render the options[]; on pick, re-send with prompt = original prompt + "\n\n" + Clarification — <question>: <picked label> and clarify_follow_up: true so the planner acknowledges the answer and continues (see the clarifyAnswer example).

Send Accept: text/event-stream to stream the build as Server-Sent Events; otherwise a single JSON body is returned once planning completes.

Wraps the app's /api/intent-plan resolver — trusted-vault gating, Pendle-PT expansion, route prefetch, feasibility checks, and the repair pass are all inherited. Takes the intents[] from /intent (or hand-built to the same shape) plus the signing wallets[] with their on-chain balances, and returns the ordered steps[] of unsigned transactions. Costs 5 credits per call.

Wraps the app's /api/re-encode-step. Re-encodes one step against the real amount available at sign time — required for correct integrations: chained and max amounts are re-sized from live balances, and expiring routes (Jupiter blockhash, LiFi tool pinning) are refreshed so the user signs the same aggregator and fee structure they were quoted. Returns 409 with error: route_expired when a pinned route is gone and the step must be re-planned via /plan.

Wraps the app's simulation layer (Tenderly for EVM, a Solana simulate for Solana). Executes the steps[] against a fork and returns per-step success, status, and gas so you can surface reverts and cost before anything is signed. Read-only — nothing is broadcast. Costs 5 credits per call.

Calldata-bearing steps are pre-validated against the target address: a step that CALLS an address with no deployed code (dead or self-destructed contract) returns 400 before any simulation runs. Plain value transfers to EOAs are exempt and simulate normally.

The current per-tenant credit balance, the flat per-call cost, and the most recent metered calls. Reads are free (not metered). This is integrator/partner metering — for checking balances and debugging 402s in your own ops, not an end-user UI element. Don't render a credits balance or refill CTA in the end-user Compose chat.

Machine-readable capability discovery: the current schema version, the flat per-call credit cost, the supported intent actions, the supported chains, and the rate-limit tiers. Feature-detect from this rather than hard-coding. Free.

Send either a plain-English body { request, wallets } or a typed body { kind, wallets, ... } — never both, never neither (400 otherwise). Not metered by credits; gated instead by a per-tenant active-agent quota (429 agent_quota_exceeded once the tier cap is hit — beta 50 / standard 500 / high 5000).

Plain-English ({ request, wallets }) runs the same compile pipeline the Flip app and Telegram bot use. Three outcomes:

• A concrete, measurable condition → 201 with agent + compile.
• A schedule phrase ("every day at 9am...", no measurable condition) → 201, created as a kind: schedule agent.
• Ambiguous → 200 with status: needs_clarification, a question, and up to 4 options. Re-submit by sending request again with the picked option folded in: "<original request>\n\nClarification — <question>: <picked label>" — the same inline convention /intent's clarification round-trip uses, just folded into the next request string (there's no multi-turn state to carry here).
• Not a watchable condition, or refused by an internal match-gate (the compiled check doesn't faithfully match what was asked) → 422 unwatchable.

Phase A is notify-only. Even when the compiler recognizes a "when X, do Y" request with a real follow-on action, the agent is armed as notify-only and the action is dropped — action agents over the API are a later phase.

Typed ({ kind, wallets, ... }) maps 1:1 onto the internal create paths for price / yield / health / portfolio / schedule — no compile step, no LLM call, always 201. kind: "condition" is not a typed-create kind — it only results from the plain-English path.

For kind: "price", coingecko_id is required in the request — this endpoint does not resolve a ticker symbol to a CoinGecko id for you; look it up first (e.g. CoinGecko's /coins/list) and pass the id directly (e.g. "ethereum", not "ETH").

Fires are delivered to any webhook endpoints you've registered (POST /webhook-endpoints) — recommended, so you don't have to poll. With none registered, a agent still arms, evaluates, and triggers normally; retrieve its triggers from GET /agent-events instead.

Tenant-scoped, newest-first, offset-paginated. Both status and kind filter against the public vocabulary shown on the returned agent objects (not the internal per-table storage) — see the callouts on each parameter below.

Send either { status } or { request }.

{ status: "paused" | "active" } works identically on any agent kind — the public vocabulary is always active/paused regardless of what's stored internally per kind (see the Agent.status schema note). An id that's well-formed but doesn't resolve to a row you own (already deleted, or another tenant's) is 404, not 500.

{ request: "<new plain-English text>" } only works on kind: "condition" agents (400 on any other kind — delete and recreate a typed agent instead). Re-runs the same compile pipeline POST /agents uses and mirrors its outcomes 1:1: ready → 200 { agent } (in place — same id, trigger history reset, matching the app's own edit-a-condition-agent behavior); ambiguous → 200 { status: "needs_clarification", ... }; not watchable → 422 unwatchable.

A structurally-invalid id (doesn't match the w_<type>_<id> shape) is 404.

Idempotent: a well-formed id whose row is already gone (e.g. a repeated delete, or a retry after a timed-out first attempt) returns 204 as a no-op — it never distinguishes "already gone" from "just deleted" in the response.

Queues a synthetic trigger through the exact same delivery pipeline a real trigger takes (webhook push + the GET /agent-events pull rail both see it), flagged type: "agent.test" — independent of whether the agent's real trigger is currently met. 202 because the event is queued into the same delivery sweep a real trigger uses, not returned inline; it typically lands within the next delivery-cron tick (every 2 minutes).

Tenant-scoped trigger history, newest-first, cursor-paginated on triggered_at. This is how a partner without a registered webhook endpoint reconciles triggers, and how any partner replays or backfills around a delivery gap. Delivery (both this rail and the webhook push rail below) is at-least-once — dedup on id regardless of which rail an event was read from.

Note: this rail and the pushed webhook body (see the webhooks section) are built from the same event mapping — id, type, agent, and the set of trigger fields are identical for the same trigger on both rails. The one intentional difference is the timestamp: this rail returns created_at as an integer epoch-ms, while the pushed webhook body returns created as an ISO-8601 string, for the same instant. Both rails' trigger objects are snake_case (e.g. value_at_trigger), so a handler can parse either rail's event with the same code.

Sent to every active endpoint registered for your tenant whenever a agent of yours triggers (including test triggers from POST /agents/{id}/test, which carry type: "agent.test"). Delivery is at-least-once — dedup on the payload's id (identical to the X-Flip-Event-Id header), never assume single delivery.

Acknowledge with any 2xx status within 10 seconds. Anything else — non-2xx, a timeout, or a redirect (redirects are never followed) — counts as a failed attempt and is retried with backoff: 1m → 5m → 30m → 2h → 12h after attempts 1 through 5, then the delivery is dead-lettered (no further retries for that specific trigger). An endpoint that racks up 10 consecutive dead-lettered deliveries is auto-disabled (GET /webhook-endpoints will show status: "disabled") — re-register or fix your receiver and the next trigger goes to a healthy endpoint again.

Structurally identical to the GET /agent-events pull-rail's event shape for the same trigger — id, type, agent, and the set of trigger fields all come from the same event mapping. Two differences to know about:

• The timestamp here is created (an ISO-8601 string); the pull rail's equivalent is created_at (an integer epoch-ms) — same instant, different field name and format.
• Both rails emit snake_case keys inside trigger (e.g. value_at_trigger), matching every other public object in this API.

In both rails, agent.id is the SAME public w_<type>_<id> value returned by create/list/get — pass it straight back to /agents/{id}, /agents/{id}/test, PATCH or DELETE without rebuilding it. Note the prefix is the storage type (alert | condition | reminder), NOT the public kind: a kind: "price" agent is w_alert_..., so kind alone is not enough to construct the id — which is why the event carries it. It is identical across both rails for the same trigger, including manual test-triggers (POST /agents/{id}/test) of every kind.

https:// only; the hostname can't be a raw private/loopback/link-local IP literal (including the 169.254.169.254 cloud metadata address), localhost/*.localhost, or *.local/*.internal — 400 invalid_url otherwise. This is a hostname/IP-literal check only; a public hostname that later resolves to a private address is re-checked at every send, but not pinned against rebinding between check and connect.

Maximum 5 endpoints per tenant — exceeding it is 429 endpoint_quota_exceeded. Remove an old endpoint first if you're unsure how many you have registered (GET /webhook-endpoints).

The response's signing_secret is shown exactly once — store it now. It is not derived from anything you can look up later; only its hash is kept server-side. See the webhooks section for how to verify it against inbound deliveries.

Never includes secrets — only the POST response ever carries the raw signing_secret.

Idempotent: an id that doesn't resolve to a row you own (already removed, or another tenant's) still returns 204 as a no-op.