Tracking intents

The TypeScript SDK is WIP. Today, poll GET /intent-details/:intentId directly. Webhooks are planned but not yet shipped.

After submission, an intent moves through a small set of states. Today, you track via polling; the SDK’s subscribe is a thin polling helper, and webhook delivery is on the roadmap.

States

These come from the relayer’s IntentDetails.status field. Non-terminal (intent is still in flight):

State	Meaning	What’s happening behind the scenes
`pending`	Intent created on-chain, awaiting solver bids	Intent is in a batched plaintext broadcast to solvers; the auction is running
`solving`	Solver won the auction, fulfilling on destination chain	Recipient bundle re-encrypted to the winning solver’s key; solver is delivering to stealth address(es)
`settled`	Destination delivery confirmed, source settlement in flight	Attestation from the secure enclave is being verified on-chain to release the solver’s reward

Terminal (intent is done, no further state changes):

State	Meaning	Funds
`completed`	Source settled. `settleTxHash` populated.	Delivered to recipient on destination
`failed`	Solver took the intent but failed to deliver before the protocol’s execution window	Refunded to sender via the escape path on the source bridge
`expired`	Auction window closed with no bidder	Refunded to sender
`cancelled`	Sender cancelled before a winner was picked	Refunded to sender

None of the terminal-failure states (failed, expired, cancelled) lose funds. The bridge’s escape path refunds the sender in all three cases, which is also why you can treat “no solver took it” as an expected failure mode rather than an emergency. State transitions are forward-only. Once terminal, the intent is final.

Poll

Direct API:

const res = await fetch(`${RELAYER_URL}/intent-details/${intentId}`);
const { intent } = await res.json();
console.log(intent.status, intent.solveTxHash);

SDK (when published):

const intent = await tachyon.intent.status(intentId);

For interactive UIs, poll every 2–5 seconds while the intent is live (pending or solving).

const unsubscribe = tachyon.intent.subscribe(intentId, (intent) => {
  if (intent.status === "completed") {
    console.log("done:", intent.settleTxHash);
    unsubscribe();
  }
}, { intervalMs: 3000 });

Under the hood this is a polling loop against GET /intent-details/:intentId. When webhooks ship, this method will switch to a long-lived connection automatically.

Webhooks (planned)

WIP. The planned shape is shown for forward compatibility, none of these calls work today.

await tachyon.webhooks.register({
  url: "https://your-app.example.com/tachyon/webhook",
  events: ["intent.solving", "intent.settled", "intent.completed"],
  secret: process.env.WEBHOOK_SECRET,
});

Each callback will be signed with HMAC using secret:

import { verifyTachyonSignature } from "@tachyon/sdk/webhooks";

app.post("/tachyon/webhook", express.raw({ type: "*/*" }), (req, res) => {
  const ok = verifyTachyonSignature(req.body, req.headers["x-tachyon-signature"], process.env.WEBHOOK_SECRET);
  if (!ok) return res.status(401).end();

  const event = JSON.parse(req.body.toString());
  switch (event.type) {
    case "intent.completed":
      markCompleted(event.intentId, event.settleTxHash);
      break;
  }
  res.status(200).end();
});

TODO: confirm webhook event names, payload shape, signature header, and retry policy before publish.

Choosing a method (today)

Method	When to use
Poll `GET /intent-details/:intentId`	Backend job, batch worker, or any server flow
SDK `subscribe` (polling helper)	Interactive UI, same as poll, just less code
Webhooks	Will be the recommended server-to-server option once shipped

Idempotency (when webhooks ship)

Webhook deliveries can repeat on retries. Use the eventId in each callback to deduplicate before applying side effects.

Failure semantics

No solver bids before auction closes → intent transitions to expired, sender is refunded via the bridge’s escape path.
Solver bid but failed to deliver in the protocol’s execution window → intent transitions to failed, sender is refunded.
Sender cancels before a winner is picked → intent transitions to cancelled, sender is refunded.

Each of these is a handleable state, not an error. Surface the reason to the user and let them retry with wider parameters (higher reward, longer auction, looser minAmountOut, different chain pair).

Recipient flow: claiming funds

How recipients sweep settled stealth-address balances.

Get Started

Guides

SDK (WIP)

Reference

Tracking intents

States

Poll

Webhooks (planned)

Choosing a method (today)

Idempotency (when webhooks ship)

Failure semantics

Recipient flow: claiming funds

​States

​Poll

​Subscribe (polling helper)

​Webhooks (planned)

​Choosing a method (today)

​Idempotency (when webhooks ship)

​Failure semantics

Recipient flow: claiming funds

States

Poll

Subscribe (polling helper)

Webhooks (planned)

Choosing a method (today)

Idempotency (when webhooks ship)

Failure semantics