Widget Integration

The widget handles the full payment flow in the browser using sy_pub_* keys. No backend needed for session creation, quoting, or committing.

Exact API Flow

Frontend (browser, sy_pub_*):
1. Create session
   POST /v2/sessions { amount, destination }

2. Get buyer's balances
   GET /v2/network/portfolio?address=BUYER_WALLET
   → Show chain picker: "Base: 500 USDC, Polygon: 200 USDC"

3. Buyer picks chain → preview
   POST /v2/sessions/:id/quote { sourceChain: "polygon" }
   → Show fees, estimated time, route provider
   → No order created. User can switch chains freely.
   → alternatives: all providers ranked by output amount

4. Buyer confirms → commit from browser
   POST /v2/sessions/:id/quote
     { sourceChain: "polygon", commit: true, executionMode: "boosted" }
   → Returns deposit address
   → Public key can commit on sessions it created

5. Execute payment (send USDC to deposit address)

6. Poll for settlement
   GET /v2/sessions/:id (no auth)
   → Repeat until status === "settled"
   → Show success screen

Backend (Optional)

A backend is only needed for webhooks and tx submission:
1. Submit tx (if not handled by widget)
   POST /v2/sessions/:id/submit-tx
     Authorization: sy_secret_*
     { txHash: "0x...", chain: "polygon" }

2. Receive webhook
   POST yourserver.com/webhooks/stableyard
   → Verify HMAC-SHA256 signature
   → event: "payment.settled" → mark order as paid
The widget can handle the entire payment flow with just sy_pub_*. A backend is only needed for webhooks and tx submission.

What Runs Where

ActionAuthRuns in
Create sessionsy_pub_*Browser
Preview quote (commit=false)sy_pub_*Browser
Commit quote (commit=true)sy_pub_*Browser
Poll statusNoneBrowser
Submit tx hashsy_secret_*Server
Receive webhookssy_secret_*Server
Refunds, cancellationssy_secret_*Server