> For the complete documentation index, see [llms.txt](https://www.pionex.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.pionex.com/docs/api-docs/bot-api/signal.md).
# Signal
Custom signal listener and user-defined signal management (private)
## Push custom trading signal
> Push a custom trading signal to drive smart copy orders. Weight: 1.\
> \
> \*\*Requires \`Enable reading\` permission.\*\*
```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Signal","description":"Custom signal listener and user-defined signal management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"SignalListenerRequest":{"type":"object","required":["signalType","signalParam","base","quote","time","price","data"],"properties":{"signalType":{"type":"string","description":"Signal type identifier (ASCII, max 1000 chars)"},"signalParam":{"type":"string","description":"Signal parameters (ASCII, max 5000 chars)"},"base":{"type":"string","description":"Base currency (e.g. BTC)"},"quote":{"type":"string","description":"Quote currency (e.g. USDT)"},"time":{"type":"string","format":"date-time","description":"Signal trigger time (RFC3339)"},"price":{"type":"string","description":"Price at signal trigger time (ASCII, max 30 chars)"},"data":{"$ref":"#/components/schemas/SignalListenerData"}}},"SignalListenerData":{"type":"object","required":["action","position_size","contracts"],"properties":{"action":{"type":"string","description":"Trading action","enum":["buy","sell"]},"position_size":{"type":"string","description":"Position size as a ratio or absolute value"},"contracts":{"type":"string","description":"Number of contracts"},"direction":{"type":"string","description":"Optional trading direction hint"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/signal/listener":{"post":{"tags":["Signal"],"summary":"Push custom trading signal","description":"Push a custom trading signal to drive smart copy orders. Weight: 1.\n\n**Requires `Enable reading` permission.**\n","operationId":"signalListener","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalListenerRequest"}}}},"responses":{"200":{"description":"Signal received successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```
## List user custom signals
> Return a paginated list of user-defined signals. Weight: 1.\
> \
> \*\*Requires \`Bot reading\` permission.\*\*
```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Signal","description":"Custom signal listener and user-defined signal management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"UserSignalListResponse":{"type":"object","properties":{"pageToken":{"type":"string","description":"Pagination token for the next page. Empty string when there are no more results."},"signals":{"type":"array","description":"List of user-defined signals","items":{"$ref":"#/components/schemas/UserSignalDetail"}}}},"UserSignalDetail":{"type":"object","properties":{"signalType":{"type":"string","description":"Signal type identifier (auto-generated)"},"title":{"type":"string","description":"Signal name"},"description":{"type":"string","description":"Signal description"},"confirmConfig":{"type":"integer","description":"Whether the webhook is configured: 0 = not confirmed, 1 = confirmed","enum":[0,1]},"tradingviewConfig":{"$ref":"#/components/schemas/TradingViewConfig"}}},"TradingViewConfig":{"type":"object","properties":{"webhookUrl":{"type":"string","description":"Webhook URL to configure in TradingView"},"message":{"type":"string","description":"JSON message template to use in TradingView alert"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/signal/userSignal":{"get":{"tags":["Signal"],"summary":"List user custom signals","description":"Return a paginated list of user-defined signals. Weight: 1.\n\n**Requires `Bot reading` permission.**\n","operationId":"listUserSignals","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"pageToken","in":"query","required":false,"description":"Pagination token returned by the previous response. Omit for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Signal list retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UserSignalListResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```
## Create user custom signal
> Create a new user-defined signal. Each user can have at most 100 signals. Weight: 1.\
> \
> \*\*Requires \`Bot trading\` permission.\*\*
```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Signal","description":"Custom signal listener and user-defined signal management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"CreateUserSignalRequest":{"type":"object","required":["title"],"properties":{"title":{"type":"string","description":"Signal name (max 100 chars)","maxLength":100},"description":{"type":"string","description":"Signal description (max 1000 chars)","maxLength":1000}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"UserSignalDetail":{"type":"object","properties":{"signalType":{"type":"string","description":"Signal type identifier (auto-generated)"},"title":{"type":"string","description":"Signal name"},"description":{"type":"string","description":"Signal description"},"confirmConfig":{"type":"integer","description":"Whether the webhook is configured: 0 = not confirmed, 1 = confirmed","enum":[0,1]},"tradingviewConfig":{"$ref":"#/components/schemas/TradingViewConfig"}}},"TradingViewConfig":{"type":"object","properties":{"webhookUrl":{"type":"string","description":"Webhook URL to configure in TradingView"},"message":{"type":"string","description":"JSON message template to use in TradingView alert"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/signal/userSignal":{"post":{"tags":["Signal"],"summary":"Create user custom signal","description":"Create a new user-defined signal. Each user can have at most 100 signals. Weight: 1.\n\n**Requires `Bot trading` permission.**\n","operationId":"createUserSignal","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserSignalRequest"}}}},"responses":{"200":{"description":"Signal created successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UserSignalDetail"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```
## Get user custom signal detail
> Return detail of a specific user-defined signal including webhook URL and message template. Weight: 1.\
> \
> \*\*Requires \`Bot reading\` permission.\*\*
```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Signal","description":"Custom signal listener and user-defined signal management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"UserSignalDetail":{"type":"object","properties":{"signalType":{"type":"string","description":"Signal type identifier (auto-generated)"},"title":{"type":"string","description":"Signal name"},"description":{"type":"string","description":"Signal description"},"confirmConfig":{"type":"integer","description":"Whether the webhook is configured: 0 = not confirmed, 1 = confirmed","enum":[0,1]},"tradingviewConfig":{"$ref":"#/components/schemas/TradingViewConfig"}}},"TradingViewConfig":{"type":"object","properties":{"webhookUrl":{"type":"string","description":"Webhook URL to configure in TradingView"},"message":{"type":"string","description":"JSON message template to use in TradingView alert"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/signal/userSignal/detail":{"get":{"tags":["Signal"],"summary":"Get user custom signal detail","description":"Return detail of a specific user-defined signal including webhook URL and message template. Weight: 1.\n\n**Requires `Bot reading` permission.**\n","operationId":"getUserSignal","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"signalType","in":"query","required":true,"description":"Signal type identifier","schema":{"type":"string"}}],"responses":{"200":{"description":"Signal detail retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UserSignalDetail"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```
## Edit user custom signal
> Update the title and/or description of an existing user-defined signal. Weight: 1.\
> \
> \*\*Requires \`Bot trading\` permission.\*\*\
> \
> At least one of \`title\` or \`description\` must be provided.
```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Signal","description":"Custom signal listener and user-defined signal management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"EditUserSignalRequest":{"type":"object","description":"At least one field must be provided.","properties":{"title":{"type":"string","description":"New signal name (max 100 chars)","maxLength":100},"description":{"type":"string","description":"New signal description (max 10000 chars)","maxLength":10000}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/signal/userSignal/edit":{"post":{"tags":["Signal"],"summary":"Edit user custom signal","description":"Update the title and/or description of an existing user-defined signal. Weight: 1.\n\n**Requires `Bot trading` permission.**\n\nAt least one of `title` or `description` must be provided.\n","operationId":"editUserSignal","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"signalType","in":"query","required":true,"description":"Signal type identifier","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditUserSignalRequest"}}}},"responses":{"200":{"description":"Signal updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```
## Delete user custom signal
> Delete a user-defined signal. Weight: 1.\
> \
> \*\*Requires \`Bot trading\` permission.\*\*\
> \
> Deletion is rejected if the signal has any non-cancelled orders. Error code \`SIGNAL\_HAS\_UNCLOSED\_ORDERS\` is returned with the open order count in \`data.cnt\`.
```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Signal","description":"Custom signal listener and user-defined signal management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/signal/userSignal/delete":{"delete":{"tags":["Signal"],"summary":"Delete user custom signal","description":"Delete a user-defined signal. Weight: 1.\n\n**Requires `Bot trading` permission.**\n\nDeletion is rejected if the signal has any non-cancelled orders. Error code `SIGNAL_HAS_UNCLOSED_ORDERS` is returned with the open order count in `data.cnt`.\n","operationId":"deleteUserSignal","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"signalType","in":"query","required":true,"description":"Signal type identifier","schema":{"type":"string"}}],"responses":{"200":{"description":"Signal deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"description":"Bad request or unclosed orders exist","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"cnt":{"type":"integer","description":"Number of unclosed orders preventing deletion"}}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```