Coins.ph Listens API
Manage user data stream listenKeys for WebSocket connections. A listenKey is required to establish a private WebSocket connection for receiving real-time account updates (orders, balances, positions).
OpenAPI Specification
openapi: 3.0.0
info:
title: TRADING Account Listens API
version: 1.0.0
description: API reference for Account management — Coins.ph
servers:
- url: https://api.pro.coins.ph
description: Production
- url: https://api.9001.pl-qa.coinsxyz.me
description: Sandbox
tags:
- name: Listens
description: Manage user data stream listenKeys for WebSocket connections. A listenKey is required to establish a private WebSocket connection for receiving real-time account updates (orders, balances, positions).
paths:
/openapi/v1/userDataStream:
post:
tags:
- Listens
summary: Create a listenKey (USER_STREAM)
description: 'Start a new user data stream. The returned `listenKey` is used to establish a WebSocket
connection for receiving real-time account updates including order status changes,
balance updates, and position changes.
**Key Notes**
- The `listenKey` is valid for **60 minutes** from creation.
- After creation, connect to: `wss://stream.coins.ph/openapi/ws/<listenKey>`
- A single WebSocket connection is valid for a maximum of **24 hours**.
- Use the keepalive endpoint (PUT) every 30 minutes to maintain the stream.
- No request body or query parameters are required — only the API key header.
**Stream Connection**
After obtaining a `listenKey`, connect via WebSocket:
```
wss://stream.coins.ph/openapi/ws/<listenKey>
```
**Stream Events**
Once connected, you will receive real-time events:
- `outboundAccountPosition` — Account balance changes
- `balanceUpdate` — Non-trading fund activities (deposits, withdrawals, transfers)
- `executionReport` — Order status updates
---
## Additional Info
**Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction)
Weight: 1
**Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk)
- **Real-Time Order Tracking** — Receive instant notifications when orders are filled, cancelled, or rejected
- **Balance Monitoring** — Get immediate updates on deposits, withdrawals, and trade settlements
- **Trading Bot Integration** — Feed live account data into automated trading strategies
**Best Practices**
- Create a new `listenKey` at application startup and maintain it with keepalive requests every 30 minutes
- Implement reconnection logic that creates a new `listenKey` if the WebSocket disconnects
- Close the `listenKey` during graceful application shutdown to release server resources
'
operationId: create_listen_key
parameters:
- in: header
name: X-COINS-APIKEY
required: true
schema:
type: string
description: API key for authentication.
x-codeSamples:
- lang: Shell
label: Create listenKey
source: 'curl -X POST ''https://api.pro.coins.ph/openapi/v1/userDataStream'' \
-H ''X-COINS-APIKEY: <your api key>''
'
responses:
'200':
description: listenKey created successfully.
content:
application/json:
schema:
type: object
properties:
listenKey:
type: string
description: The key used to establish a WebSocket connection for user data stream updates. Valid for 60 minutes.
example: iA9LWJjuMwKWYP4QQPw34GRmBgz3x5AephXSuqcDef1RnzoBVhEcEG63Co5lSg
examples:
success:
summary: listenKey created
value:
listenKey: iA9LWJjuMwKWYP4QQPw34GRmBgz3x5AephXSuqcDef1RnzoBVhEcEG63Co5lSg
default:
description: 'API error response. The `code` field contains the internal API error code (not an HTTP status code).
| Code | Description |
|---|---|
| -1022 | Signature for this request is not valid |
| -2015 | Invalid API-key, IP, or permissions for action |
For the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes).
'
put:
tags:
- Listens
summary: Ping / Keep-alive a listenKey (USER_STREAM)
description: 'Keep a user data stream alive to prevent timeout. User data streams automatically close
after **60 minutes** of inactivity. A keepalive request extends the `listenKey` validity
by another 60 minutes from the time the request is received.
**Key Notes**
- Each successful keepalive resets the 60-minute expiration timer.
- The 24-hour maximum WebSocket connection limit still applies regardless of keepalives.
- Returns an empty object `{}` on success.
- Returns error code `-1125` if the `listenKey` does not exist or has already expired.
**Keepalive Strategy**
- Send keepalive requests every **30 minutes** to maintain a safety margin before the 60-minute expiration.
- If a keepalive fails, create a new `listenKey` and re-establish the WebSocket connection.
---
## Additional Info
**Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction)
Weight: 1
**Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk)
- **Stream Keepalive** — Send periodic keepalive requests to prevent the listenKey from expiring during a long-running session
- **Health Check** — Verify that a `listenKey` is still valid before relying on the stream
**Best Practices**
- Schedule keepalive requests at fixed intervals (every 30 minutes) using a timer or cron job
- Implement error handling: if keepalive returns `-1125`, the stream has expired — create a new `listenKey`
- Log keepalive failures for monitoring and alerting purposes
'
operationId: keepalive_listen_key
parameters:
- in: header
name: X-COINS-APIKEY
required: true
schema:
type: string
description: API key for authentication.
- in: query
name: listenKey
required: true
schema:
type: string
description: The listenKey to keep alive.
example: iA9LWJjuMwKWYP4QQPw34GRmBgz3x5AephXSuqcDef1RnzoBVhEcEG63Co5lSg
x-codeSamples:
- lang: Shell
label: Keep-alive listenKey
source: 'curl -X PUT ''https://api.pro.coins.ph/openapi/v1/userDataStream?listenKey=iA9LWJjuMwKWYP4QQPw34GRmBgz3x5AephXSuqcDef1RnzoBVhEcEG63Co5lSg'' \
-H ''X-COINS-APIKEY: <your api key>''
'
responses:
'200':
description: listenKey keepalive successful. Validity extended by 60 minutes.
content:
application/json:
schema:
type: object
examples:
success:
summary: Keepalive successful
value: {}
default:
description: 'API error response. The `code` field contains the internal API error code (not an HTTP status code).
| Code | Description |
|---|---|
| -1125 | This listenKey does not exist |
| -2015 | Invalid API-key, IP, or permissions for action |
For the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes).
'
delete:
tags:
- Listens
summary: Close a listenKey (USER_STREAM)
description: 'Explicitly close a user data stream. Once closed, the `listenKey` becomes invalid and
the associated WebSocket connection is immediately disconnected. A closed `listenKey`
**cannot be reused** — you must create a new one.
**Key Notes**
- The WebSocket connection associated with this `listenKey` is immediately terminated.
- Returns an empty object `{}` on success.
- Returns error code `-1125` if the `listenKey` does not exist or has already been closed.
- A closed `listenKey` cannot be revived — use the Create endpoint to generate a new one.
---
## Additional Info
**Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction)
Weight: 1
**Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk)
- **Graceful Shutdown** — Close the listenKey explicitly on exit to release server-side resources immediately rather than waiting for the 60-minute timeout
- **Stream Reset** — Terminate and recreate a stream if it enters an inconsistent state
- **Security** — Invalidate a `listenKey` immediately if the associated API key is compromised
**Best Practices**
- Always close listenKeys during application shutdown to release server-side resources
- Implement a shutdown hook that calls this endpoint before process termination
- After closing, clean up local references to the old `listenKey` and WebSocket connection
'
operationId: close_listen_key
parameters:
- in: header
name: X-COINS-APIKEY
required: true
schema:
type: string
description: API key for authentication.
- in: query
name: listenKey
required: true
schema:
type: string
description: The listenKey to close.
example: iA9LWJjuMwKWYP4QQPw34GRmBgz3x5AephXSuqcDef1RnzoBVhEcEG63Co5lSg
x-codeSamples:
- lang: Shell
label: Close listenKey
source: 'curl -X DELETE ''https://api.pro.coins.ph/openapi/v1/userDataStream?listenKey=iA9LWJjuMwKWYP4QQPw34GRmBgz3x5AephXSuqcDef1RnzoBVhEcEG63Co5lSg'' \
-H ''X-COINS-APIKEY: <your api key>''
'
responses:
'200':
description: listenKey closed successfully. The associated WebSocket connection is terminated.
content:
application/json:
schema:
type: object
examples:
success:
summary: listenKey closed
value: {}
default:
description: 'API error response. The `code` field contains the internal API error code (not an HTTP status code).
| Code | Description |
|---|---|
| -1125 | This listenKey does not exist |
| -2015 | Invalid API-key, IP, or permissions for action |
For the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes).
'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-COINS-APIKEY
x-readme:
proxy-enabled: false