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
| Action | Auth | Runs in |
|---|
| Create session | sy_pub_* | Browser |
| Preview quote (commit=false) | sy_pub_* | Browser |
| Commit quote (commit=true) | sy_pub_* | Browser |
| Poll status | None | Browser |
| Submit tx hash | sy_secret_* | Server |
| Receive webhooks | sy_secret_* | Server |
| Refunds, cancellations | sy_secret_* | Server |