Webull Auth

Webull authentication

Read references/authentication.md, the matching references/endpoints.json entry, and its schema_ref in references/openapi.json before constructing any request. Use the official Webull Open API reference for current details.

First-use onboarding

Before the first API request, check whether WEBULL_APP_KEY and WEBULL_APP_SECRET are available through the configured environment or secret manager. If WEBULL_APP_KEY is missing, stop and ask the user to configure the Webull API Key securely before continuing. Never ask the user to paste the App Secret or access token into chat.

Supported endpoints

• POST /openapi/auth/token/create — official reference index. Treat token creation as a sensitive write-like operation: require explicit TOKEN_WRITE confirmation immediately before calling it.
• POST /openapi/auth/token/check — official reference index. The catalog marks this as a credential-status read; still handle token material as secret.

Workflow

1. Load only the required environment variables from a local secret manager or shell environment. Never ask the user to paste a secret into chat, never print secrets, and redact tokens, signatures, authorization headers, and response fields containing credential material.
2. Read the catalog entry to determine the HTTP method, required headers, query parameters, and JSON body. Do not invent fields or copy a neighboring endpoint’s schema.
3. For token creation, summarize the intended operation and wait for exact TOKEN_WRITE confirmation; then invoke the shared runtime, for example:

``bash python scripts/webull_api.py request --method POST --path /openapi/auth/token/create --body-file ./token-create.json ``

1. For status checks, invoke the catalog-shaped request only after confirming the token is available through the configured secret source. No write gate is required because this endpoint is cataloged as risk: read:

``bash python scripts/webull_api.py request --method POST --path /openapi/auth/token/check --body-file ./token-check.json ``

1. Explain the documented lifecycle: creation normally returns PENDING; the user completes mobile-app SMS/2FA verification, then check status until NORMAL. INVALID or EXPIRED requires a new token. Never claim that a token is active without the check response.
2. Use UAT first. Keep production host selection explicit and separate from credential setup. Do not persist tokens in source control, logs, examples, or generated reports.

Safe handling

Do not expose a complete request or response when it contains a token or signed header; show a redacted summary instead. Do not bypass signature prerequisites, substitute bearer-token guesses, or infer missing app credentials. Authentication success does not authorize an order or any other write.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nutdnuy
• Source: nutdnuy/webull-openapi-AI-Plugin
• License: MIT

Install and usage instructions live in the source repository linked above.