API Keys

API keys authenticate private account and trading requests. Each key has a public key and a secret key, an account scope, and a set of permissions.

Create an API key

Sign in at qfex.com and select your profile in the bottom right corner.
Navigate to Developer Settings via the carousel.
Click Generate public and secret API Keys.
Ensure you have 2FA enabled.
Provide a descriptive name, choose the account access and permissions the key needs, and confirm.
Copy the generated key and store it securely—it will only be shown once.

Account access and permissions

Each API key is limited by both its account access and its permissions. A request must satisfy both settings. For account access, choose either:

A specific account: The key can be used only with the selected primary account or subaccount.
All accounts: The key can be used with any account you own. Use this only when the integration genuinely needs access across accounts.

Permissions control what the key can do:

Permission	Allows
Execute orders	Place, modify, and cancel orders, and perform related trading actions.
View orders	Read orders, fills, and trading history.
View positions	Read open position information.
View balance (`view_balance`)	Read balances, equity, fees, deposit addresses with `GET /address`, and registered withdrawal addresses with `GET /withdrawal-addresses`.
Deposit and withdraw (`deposit_withdraw`)	Use supported funding and withdrawal actions, rotate deposit addresses, and manage bank accounts. Crypto withdrawals require a registered destination. Available only to keys with All accounts access.

Create keys with only the permissions required for their intended use. For example, reporting software may need view permissions but should not need order execution or withdrawal access.

Use an API key with a third party

If you authorize a trusted third-party application to access QFEX with an API key:

Create a dedicated key for that application. Do not reuse your personal integration key.
Limit it to the required account and enable only the permissions the application needs.
Provide the public and secret key through a secure channel. The application never needs your QFEX password or MFA codes.
The application must keep the secret key on a secure server and use it to sign authenticated requests. It must never expose the secret in browser code, mobile applications, logs, URLs, or source control.
Revoke the key from Developer Settings when the integration is no longer needed or if either credential may have been exposed.

The secret key is displayed only once. QFEX cannot display it again after creation; create a replacement key if it is lost. For direct integrations, see WebSocket authentication for the trading signing flow or Programmatic deposits and withdrawals for funding REST requests. A third-party application can also use QFEX OAuth or wallet-signed builder registration to connect a user account.

Treat the secret key like a password. Anyone who has both key values can act within the account access and permissions you selected.

Builder-issued API keys

Builder wallet registration lets an enabled builder create a user’s trading key after the user signs a wallet message. The builder authenticates the registration request with its own API key and register_user permission. The returned user key is restricted to the main account and grants trading, account reads, deposit-address reads, and crypto withdrawals to registered destinations. Its view_balance permission authorizes GET /address and GET /withdrawal-addresses. Registered-destination crypto withdrawals with POST /withdraw are enabled through builder key issuance and replacement; this access is not selectable in Developer Settings. It has deposit_withdraw disabled, so it cannot rotate deposit addresses, manage bank accounts, or withdraw USD. See programmatic funding for the requests. The key is labelled builder- followed by the builder’s username. Creating another key for the same user and builder label replaces the previous key. Keys with labels starting with builder- or managed are excluded from the normal API-key listing.

Create an API key programmatically

Standard programmatic key creation uses a QFEX user session, not an existing API key. First authenticate with a wallet or another supported sign-in method, then complete MFA to obtain a recently elevated access token. Send the elevated token to the key-generation endpoint. Supply every permission explicitly so the key cannot gain permissions through a default-value change:

const QFEX_AUTH_URL = "https://verify.qfex.com";
const QFEX_AUTH_CLIENT_KEY = "YOUR_QFEX_AUTH_CLIENT_KEY";

