A lightweight Python library that works as a connector to the Coins.ph public API.

• Features
• Installation
• Quick Start
• Authentication
• Usage Examples
  • REST API Examples
  • WebSocket Examples
• WebSocket Streams
• API Reference
  • REST API Methods
  • WebSocket Methods
• Error Handling
• Contributing
• License

• Comprehensive REST API Coverage: Support for spot trading, wallet operations, fiat transactions, and more
• Real-time WebSocket Streams: Live market data, order updates, and user account information
• Easy to Use: Simple and intuitive interface for both REST and WebSocket APIs
• Type Safety: Well-structured parameter handling
• Flexible Configuration: Multiple client types for different use cases
• Extensive Examples: Sample code for all major operations

• Python 3.6 or higher
• requests library

pip install requests

git clone https://github.com/coins-docs/coins-connector-python.git
cd coins-connector-python

1. Configure your API credentials in config/conf.py:

class Config:
    # REST API configuration
    api_key = "your_api_key_here"
    secret = "your_secret_key_here"
    rest_url = "https://api.coins.ph/"
    
    # WebSocket configuration
    stream_url = "wss://wsapi.coins.ph"
    
    # For invoice operations
    invoice_key = "your_invoice_key_here"
    invoice_secret = "your_invoice_secret_here"

2. Import and use the client:

from coins.spot import Client
import time

# Initialize client
client = Client()

# Get server time
response = client.time()
print(response)

Most endpoints require API key authentication. You need to:

1. Create an API key from your Coins.ph account
2. Configure the key and secret in config/conf.py
3. The library automatically handles signature generation

from coins.spot import Client

client = Client()

# Get exchange information
response = client.exchange_info(symbol='BTCPHP')

# Get order book depth
response = client.depth(symbol='BTCPHP', limit=10)

from coins.spot import Client
import time

client = Client()
timestamp = int(time.time() * 1000)

# Place a limit order
response = client.order_new(
    symbol='BTCPHP',
    side='buy',
    type='limit',
    time_in_force='GTC',
    quantity='0.001',
    price='2000000',
    timestamp=timestamp
)

from coins.spot import Client
import time

client = Client()
timestamp = int(time.time() * 1000)

# Get account balances
response = client.account(timestamp=timestamp)

from coins.websocket.spot import client

# Subscribe to ticker updates for a symbol
client.ticker(symbol='BTCPHP')

from coins.websocket.spot import client

# Subscribe to kline updates (1 minute interval)
client.kline(symbol='BTCPHP', interval='1m')

from coins.websocket.spot import client as ws_client
from coins.spot import Client

# Get listen key for user data stream
rest_client = Client()
listen_key = rest_client.get_listen_key()['listenKey']

# Subscribe to user data (orders, balances, etc.)
ws_client.user_data(listen_key=listen_key)

For more examples, please refer to the examples/ directory.

The library provides real-time WebSocket streams for market data and user account updates. All WebSocket connections are automatically managed, including reconnection on disconnect.

• Aggregate Trade Stream: Real-time aggregated trade data

  client.agg_trade(symbol='BTCPHP')

• Trade Stream: Raw trade information with unique buyer and seller

  client.trade(symbol='BTCPHP')

• Kline/Candlestick Stream: Real-time candlestick updates

  client.kline(symbol='BTCPHP', interval='1m')  # Intervals: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M

• Mini Ticker Stream: 24hr rolling window mini-ticker statistics

  client.mini_ticker(symbol='BTCPHP')  # Single symbol
  client.mini_ticker()  # All symbols

• Ticker Stream: 24hr rolling window ticker statistics

  client.ticker(symbol='BTCPHP')  # Single symbol
  client.ticker()  # All symbols

• Book Ticker Stream: Best bid/ask price and quantity updates

  client.book_ticker(symbol='BTCPHP')  # Single symbol
  client.book_ticker()  # All symbols

• Partial Book Depth Stream: Top bids and asks (5, 10, or 20 levels)

  client.partial_book_depth(symbol='BTCPHP', level=5)  # 5, 10, or 20 levels
  client.partial_book_depth(symbol='BTCPHP', level=20, speed=100)  # With 100ms updates

• Diff Book Depth Stream: Order book depth updates for local management

  client.diff_book_depth(symbol='BTCPHP')
  client.diff_book_depth(symbol='BTCPHP', speed=100)  # With 100ms updates

• Mark Price Stream: Mark price and funding rate updates

  client.mark_price(symbol='BTCPHP')  # Single symbol
  client.mark_price()  # All symbols

• User Data Stream: Real-time account updates (orders, balances, positions)

  # First, get a listen key from REST API
  from coins.spot import Client
  rest_client = Client()
  listen_key = rest_client.get_listen_key()['listenKey']
  
  # Then subscribe to user data stream
  from coins.websocket.spot import client
  client.user_data(listen_key=listen_key)

• All Orders Stream: Real-time order updates for a symbol

  client.all_order(symbol='BTCPHP')

You can provide a custom message handler to process incoming WebSocket messages:

from coins.websocket.spot.websocket_client import SpotWebsocketClient
import json


def my_message_handler(ws, message):
    data = json.loads(message)
    print(f"Received: {data}")


# Create client with custom handler
ws_client = SpotWebsocketClient(on_message=my_message_handler)
ws_client.ticker(symbol='BTCPHP')

