Dead-Coin Desk Python SDK

A minimal copy/paste Python client for the Dead-Coin Buyback Desk: quote any delisted token position from live DEX data, reserve the firm USDC bid, and track your orders. Full endpoint semantics in the REST API reference.

Install

pip install requests

Quickstart

from deadcoins import DeadCoinsClient

dc = DeadCoinsClient("https://cymetica.com")

# 1. Quote a position — public, no login needed
q = dc.quote("0x1234…dead", amount_tokens="1500000")   # chain defaults to "auto"
print(q["tier"], q["bid_usdc"], q["discount_pct"], q["expires_at"])

# 2. Reserve the bid — needs an account
dc.login("you@example.com", "…")
order = dc.reserve(q["quote_id"])
print(order["order_id"], order["status"])

# 3. Track your orders
for o in dc.my_orders():
    print(o["order_id"], o["status"], o["bid_usdc"])

SDK Source (paste this file as deadcoins.py)

"""deadcoins.py — minimal client for EventTrader's Dead-Coin Buyback Desk."""
import requests

BASE_PATH = "/api/v1/deadcoins"


class DeadCoinsClient:
    def __init__(self, base_url: str = "https://cymetica.com",
                 email: str | None = None, password: str | None = None):
        self.base = base_url.rstrip("/")
        self.s = requests.Session()
        if email and password:
            self.login(email, password)

    def login(self, email: str, password: str):
        r = self.s.post(f"{self.base}/auth/login",
                        json={"email": email, "password": password}, timeout=15)
        r.raise_for_status()
        token = r.json()["access_token"]
        self.s.headers.update({"Authorization": f"Bearer {token}"})
        return token

    def quote(self, contract_address: str, amount_tokens=None,
              chain: str = "auto"):
        # Public. Omit amount_tokens for a per-token preview
        # (previews cannot be reserved — re-quote with an amount).
        body = {"chain": chain, "contract_address": contract_address}
        if amount_tokens is not None:
            body["amount_tokens"] = str(amount_tokens)
        r = self.s.post(f"{self.base}{BASE_PATH}/quote", json=body, timeout=30)
        r.raise_for_status()
        return r.json()

    def reserve(self, quote_id: str):
        # Auth required. 404 unknown, 409 reserved/declined/preview, 410 expired.
        r = self.s.post(f"{self.base}{BASE_PATH}/reserve",
                        json={"quote_id": quote_id}, timeout=15)
        r.raise_for_status()
        return r.json()

    def my_orders(self):
        # Auth required. Your 50 most recent desk orders, newest first.
        r = self.s.get(f"{self.base}{BASE_PATH}/orders/mine", timeout=10)
        r.raise_for_status()
        return r.json()

Notes

Quotes are firm until expires_at (~15 minutes) — reserve before then or re-quote. tier is LIQUID (real bid, 20–40% liquidity-scaled discount), DUST (tax-loss disposal: nominal bid + flat fee, receipt included), or DECLINED (decline_reason says why). The quote endpoint is rate-limited; back off on 429.

Prefer an LLM driving the desk? The same quote flow is exposed as MCP tools for Claude and other MCP clients.