# Create Instant Exchange

Creates an instant currency exchange request at the Virtual account level. Requires base currency, base amount, target currency, and target amount as inputs. This feature does not rely on the latest FX rate provided by Webull.

# OpenAPI definition

```json
{
  "info": {
    "title": "Webull Open API Reference",
    "description": "application.yml\\ncom\\ni18n\\nMETA-INF\\nstatic\\n\\r\\n",
    "contact": {
      "name": "",
      "url": "",
      "email": ""
    },
    "version": "2.0",
    "x-logo": {
      "url": "static/png/logo.png"
    }
  },
  "servers": [
    {
      "url": "https://broker-api.sandbox.webull.hk"
    }
  ],
  "path": "/broker/funding/instant-exchanges/create",
  "method": "post",
  "tags": [
    "FX"
  ],
  "description": "Creates an instant currency exchange request at the Virtual account level. Requires base currency, base amount, target currency, and target amount as inputs. This feature does not rely on the latest FX rate provided by Webull.",
  "operationId": "brokerFundingCreateInstantFX",
  "parameters": [
    {
      "name": "x-app-key",
      "in": "header",
      "description": "A unique identifier issued to a developer for accessing an application's API.",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "x-app-secret",
      "in": "header",
      "description": "A unique key issued to developers to access the application's API.",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "x-timestamp",
      "in": "header",
      "description": "Timestamp of the request, follows ISO8601 format: YYYY-MM-DDThh:mm:ssZ, e.g. 2023-07-16T19:23:51Z, only supports UTC time zone.",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "x-signature-version",
      "in": "header",
      "description": "Signature algorithm version, default is 1.0.",
      "required": true,
      "schema": {
        "type": "string",
        "default": "1.0"
      },
      "examples": {
        "1.0": {
          "value": "1.0"
        }
      }
    },
    {
      "name": "x-signature-algorithm",
      "in": "header",
      "description": "Signature algorithm, default is HMAC-SHA1.",
      "required": true,
      "schema": {
        "type": "string",
        "default": "HMAC-SHA1"
      },
      "examples": {
        "HMAC-SHA1": {
          "value": "HMAC-SHA1"
        }
      }
    },
    {
      "name": "x-signature-nonce",
      "in": "header",
      "description": "Signature unique random number.",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "x-version",
      "in": "header",
      "description": "API interface version. Supported values: `v2`, `v3`.",
      "required": true,
      "schema": {
        "type": "string",
        "default": "v3"
      },
      "examples": {
        "v3": {
          "value": "v3"
        }
      }
    },
    {
      "name": "x-signature",
      "in": "header",
      "description": "A signature is a unique digital fingerprint, typically encrypted, that verifies the authenticity and integrity of a message or transaction, ensuring it has not been tampered with during transmission.",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "required": [
            "account_id",
            "client_request_id",
            "from_amount",
            "from_currency",
            "to_amount",
            "to_currency"
          ],
          "type": "object",
          "properties": {
            "account_id": {
              "type": "string",
              "description": "Account identifier, Exchange on which account id.",
              "example": "93IUJ28O9VO2KBGHDHR4H9"
            },
            "client_request_id": {
              "type": "string",
              "description": "Client Request ID, unique for each request. <br/> Maximum length is 32 characters. <br/> Allowed characters: letters (A–Z, a–z), digits (0–9), hyphen (-), underscore (_).",
              "example": "89JGKD4LKIVI5UU6L3KHNU10IA"
            },
            "from_amount": {
              "type": "string",
              "description": "Base amount for exchange.",
              "example": "100"
            },
            "to_amount": {
              "type": "string",
              "description": "Amount after exchange.",
              "example": "700"
            },
            "from_currency": {
              "type": "string",
              "description": "Currency",
              "example": "USD",
              "enum": [
                "CNH",
                "HKD",
                "USD"
              ]
            },
            "to_currency": {
              "type": "string",
              "description": "Currency",
              "example": "HKD",
              "enum": [
                "CNH",
                "HKD",
                "USD"
              ]
            }
          },
          "title": "BrokerCreateInstantExchangeParam"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "OK",
      "content": {
        "application/json": {
          "schema": {
            "required": [
              "account_id",
              "client_request_id",
              "from_amount",
              "from_currency",
              "instant_exchange_id",
              "status",
              "to_amount",
              "to_currency"
            ],
            "type": "object",
            "properties": {
              "account_id": {
                "type": "string",
                "description": "Account identifier, Exchange on which account id.",
                "example": "93IUJ28O9VO2KBGHDHR4H9"
              },
              "client_request_id": {
                "type": "string",
                "description": "Client Request ID, unique for each request. ",
                "example": "LJIS16BACHQG9LPP44L9IQHGAB"
              },
              "instant_exchange_id": {
                "type": "string",
                "description": "Request id generated by the system.",
                "example": "89JGKD4LKIVI5UU6L3KHNU10IA"
              },
              "from_amount": {
                "type": "string",
                "description": "Base amount for exchange.",
                "example": "100"
              },
              "to_amount": {
                "type": "string",
                "description": "Amount after exchange.",
                "example": "700"
              },
              "from_currency": {
                "type": "string",
                "description": "Currency",
                "example": "USD",
                "enum": [
                  "CNH",
                  "HKD",
                  "USD"
                ]
              },
              "to_currency": {
                "type": "string",
                "description": "Currency",
                "example": "HKD",
                "enum": [
                  "CNH",
                  "HKD",
                  "USD"
                ]
              },
              "status": {
                "type": "string",
                "description": "Request status",
                "example": "SUBMITTED",
                "enum": [
                  "SUBMITTED",
                  "CANCELED",
                  "REJECTED",
                  "FAILED",
                  "COMPLETED"
                ]
              },
              "reason": {
                "type": "string",
                "description": "Reason. If the terminal state is not “COMPLETED”, return the reason.",
                "example": "Failed."
              }
            },
            "title": "BrokerInstantExchangeResult"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized: Authentication required",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error_code": {
                "type": "string",
                "description": "Internal logic error code",
                "example": "UNAUTHORIZED"
              },
              "message": {
                "type": "string",
                "description": "Error message",
                "example": "Insufficient permission"
              }
            }
          }
        }
      }
    },
    "417": {
      "description": "A business logic error triggered when the request cannot be processed due to domain-specific constraints.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error_code": {
                "type": "string",
                "description": "Internal logic error code",
                "example": "INVALID_PARAMETER"
              },
              "message": {
                "type": "string",
                "description": "Error message",
                "example": "Parameter error, phone"
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "Internal Server Error.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error_code": {
                "type": "string",
                "description": "Internal logic error code",
                "example": "SYSTEM_ERROR"
              },
              "message": {
                "type": "string",
                "description": "Error message",
                "example": "Internal Server Error"
              }
            }
          }
        }
      }
    }
  },
  "jsonRequestBodyExample": {
    "account_id": "93IUJ28O9VO2KBGHDHR4H9",
    "client_request_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
    "from_amount": "100",
    "to_amount": "700",
    "from_currency": "USD",
    "to_currency": "HKD"
  },
  "postman": {
    "name": "Create Instant Exchange",
    "description": {
      "content": "Creates an instant currency exchange request at the Virtual account level. Requires base currency, base amount, target currency, and target amount as inputs. This feature does not rely on the latest FX rate provided by Webull.",
      "type": "text/plain"
    },
    "url": {
      "path": [
        "broker",
        "funding",
        "instant-exchanges",
        "create"
      ],
      "host": [
        "{{baseUrl}}"
      ],
      "query": [],
      "variable": []
    },
    "header": [
      {
        "disabled": false,
        "description": {
          "content": "(Required) A unique identifier issued to a developer for accessing an application's API.",
          "type": "text/plain"
        },
        "key": "x-app-key",
        "value": ""
      },
      {
        "disabled": false,
        "description": {
          "content": "(Required) A unique key issued to developers to access the application's API.",
          "type": "text/plain"
        },
        "key": "x-app-secret",
        "value": ""
      },
      {
        "disabled": false,
        "description": {
          "content": "(Required) Timestamp of the request, follows ISO8601 format: YYYY-MM-DDThh:mm:ssZ, e.g. 2023-07-16T19:23:51Z, only supports UTC time zone.",
          "type": "text/plain"
        },
        "key": "x-timestamp",
        "value": ""
      },
      {
        "disabled": false,
        "description": {
          "content": "(Required) Signature algorithm version, default is 1.0.",
          "type": "text/plain"
        },
        "key": "x-signature-version",
        "value": ""
      },
      {
        "disabled": false,
        "description": {
          "content": "(Required) Signature algorithm, default is HMAC-SHA1.",
          "type": "text/plain"
        },
        "key": "x-signature-algorithm",
        "value": ""
      },
      {
        "disabled": false,
        "description": {
          "content": "(Required) Signature unique random number.",
          "type": "text/plain"
        },
        "key": "x-signature-nonce",
        "value": ""
      },
      {
        "disabled": false,
        "description": {
          "content": "(Required) API interface version. Supported values: `v2`, `v3`.",
          "type": "text/plain"
        },
        "key": "x-version",
        "value": ""
      },
      {
        "disabled": false,
        "description": {
          "content": "(Required) A signature is a unique digital fingerprint, typically encrypted, that verifies the authenticity and integrity of a message or transaction, ensuring it has not been tampered with during transmission.",
          "type": "text/plain"
        },
        "key": "x-signature",
        "value": ""
      },
      {
        "key": "Content-Type",
        "value": "application/json"
      },
      {
        "key": "Accept",
        "value": "application/json"
      }
    ],
    "method": "POST",
    "body": {
      "mode": "raw",
      "raw": "",
      "options": {
        "raw": {
          "language": "json"
        }
      }
    }
  }
}
```