# Float

> Float swaps Canton Coin (CC) to and from ~2,000 assets at the best rate across its liquidity partners. Partners integrate it with a server-side REST API (/v1) and earn 0.2% of the CC side of every order they route.

Key facts for an integration:

- Base URL: https://api.myfloat.cc/v1.
- Auth: optional "Authorization: Bearer fl_live_…" API key from https://www.myfloat.cc/partners. Server-side only: keep it in an environment variable (FLOAT_API_KEY); never in client code. Browser calls from a partner's own domain are not supported (CORS) — use a server-side proxy.
- Flow: GET /v1/assets?all=1 → POST /v1/quote (rateType "float") → POST /v1/order (with Idempotency-Key) → show depositAddress, exact amountIn, depositDeadline → follow the order (order.state_changed webhooks, and/or poll GET /v1/order/{claimToken} every 10–30 s) until state is completed, refunded, failed or expired.
- Withdraw CC (CC → X): the user sends exactly amountIn CC to the order's own Float deposit address. No memo, ever.
- Get CC (X → CC): the user sends exactly amountIn to the partner's depositAddress, with depositExtraId as memo/tag when it is not null.
- Errors are { "error": "<sentence>", "code": "<stable code>" }; branch on code.
- Amounts are decimal strings; never use floating-point arithmetic on them.
- Webhooks: register an https endpoint with POST /v1/webhooks (API key; the signing secret is returned once). Events: order.state_changed ({id, type, created_at, data: {previous_state, order}} — order is the public order object), payout.updated, webhook.test. Verify Float-Signature: t=<unix>,v1=<hex> = HMAC-SHA256(secret, "<t>.<raw body>"); either v1 during a 24 h rotation overlap; 5-minute tolerance. Retries with backoff for 24 h; auto-pause after 10 failures over 12 h; up to 5 endpoints. De-duplicate on the event id.
- Destination tag / memo for Withdraw CC payouts: send destinationExtraId on /quote and /order (out only) when the payout address needs one (an exchange's XRP, XLM, TON, ATOM, EOS, HBAR… address). /v1/assets rows and quotes carry destinationExtraIdNeeded and destinationExtraIdName — that flag is authoritative; any list of such assets in the docs is only a snapshot. When it is true, show "Sending to an exchange? Add your destination tag/memo, or the funds may be lost."
- Identify an asset by symbol + network (the pair), not by a ticker suffix such as "-SOL". network is optional on /quote and /order: omit the key (never send null) for the asset's default network.
- Render the API's error sentence as text, never as HTML (no innerHTML). alternatives[].note is display text ("0.37% less than The Change"); do not parse it. venueBaseFeeBps may be null.
- Embed widget (no API key): iframe https://www.myfloat.cc/bridge?embed=1&ref=<referral code>. It posts { source: "float-widget", type } messages to the parent — height, direction, order_created (direction only — the widget never posts the order's claim token), order_state — with target origin "*", so accept only e.origin === "https://www.myfloat.cc" and e.data.source === "float-widget".
- The document at the API host's root (/openapi.json) is a different product (Slay's wallet API). Float's spec is /v1/openapi.json.

## Docs

- [API reference (Markdown)](https://www.myfloat.cc/docs/api.md): every endpoint, request and response field, states, networks and pinned chains, idempotency, rate limits, webhooks and signature verification, refunds, errors, earnings, embed widget, code examples in curl, Node and Python.
- [OpenAPI 3.1 spec](https://www.myfloat.cc/openapi.json): the same API, machine-readable, with examples. Also served at https://api.myfloat.cc/v1/openapi.json.
- [API reference (HTML)](https://www.myfloat.cc/docs/api)

## Integrate Float with an AI

Give your AI assistant the URL https://www.myfloat.cc/docs/ai. It should read https://www.myfloat.cc/docs/api.md and https://www.myfloat.cc/openapi.json, then ask you five questions, one at a time: (1) integration type — (A) API, your own swap screen with your API key, or (B) Widget, Float's swap screen embedded with your referral code; (2) branding (website or brand kit); (3) your API key for (A), or your referral code for (B); (4) ideas (optional); (5) placement. For (A) it builds a server-side proxy, the swap widget, a webhook receiver that verifies signatures (registered with POST /v1/webhooks), tests and a README. For (B) it builds the iframe embed with a height listener, in your branding — no API key, no backend.

- [Integrate Float with your AI (Markdown)](https://www.myfloat.cc/docs/ai.md): the copy-paste prompt, the reference widget spec (states, copy, layout, accessibility) and a complete Next.js starter.
- [Starter download](https://www.myfloat.cc/downloads/float-widget-starter.zip): Next.js App Router — key-holding proxy (app/api/float/[...path]/route.ts), FloatWidget.tsx, TokenPicker.tsx, a webhook receiver (app/api/float-webhook/route.ts) and scripts/register-webhook.mjs.

Copy-paste prompt (short form):

    Integrate Float into my app. Read https://www.myfloat.cc/docs/ai.md, https://www.myfloat.cc/docs/api.md and
    https://www.myfloat.cc/openapi.json first. Ask me, one at a time: (1) API (my own swap screen, with my API
    key) or Widget (Float's swap screen embedded, with my referral code); (2) my website or brand
    kit; (3) for API, my Float API key (store it only as the server-side env var FLOAT_API_KEY),
    for Widget, my referral code (public; never ask for a key); (4) any ideas (optional);
    (5) where it should live.
    API: build a server-side proxy for the five /v1 calls, the swap widget following the
    reference widget spec in my branding, a webhook receiver that verifies Float-Signature
    (register it with POST /v1/webhooks; secret in FLOAT_WEBHOOK_SECRET), tests or a checklist,
    and a README. Use rateType "float". Never create a real order while testing.
    Widget: embed the iframe https://www.myfloat.cc/bridge?embed=1&ref=<my referral code> (width 100%, no
    border, a title) with a message listener that sets its height, accepting messages only when
    e.origin === "https://www.myfloat.cc" and e.data.source === "float-widget". No API key, no proxy, no
    webhook; add a plain https://www.myfloat.cc/bridge?ref=<code> link as a fallback.

## Token picker

- GET /v1/assets?all=1 returns every asset with symbol, name, network, networkName, icon and networkIcon (absolute URLs to Float-hosted 64×64 images, or null: draw a lettered tile).
- [Token image map](https://www.myfloat.cc/data/token-icons.json): { size: 64, icons: { "<TICKER>": "/icons/tokens/<file>.webp" } }.
- [Chain logo map](https://www.myfloat.cc/data/chain-logos.json): { size: 64, chains: { "<id>": { name, logo, networks } }, networks: { "<CODE>": "<id>" } }.

## Optional

- [Docs overview](https://www.myfloat.cc/docs)
- [Partner dashboard](https://www.myfloat.cc/partners): API keys, referral links, earnings, payouts.
- [Support centre](https://www.myfloat.cc/support): order diagnosis by order link, help articles, support requests. Email: support@myfloat.cc