export async function createQfexApiKey({
  accessToken,
  name,
  accountId = "*",
  permissions = {},
}) {
  const response = await fetch(
    `${QFEX_AUTH_URL}/rest/v1/rpc/generate_api_key_v3`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        apikey: QFEX_AUTH_CLIENT_KEY,
        Authorization: `Bearer ${accessToken}`,
      },
      body: JSON.stringify({
        p_name: name,
        p_account_id: accountId,
        p_execute_orders: permissions.executeOrders === true,
        p_view_orders: permissions.viewOrders === true,
        p_view_positions: permissions.viewPositions === true,
        p_view_balance: permissions.viewBalance === true,
        p_deposit_withdraw:
          accountId === "*" && permissions.depositWithdraw === true,
      }),
    },
  );

  const result = await response.json();
  if (!response.ok) {
    throw new Error(result.message ?? "API key creation failed");
  }

  return {
    publicKey: result.public_key,
    secretKey: result.secret_key,
  };
}

Create a key after the user has selected its scope and permissions:

const apiKey = await createQfexApiKey({
  accessToken: elevatedSession.access_token,
  name: "order-service",
  accountId: "11111111-1111-4111-8111-111111111111",
  permissions: {
    executeOrders: true,
    viewOrders: true,
    viewPositions: true,
    viewBalance: true,
    depositWithdraw: false,
  },
});

await saveToEncryptedCredentialStore(apiKey);

The accountId value must be one of:

* for all primary accounts and subaccounts owned by the user
The user’s primary account ID
A subaccount ID owned by the user

The deposit and withdrawal permission is available only when accountId is *. QFEX forces that permission to false for a key restricted to one account.

Never return the generated secret to logs, analytics, browser storage, or an untrusted caller. The response is the only time QFEX returns the plaintext secret.

Elevate a session with TOTP

API-key creation requires recent MFA verification. If the user has a verified authenticator-app factor, challenge and verify that factor before creating the key:

async function qfexAuthRequest(path, { accessToken, body }) {
  const response = await fetch(`${QFEX_AUTH_URL}${path}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      apikey: QFEX_AUTH_CLIENT_KEY,
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify(body),
  });

  const result = await response.json();
  if (!response.ok) {
    throw new Error(result.msg ?? result.message ?? "MFA request failed");
  }
  return result;
}

export async function elevateQfexSessionWithTotp({
  accessToken,
  factorId,
  code,
}) {
  const challenge = await qfexAuthRequest(
    `/auth/v1/factors/${encodeURIComponent(factorId)}/challenge`,
    { accessToken, body: { factorId } },
  );

  return qfexAuthRequest(
    `/auth/v1/factors/${encodeURIComponent(factorId)}/verify`,
    {
      accessToken,
      body: {
        challenge_id: challenge.id,
        code,
      },
    },
  );
}

Use the access_token returned by the verification response for key creation. Obtain factorId from the signed-in user’s verified factors. The user must provide the current authenticator code; do not store or attempt to generate it for them.

HTTP request

The raw key-generation request is:

POST /rest/v1/rpc/generate_api_key_v3
Host: verify.qfex.com
Content-Type: application/json
apikey: <QFEX_AUTH_CLIENT_KEY>
Authorization: Bearer <MFA_ELEVATED_ACCESS_TOKEN>

{
  "p_name": "order-service",
  "p_account_id": "*",
  "p_execute_orders": true,
  "p_view_orders": true,
  "p_view_positions": true,
  "p_view_balance": true,
  "p_deposit_withdraw": false
}

A successful response contains public_key and secret_key. Persist the pair before discarding the response; the secret cannot be retrieved later.

Common errors

Error	Resolution
`no_recent_mfa_auth`	Complete a new MFA challenge and retry with the elevated access token.
`api_key_name_required`	Provide a non-empty `p_name`.
Invalid account scope	Use `*`, the user’s primary account ID, or an owned subaccount ID.
Duplicate key name	Choose a different name for this user.
`401`	Sign in again or refresh the user session.

API Documentation

Builder Codes

REST API

Funding API

WebSocket

Create an API key

Account access and permissions

Use an API key with a third party

Builder-issued API keys

Create an API key programmatically

Elevate a session with TOTP

HTTP request

Common errors

​Create an API key

​Account access and permissions

​Use an API key with a third party

​Builder-issued API keys

​Create an API key programmatically

​Elevate a session with TOTP

​HTTP request

​Common errors

Create an API key

Account access and permissions

Use an API key with a third party

Builder-issued API keys

Create an API key programmatically

Elevate a session with TOTP

HTTP request

Common errors