• ping() - Test connectivity
• time() - Get server time
• exchange_info() - Get exchange information
• pairs() - Get all trading pairs
• depth() - Get order book depth
• trades() - Get recent trades
• klines() - Get kline/candlestick data
• avg_price() - Get average price
• ticker_24hr() - Get 24hr ticker statistics
• ticker_price() - Get ticker price
• ticker_book_ticker() - Get best price/qty on the order book

• order_new() - Place a new order
• order_test() - Test order placement
• order_detail() - Query order
• order_cancel() - Cancel order
• order_cancel_all() - Cancel all open orders
• order_openorders() - Get open orders
• order_history() - Get order history
• order_cancel_replace() - Cancel and replace order
• my_trades() - Get trade history
• trade_fee() - Get trading fee

• account() - Get account information
• deposit_address() - Get deposit address
• deposit_history() - Get deposit history
• withdraw_apply() - Submit withdrawal
• withdraw_history() - Get withdrawal history
• transaction_history() - Get transaction history
• address_whitelist() - Get withdrawal address whitelist
• api_keys() - Get API keys information
• config_getall() - Get wallet configuration

• subAccount_create() - Create sub-account
• subAccount_list() - Get sub-account list
• subAccount_asset() - Get sub-account assets
• subAccount_transfer_universal_transfer() - Universal transfer
• subAccount_transfer_sub_to_master() - Sub-account to master transfer
• subAccount_transfer_universal_transfer_history() - Get transfer history
• subAccount_transfer_sub_history() - Get sub-account transfer history
• collect_from_subaccount() - Collect funds from sub-accounts
• get_fund_record() - Get fund collection records
• wallet_deposit_address() - Get sub-account deposit address
• wallet_deposit_history() - Get sub-account deposit history

• fiat_support_channel() - Get supported channels
• fiat_details() - Get transaction details
• fiat_history_order() - Get transaction history
• fiat_history_order_v2() - Get transaction history (V2)
• generate_qr_code() - Generate QR code
• generate_static_qr_code() - Generate static QR code
• cancel_qr_code() - Cancel QR code
• update_qr_code() - Update QR code
• get_qr_code() - Get QR code details
• get_qr_code_static_list() - Get static QR code list

• get_supported_trading_pairs() - Get supported pairs
• get_quote() - Get conversion quote
• accept_quote() - Accept quote
• query_order_history() - Query conversion history

• crypto_accounts() - Get crypto accounts
• p2p_transfer() - Execute P2P transfer
• query_transfer() - Query transfer

• payment_request() - Create payment request
• get_payment_request() - Get payment request
• cancel_payment_request() - Cancel payment request
• payment_request_reminder() - Send payment reminder

• user_ip() - Get user IP
• check_sys_status() - Check system status

The SpotWebsocketClient class provides methods to subscribe to real-time data streams.

Initialization Parameters:

• stream_url - WebSocket stream URL (default from config)
• on_message - Callback function for incoming messages
• on_open - Callback function when connection opens
• on_close - Callback function when connection closes
• on_error - Callback function for errors
• on_ping - Callback function for ping frames
• on_pong - Callback function for pong frames
• proxies - Optional proxy configuration
• max_reconnect_attempts - Maximum reconnection attempts (default: 5)
• reconnect_delay - Delay between reconnection attempts in seconds (default: 5)

• agg_trade(symbol, id=None, action=None) - Subscribe to aggregate trade stream
• trade(symbol, id=None, action=None) - Subscribe to raw trade stream
• kline(symbol, interval, id=None, action=None) - Subscribe to kline/candlestick stream
  • Supported intervals: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M
• mini_ticker(symbol=None, id=None, action=None) - Subscribe to mini ticker stream
  • If symbol is None or empty, subscribes to all symbols
• ticker(symbol=None, id=None, action=None) - Subscribe to ticker stream
  • If symbol is None or empty, subscribes to all symbols
• book_ticker(symbol, id=None, action=None) - Subscribe to book ticker stream
• partial_book_depth(symbol, level=5, speed=None, id=None, action=None) - Subscribe to partial book depth
  • Valid levels: 5, 10, 20
  • Optional speed: 100 (for 100ms updates)
• diff_book_depth(symbol, speed=None, id=None, action=None) - Subscribe to differential book depth
  • Optional speed: 100 (for 100ms updates)
• mark_price(symbol, id=None, action=None) - Subscribe to mark price stream
  • If symbol is None or empty, subscribes to all symbols
• all_order(symbol, id=None, action=None) - Subscribe to all orders stream for a symbol

• user_data(listen_key, id=None, action=None) - Subscribe to user data stream
  • Requires a valid listen key obtained from REST API

Each subscription method supports optional parameters:

• id - Custom identifier for the subscription
• action - Action to perform (e.g., subscribe/unsubscribe)

The library returns the raw API response. You should handle errors based on the response:

from coins.spot import Client
import time

client = Client()
timestamp = int(time.time() * 1000)

response = client.order_new(
    symbol='BTCPHP',
    side='buy',
    type='limit',
    quantity='0.001',
    price='2000000',
    timestamp=timestamp
)

# Check for errors
if isinstance(response, dict):
    if 'code' in response and response['code'] != 200:
        print(f"Error: {response.get('msg', 'Unknown error')}")
    else:
        print("Success:", response)
else:
    print("Response:", response)

• 400 - Bad Request (invalid parameters)
• 401 - Unauthorized (invalid API key or signature)
• 403 - Forbidden (IP restriction or insufficient permissions)
• 429 - Too Many Requests (rate limit exceeded)
• 500 - Internal Server Error

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

This project is licensed under the MIT License.

For issues, questions, or contributions, please visit the GitHub repository.

For API documentation, visit Coins API Documentation.