cocos-capital-client

Unofficial Python client for Cocos Capital API.

Disclaimer: This is NOT an official library. It was created by reverse engineering the Cocos Capital API. Use at your own risk.

Installation

# From GitHub
pip install git+https://github.com/testacode/cocos-capital-client.git

# With uv
uv add git+https://github.com/testacode/cocos-capital-client.git

# Local development
uv add --editable ../cocos-capital-client

Configuration

The client requires your Cocos Capital credentials. Never hardcode credentials in your code.

Environment Variables (Recommended)

export COCOS_EMAIL="your@email.com"
export COCOS_PASSWORD="your-password"
export COCOS_TOTP_SECRET="YOUR_TOTP_SECRET"  # Base32 encoded

import os
from cocos_capital_client import CocosClient

async with CocosClient(
    email=os.environ["COCOS_EMAIL"],
    password=os.environ["COCOS_PASSWORD"],
    totp_secret=os.environ["COCOS_TOTP_SECRET"],
) as client:
    portfolio = await client.get_portfolio()

Getting Your TOTP Secret

1. Go to Cocos Capital app settings
2. Enable 2FA if not already enabled
3. When shown the QR code, extract the secret parameter from the otpauth:// URL
4. The secret is a Base32 encoded string (e.g., JBSWY3DPEHPK3PXP)

Quick Start

Async Client (Recommended)

from cocos_capital_client import CocosClient, OrderRequest

async with CocosClient(
    email="your@email.com",
    password="your-password",
    totp_secret="YOUR_TOTP_SECRET"  # Base32 encoded
) as client:
    # Get portfolio
    portfolio = await client.get_portfolio()
    print(f"Positions: {len(portfolio.positions)}")
    print(f"Total ARS: {portfolio.total_value_ars}")

    # Get buying power
    bp = await client.get_buying_power()
    print(f"Available: {bp.amount} {bp.currency}")

    # Search tickers
    tickers = await client.search_tickers("GGAL")
    for t in tickers:
        print(f"{t.symbol}: {t.last_price}")

    # Submit order
    order = await client.submit_order(OrderRequest(
        long_ticker="GGAL",
        side="BUY",
        type="LIMIT",
        quantity=100,
        price=1500.50,
    ))
    print(f"Order {order.id}: {order.status}")

Sync Client

from cocos_capital_client import SyncCocosClient

with SyncCocosClient(email, password, totp_secret) as client:
    portfolio = client.get_portfolio()
    orders = client.get_orders()

Features

• Authentication (login, 2FA TOTP, token refresh)
• Portfolio (positions, balances, performance)
• Orders (submit, cancel, list, get)
• Buying/Selling power
• Market data (ticker search, market status)
• Dólar MEP rates
• Fully typed (PEP 561)
• Async-first with sync wrapper

API Reference

Portfolio

Method	Description
get_portfolio()	Get positions and balances
get_buying_power(currency)	Available funds for buying
get_selling_power(ticker)	Available quantity for selling
get_daily_performance()	Today's P&L
get_historical_performance()	Lifetime P&L

Trading

Method	Description
submit_order(request)	Submit buy/sell order
cancel_order(order_id)	Cancel open order
get_orders(status?)	List orders
get_order(order_id)	Get order details

Market Data

Method	Description
search_tickers(query)	Search instruments
get_ticker(symbol)	Get specific ticker
get_market_status()	Check if market is open
get_dolar_mep()	Get dólar MEP rates

Development

# Install dependencies
uv sync --all-extras

# Run checks
uv run ruff check .
uv run ruff format --check .
uv run pyright

# Run tests
uv run pytest -v --cov=cocos_capital_client

Documentation

• API Reference - Full API docs (pdoc)
• Cocos API - Reverse-engineered API endpoints
• Technical Spec - Implementation details
• Security Policy - Vulnerability reporting and best practices

License

MIT