Signo API (1beta)

Returns a complete Notify or Prepare draft and private review URL. No active agent, subscription or spending authority is created. The owner opens the review URL, connects that wallet, links Telegram and signs once to create the agent. Prepare uses the existing per-fire unsigned planner; every transaction still requires owner approval. Action requests must explicitly choose prepare; otherwise they are refused as autonomy_mismatch, not silently downgraded. There is no clarification round trip: an ambiguous or unwatchable request is a 422 with the reason. Existing authenticated partner APIs remain available. Anonymous preparation is rate limited; drafts expire after 72 hours.

The version 2 permission shape, with a partner key (agents scope) or without a key. Keyless calls are rate limited like agent drafts and stored under a public tenant that no key can read; the owner reads and authorizes on the review page. The named wallet must have Execute early access. An ineligible wallet gets 403 execute_team_only and nothing is stored. The returned message directs the owner to support@signo.fi. The protection short-form (a body with no schema_version) is retired and answers 400 with the mapping onto the permission shape. Free access. Budget and cap_per are amounts before fees; the Shield fee comes on top. cap_per may equal budget. The registered lifetime cap and token approval include a rounded-up fee buffer. Invalid budget arithmetic returns 400 invalid_budget. A chain's native coin is not supported for Execute: wrap OKB to WOKB on X Layer and ETH to WETH on Arbitrum first. Owner wallet authorization is required on the review page; nothing can spend before the owner signs. An already-true condition can fire at the first hourly check. Start after Pause re-arms the agent and can fire at the next check without a new crossing. A check blocked by sizing, balance, approval, a venue stop or a service-wide execution pause can try again while the condition stays true. After a successful firing, one execution completes that trigger; an agent that stays active normally waits for a false reading and a new crossing. Public permission drafts do not opt into repay-from-collateral continuation.

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 messages as structured user/assistant messages, oldest first, with the current message in prompt. Structured user turns can confirm an address; assistant turns and legacy conversation_context cannot (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.

Errors: 403 partner_not_configured when the tenant's partnerId is not a partner this deployment supports, and 503 engine_unreachable when the engine cannot be reached — retryable, and no credits are charged.

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.

Errors: a tenant configured for a partner gets 403 partner_scope_forbidden when every leg of the requested plan belongs to a different protocol — the plan is refused whole, not trimmed. A tenant whose partnerId is not a partner this deployment supports gets 403 partner_not_configured. When the planning engine itself cannot be reached the call returns 503 engine_unreachable; it is safe to retry and costs no credits.

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.

Errors: 503 engine_unreachable when the encoding service cannot be reached. Retryable, and no credits are charged.

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.

Errors: 503 engine_unreachable when the encoding service cannot be reached. Retryable, and no credits are charged.

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 Signo 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.

Defaults to Notify. Set autonomy: prepare to store a persistent action. Supply action for typed requests; plain-English can include the action in request. Explicit Prepare without an action returns 422. Execute requires a Shield permission and is not accepted here. Partner agents use webhooks or event polling without Telegram; keyless drafts require owner review and Telegram. Preparation delivers an unsigned handoff; every execution needs a wallet signature. Successful prepared plans use the existing 5-credit partner planning charge. Clarifications, failed plans and Notify fires are not charged. Optional idempotency_key deduplicates retries per tenant; changed bodies with the same key return 409 idempotency_conflict. Keys remain reserved after agent deletion; replaying a deleted agent returns 410 agent_deleted. Invalid action/autonomy combinations return action_required or action_requires_prepare. autonomy: execute returns 422 execute_requires_shield.

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, an 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). Agents activated from a partner surface (/surfaces/activate) also refuse it with 400 invalid_patch: their subject, field values and action were configured on the surface, so reconfigure them there or delete and recreate. { status } and DELETE work on them like any agent. 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 an 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-Signo-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, no credentials in the URL, and the hostname can't be a private/loopback/link-local/CGNAT/special-use IP literal (including the 169.254.169.254 cloud metadata address), localhost/*.localhost, or *.local/*.internal. A hostname must resolve, and every DNS answer must be a public address — checked here and again at every send; delivery then connects to the checked address (pinned, no second lookup), verifies TLS against the hostname, and never follows redirects. 400 invalid_url otherwise, with the reason as friendly_message: https_required, credentials_disallowed, private_ip, localhost, internal_hostname, private_dns_answer, no_dns_answers, dns_unresolved, dns_timeout.

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.

Returns { address, chain, linked } for a single wallet so a partner button can say Turn on (linked: true) vs Turn on with Telegram (linked: false). A well-formed address with no row (or a disabled link) is 200 with linked: false, never 404. Never returns chat ids or usernames.

Requires the agents scope. Not credit-metered. Call this from your backend holding the sg_ key — never from the browser.

Address case is preserved (Solana is case-sensitive). Chain must be a slug from GET /meta's chains[].

Returns the authenticated tenant's versioned public surface definitions: copy, required subject identity, user fields, actions, and capabilities. Definitions are projected from Signo's agent catalog; private prompts and engine plans are never returned.

Requires the agents scope and a partner configured on the tenant. Call from your backend with the server-only sg_ key. The response is browser-safe and may be passed to your UI. Not credit-metered. A tenant with no configured catalog returns 403 partner_not_configured.

The default integration call. Send the current wallet and a stable page subject; Signo assembles the public definition, Telegram link state, and any existing in-page agent for the same tenant + wallet + catalog agent + normalized subject.

Resolve never mints a one-time code or activation URL. Its response is safe to pass to browser components. display_context is presentation-only and never participates in identity, authorization, arming, or pricing. Call from your backend with the server-only sg_ key. Not credit-metered. Surface-specific failures use partner_not_configured, agent_not_found, or state_unavailable; malformed input uses invalid_request.

Call only after the user submits the surface. Signo revalidates the agent, schema version, subject, action, and field values, then stores a short-lived server-owned prefill and returns its activation URL.

Read outcome first. A wallet that already has a live Telegram link is armed in this call (outcome: "activated", with the saved agent in agent and no URL): show the confirmation. Otherwise (outcome: "requires_action") open activation_url exactly as returned. The /go?p=... token is opaque: do not parse, edit, cache, or reconstruct it. A later contract may change its encoding or remove query parameters entirely. Link-only activation uses { intent: "link", wallet } and is always requires_action. Repeat submits are harmless: an identical configuration is a no-op, a changed one updates the same agent, a paused one resumes (change). Call from your backend with the server-only sg_ key. Not credit-metered. Catalog/field/action mismatches return invalid_configuration; mint failures return activation_unavailable; a linked wallet whose agent could not be saved returns activation_failed; an unreadable Telegram link state returns state_unavailable; an unconfigured tenant returns partner_not_configured.

When POST /surfaces/resolve was called with include: [result] and the returned result has review.available: true, exchange that result id for a one-time review URL. The server verifies tenant, wallet, catalog agent, and normalized subject ownership before minting the exchange.

Open review_url exactly as returned. It is short-lived and opaque and does not expose the underlying handoff token. This user review/signing transition is available through HTTP and the TypeScript SDK; it is intentionally not an MCP tool. Call from your backend with the server-only sg_ key. Result state errors are result_not_found, result_not_prepared, and result_expired; transient exchange failures return review_unavailable.