> ## Documentation Index > Fetch the complete documentation index at: https://docs.zapyd.com/llms.txt > Use this file to discover all available pages before exploring further. # Initialize Widget > Returns a widget_link that opens the Zapyd widget, optionally prefilled for a buy or a sell. Add the Zapyd "Initialize Widget" call (`POST /widget/initialize`) to my backend. Returns a widget\_link that opens the Zapyd widget, optionally prefilled for a buy or a sell. * Sandbox: `POST https://sandbox.zapyd.com/widget/initialize` * Production: `POST https://api.zapyd.com/widget/initialize` JSON body (Buy flow): * `asset_code` (string, optional): Cryptocurrency asset code. Example: `USDT`. * `fiat_amount` (string, optional): Fiat amount the user will pay (buy flow). Example: `1000`. * `fiat_currency` (string, optional): Fiat currency code. Example: `INR`. * `flow_type` (string, optional): Must be `buy` for this request shape. * `network_code` (string, optional): Blockchain network code for the asset. Example: `tron`. * `payment_method` (string, optional): Fiat payment method (e.g. IMPS, UPI). Example: `IMPS`. * `wallet_address` (string, optional): User's wallet address to receive crypto. Example: `TXqH4MnDw46f3yyrRwau3JF92Y1ie3pAXf`. JSON body (Sell flow): * `asset_code` (string, optional): Cryptocurrency asset code. Example: `USDT`. * `asset_amount` (string, optional): Crypto amount the user will sell. Example: `10`. * `fiat_currency` (string, optional): Fiat currency code for settlement quote. Example: `INR`. * `flow_type` (string, optional): Must be `sell` for this request shape. * `network_code` (string, optional): Blockchain network code for the asset. Example: `tron`. Success: HTTP 200, `{status: true, message, data}`. `data`: `widget_link` (URL to load the widget (includes `token`, `app_id`, and `flow_type` query parameters)). Rules: * Call it from your server only, and send only `data.widget_link` to the browser. Embed it in an iframe with `allow="camera; microphone"` (KYC needs the camera), or open it in a new tab or webview. * Every body field is an optional prefill: send what your app already knows. `flow_type: buy` takes `fiat_amount`, `payment_method` and the user's `wallet_address`; `flow_type: sell` takes `asset_amount`. Both take `asset_code`, `network_code` and `fiat_currency`. * Your backend still registers the webhook URL and acts on final statuses (for example, never credit a payin that is `ON_HOLD`). Signing (this endpoint only; every other Zapyd endpoint signs differently): * Headers: `X-API-KEY`, `X-TIMESTAMP` (Unix seconds, within 300 s of server time) and `X-SIGNATURE`. * `X-SIGNATURE` = lowercase hex(HMAC-SHA256(key = API secret, message = rawBody + timestamp)): the body bytes exactly as sent (no key sorting), followed directly by the timestamp. No API key, no `|`, hex not Base64. * Test vector: secret `test-secret-do-not-use`, timestamp `1735689600`, body `{"flow_type":"buy","fiat_amount":"1000"}` gives `26241a01db912ebb26d7f7099958a11ebc50af14937df9d1797a9e89959e7c87`. Deliver: 1. A typed `initializeWidget` function in this codebase's language and HTTP client. Reuse an existing Zapyd client and signer, or write one small shared client. 2. Config from `ZAPYD_API_KEY`, `ZAPYD_API_SECRET` and `ZAPYD_BASE_URL`. The secret stays on the server, never in a browser or app. 3. Return `data`. When `status` is false, throw an error with the HTTP status, `err_code`, `message` and `errors`. Don't show raw errors to end users. 4. Retry only 429 and 5xx: exponential backoff from 1 s, capped at 30 s, at most 5 attempts. 5. Amounts as strings. Types for every field above. 6. Tests: the signer against the test vector, and this call against sandbox. Reference: `https://docs.zapyd.com/api-reference-exchange/endpoint/widget/initialize.md` ## OpenAPI ````yaml POST /widget/initialize openapi: 3.1.0 info: title: Zapyd API description: API for Zapyd - Customer, Payout, and Webhook services license: name: MIT version: 1.0.0 servers: - url: https://sandbox.zapyd.com/pos/api/v1 description: Payout API Base URL variables: base_url: default: https://sandbox.zapyd.com - url: https://sandbox.zapyd.com/cms/api/v1 description: Customer API Base URL variables: base_url: default: https://sandbox.zapyd.com security: - ApiKeyAuth: [] TimestampAuth: [] SignatureAuth: [] tags: - name: Customer description: Customer related operations x-displayName: Customer x-traitTag: true - name: Payout description: Payout related operations - name: Webhooks description: Webhook related operations - name: Widget description: Hosted buy/sell widget session initialization paths: /widget/initialize: post: tags: - Widget description: Initialize a widget session and receive a `widget_link` URL. requestBody: required: true content: application/json: schema: oneOf: - type: object title: Buy flow properties: asset_code: type: string description: Cryptocurrency asset code example: USDT fiat_amount: type: string description: Fiat amount the user will pay (buy flow) example: '1000' fiat_currency: type: string description: Fiat currency code example: INR flow_type: type: string enum: - buy description: Must be `buy` for this request shape network_code: type: string description: Blockchain network code for the asset example: tron payment_method: type: string description: Fiat payment method (e.g. IMPS, UPI) example: IMPS wallet_address: type: string description: User's wallet address to receive crypto example: TXqH4MnDw46f3yyrRwau3JF92Y1ie3pAXf - type: object title: Sell flow properties: asset_code: type: string description: Cryptocurrency asset code example: USDT asset_amount: type: string description: Crypto amount the user will sell example: '10' fiat_currency: type: string description: Fiat currency code for settlement quote example: INR flow_type: type: string enum: - sell description: Must be `sell` for this request shape network_code: type: string description: Blockchain network code for the asset example: tron examples: buy: summary: Buy flow value: asset_code: USDT fiat_amount: '1000' fiat_currency: INR flow_type: buy network_code: tron payment_method: IMPS wallet_address: TXqH4MnDw46f3yyrRwau3JF92Y1ie3pAXf sell: summary: Sell flow value: asset_code: USDT asset_amount: '10' fiat_currency: INR flow_type: sell network_code: tron responses: '200': description: >- Widget initialized successfully. The `widget_link` opens the widget; query parameters include `app_id` and `flow_type`. content: application/json: schema: type: object properties: status: type: boolean example: true message: type: string example: Success data: type: object properties: widget_link: type: string format: uri description: >- URL to load the widget (includes `token`, `app_id`, and `flow_type` query parameters) required: - widget_link required: - status - message - data examples: buy: summary: Buy flow response value: message: Success status: true data: widget_link: >- https://app.zapyd.com/login?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcmdfaWQiOiJmZjQ2YjNiMC04NTQ3LTRmNDgtODRhNS00MDdjMzhlMGM0ZTkiLCJhcHBfaWQiOiJ5b3VyX2FwcF9pZCIsImZsb3dfdHlwZSI6ImJ1eSIsImFzc2V0X2NvZGUiOiJVU0RUIiwiYXNzZXRfbmFtZSI6IlRldGhlciIsImFzc2V0X2xvZ28iOiJodHRwczovL2FwcC56YXB5ZC5jb20vYXNzZXRzL2NvaW5zL3VzZHQucG5nIiwiZmlhdF9jdXJyZW5jeSI6IklOUiIsIm5ldHdvcmtfY29kZSI6InRyb24iLCJuZXR3b3JrX25hbWUiOiJUcm9uIiwicGF5bWVudF9tZXRob2QiOiJpbXBzIiwiZmlhdF9hbW91bnQiOiIxMDAwIiwid2FsbGV0X2FkZHJlc3MiOiJUWHFINE1uRHc0NmYzeXlyUndhdTNKRjkyWTFpZTNwQVhmIiwidHlwZSI6IndpZGdldCIsImV4cCI6MTc3NTY3ODkzMSwiaWF0IjoxNzc1Njc3MTMxfQ.3tS9DHVv9rBe4dlRxCivp46L1q1bppx8ZSvO16p38aE&app_id=your_app_id&flow_type=buy sell: summary: Sell flow response value: message: Success status: true data: widget_link: >- https://app.zapyd.com/login?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcmdfaWQiOiJmZjQ2YjNiMC04NTQ3LTRmNDgtODRhNS00MDdjMzhlMGM0ZTkiLCJhcHBfaWQiOiJ5b3VyX2FwcF9pZCIsImZsb3dfdHlwZSI6InNlbGwiLCJhc3NldF9jb2RlIjoiVVNEVCIsImFzc2V0X25hbWUiOiJUZXRoZXIiLCJhc3NldF9sb2dvIjoiaHR0cHM6Ly9hcHAuemFweWQuY29tL2Fzc2V0cy9jb2lucy91c2R0LnBuZyIsImZpYXRfY3VycmVuY3kiOiJJTlIiLCJuZXR3b3JrX2NvZGUiOiJ0cm9uIiwibmV0d29ya19uYW1lIjoiVHJvbiIsInBheW1lbnRfbWV0aG9kIjoiaW1wcyIsImFzc2V0X2Ftb3VudCI6IjEyIiwidHlwZSI6IndpZGdldCIsImV4cCI6MTc3NTY3ODkwMywiaWF0IjoxNzc1Njc3MTAzfQ.369yVMOLsjFCcTDENG9cKY3ZEsSfYhU5J_LZze441-c&app_id=your_app_id&flow_type=sell '400': description: Bad Request content: application/json: schema: type: object properties: status: type: boolean example: false message: type: string example: Bad Request data: type: 'null' err_code: type: string example: REQ_FIELD_MISSING errors: type: object additionalProperties: type: array items: type: string example: asset_code: - This field is required. wallet_address: - Invalid wallet address format. '500': description: Internal Server Error content: application/json: schema: type: object properties: status: type: boolean example: false message: type: string example: Internal Server Error data: type: 'null' err_code: type: string example: SYS_INTERNAL_ERROR errors: type: string example: Unexpected error occurred. Please try again later. servers: - url: https://sandbox.zapyd.com description: Widget API Base URL components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: API Key for authentication TimestampAuth: type: apiKey in: header name: X-TIMESTAMP description: Current timestamp in seconds since epoch SignatureAuth: type: apiKey in: header name: X-SIGNATURE description: HMAC SHA256 signature of the request encoded in Base64 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.