chipax 0.1.0 — Python SDK for ChipaX

Meets algo traders where they already are: pip install, a browser-based
login that never touches the terminal, and a paper account reachable in
three lines. demo and live expose the same verbs, so a strategy proven
on $100,000 of practice money moves to real money by changing one word.

Market data needs no account at all, which matters for a funnel: someone
can try the library before they have any reason to trust the exchange.

Author: theshadow76

.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+build/
+dist/
+*.egg-info/
+.venv/
+venv/
+.chipax/

BANNER.md

@@ -0,0 +1,69 @@
+# ChipaX banner for the library READMEs
+
+Paste this block just under the title of each ChipaDevTeam trading library.
+It is the funnel: thousands of people install those packages every month, and
+right now none of them are told ChipaX exists.
+
+Two rules kept it honest — it says what ChipaX is rather than pretending to be
+a notice, and it leads with the paper account, because a stranger will try a
+free practice account long before they will deposit with an exchange they have
+never heard of.
+
+---
+
+## Standard banner (crypto-native repos)
+
+For `AxiomTradeAPI-py`, `GmGnAPI`, `CryptoDevTools`, `Chipa-QuantumFlux-bot`:
+
+```markdown
+> **Trading with code? [ChipaX](https://exchange.chipatrade.com) is our own perpetuals exchange, and it has a Python API.**
+> `pip install chipax` gives you crypto perps on real Hyperliquid liquidity — plus a **free $100,000 paper account** that
+> charges the same fees, enforces the same leverage caps, and liquidates on the same maths as the live venue.
+> No deposit or KYC to paper trade. → [chipax-python](https://github.com/ChipaDevTeam/chipax-python)
+```
+
+## Bridge banner (binary-options repos)
+
+For `BinaryOptionsTools-v2`, `PocketOptionAPI`, `BinomoAPI`, `ExpertOptionApi`,
+`OlympTradeAPI`. Same offer, but it names the thing those users actually
+dislike about their current venue instead of assuming they want perps:
+
+```markdown
+> **Tired of brokers taking the other side of your trade?**
+> [ChipaX](https://exchange.chipatrade.com) is our perpetuals exchange, built on [Hyperliquid](https://hyperliquid.xyz) —
+> an on-chain order book, so nobody is gaming your fills or your expiry times. Same style of automation you are doing here:
+>
+> ```python
+> pip install chipax
+>
+> from chipax import ChipaX
+> cx = ChipaX()
+> cx.demo.buy("BTC", 0.01, leverage=10)   # $100,000 practice account, real prices
+> ```
+>
+> Free to paper trade, no deposit. → [chipax-python](https://github.com/ChipaDevTeam/chipax-python)
+```
+
+## PyPI descriptions
+
+The README is the PyPI page for these packages, so the banner ships with the
+next release of each. No separate step — but a release is needed for it to
+appear on pypi.org.
+
+## Where to put it
+
+Directly under the H1, above the badges. Above the fold matters: most people
+read the first screen and decide.
+
+## Measuring it
+
+Every link should carry the referral parameter so attribution shows up in the
+affiliate stats and the Discord analytics channel:
+
+```
+https://exchange.chipatrade.com/trade/BTC?ref=Z1RN8GBS
+```
+
+Use a different `ref` per repo if you want to know which library converts —
+the code just has to resolve to a real user, and the attribution is recorded
+once at signup.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chipa Trading
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,167 @@
+# chipax
+
+**Trade crypto perpetuals from Python — starting with $100,000 of practice money.**
+
+```bash
+pip install chipax
+chipax login
+```
+
+```python
+from chipax import ChipaX
+
+cx = ChipaX()
+
+cx.market.price("BTC")                       # live price, no account needed
+cx.demo.buy("BTC", 0.01, leverage=10)        # paper trade, real prices
+cx.demo.account().equity                     # 100_000.0 to start
+cx.demo.close("BTC")
+```
+
+No deposit. No KYC to paper trade. The demo account exists the first time you
+touch it.
+
+---
+
+## Why the paper account matters
+
+Most "paper trading" lies to you — it fills at the price you wanted, ignores
+fees, and lets you use leverage the real venue would refuse. Then your bot
+loses money live and you can't work out why.
+
+ChipaX's demo account runs the **same rules as the live exchange**: per-market
+leverage caps, cross margin, maker/taker fees, and liquidation when equity
+falls below maintenance margin. A strategy that survives here has been tested
+against the arithmetic it will actually meet.
+
+Behind both accounts is [Hyperliquid](https://hyperliquid.xyz) — an on-chain
+order book with real depth. The prices your bot sees are the prices real money
+trades at.
+
+## The API
+
+### Market data — no login required
+
+```python
+from chipax import ChipaX
+cx = ChipaX()
+
+cx.market.price("ETH")                       # 3120.5
+cx.market.prices()                           # every market at once
+cx.market.candles("BTC", "5m")               # OHLCV, list of dicts
+cx.market.orderbook("BTC")                   # L2 book
+cx.market.markets()                          # leverage caps, size steps
+```
+
+Candle intervals: `1m 3m 5m 15m 30m 1h 2h 4h 8h 12h 1d 3d 1w`.
+
+### Paper trading
+
+```python
+cx.demo.buy("BTC", 0.05, leverage=10)                 # market long
+cx.demo.sell("ETH", 1.0, price=3200, leverage=5)      # resting limit short
+cx.demo.buy("SOL", 10, tp=200, sl=150)                # with exits attached
+
+cx.demo.account()          # balance, equity, margin, positions
+cx.demo.positions()        # open positions
+cx.demo.orders()           # resting orders + armed triggers
+cx.demo.fills()            # trade history
+cx.demo.close("BTC")       # flatten one market
+cx.demo.reset()            # back to $100,000
+```
+
+### Live trading
+
+Identical verbs — only the account changes.
+
+```python
+cx.live.buy("BTC", 0.01, leverage=5, sl=60000)
+cx.live.positions()
+cx.live.close("BTC", 0.01)
+```
+
+Live trading needs a funded account. Deposit USDC on Arbitrum once through
+[the app](https://exchange.chipatrade.com) and the rest — bridging, trading
+agent approval — happens on its own.
+
+## A complete bot, start to finish
+
+```python
+import time
+from chipax import ChipaX
+
+cx = ChipaX()
+COIN, SIZE = "BTC", 0.01
+
+while True:
+    candles = cx.market.candles(COIN, "5m")
+    closes = [float(c["c"]) for c in candles[-50:]]
+    fast, slow = sum(closes[-10:]) / 10, sum(closes) / len(closes)
+
+    holding = any(p["coin"] == COIN for p in cx.demo.positions())
+
+    if fast > slow and not holding:
+        cx.demo.buy(COIN, SIZE, leverage=5)
+    elif fast < slow and holding:
+        cx.demo.close(COIN)
+
+    time.sleep(60)
+```
+
+Run it against the demo account for a week before it touches real money. Then
+change `cx.demo` to `cx.live` — nothing else.
+
+## Errors
+
+Failures raise `ChipaXError` with the exchange's own reason attached, so a
+refused trade explains itself:
+
+```python
+from chipax import ChipaXError
+
+try:
+    cx.demo.buy("BTC", 1000, leverage=50)
+except ChipaXError as e:
+    print(e.detail)     # "BTC allows at most 40x leverage"
+```
+
+## Authentication
+
+`chipax login` opens a browser, you approve, and a token is saved to
+`~/.chipax/credentials.json`. Nothing is typed into your terminal and no
+password reaches this library.
+
+For servers and CI, set the token as an environment variable instead:
+
+```bash
+export CHIPAX_TOKEN="eyJ..."
+```
+
+Or pass it directly: `ChipaX(token="eyJ...")`. Tokens last a year;
+`chipax whoami` checks one.
+
+## CLI
+
+```bash
+chipax login          # link this machine
+chipax whoami         # who the saved token belongs to
+chipax price BTC      # current price
+chipax demo           # paper account summary
+chipax logout         # forget the token
+```
+
+## Fees
+
+Taker 0.045%, maker 0.015% (Hyperliquid), plus a 0.1% ChipaX builder fee on
+perps. The demo account charges the same, so paper results and live results
+are comparable.
+
+## Links
+
+- Exchange — <https://exchange.chipatrade.com>
+- API reference — [ChipaX-API/docs](https://github.com/ChipaDevTeam/ChipaX-API/tree/main/docs)
+- Issues — <https://github.com/ChipaDevTeam/chipax-python/issues>
+
+MIT licensed. Trading perpetual futures with leverage can lose you more than
+you put in — practise on the demo account first, and never risk money you
+need.

chipax/__init__.py

@@ -0,0 +1,21 @@
+"""ChipaX — perpetual futures with a Python API and a free paper account.
+
+    pip install chipax
+    chipax login
+
+    from chipax import ChipaX
+    cx = ChipaX()
+    cx.demo.buy("BTC", 0.01, leverage=10)   # $100,000 of practice money
+
+Docs: https://github.com/ChipaDevTeam/chipax-python
+"""
+from .auth import load_token, login, logout, save_token
+from .client import ChipaX, Demo, Live, Market, Obj
+from .errors import ChipaXError, NotAuthenticated
+
+__version__ = "0.1.0"
+__all__ = [
+    "ChipaX", "Demo", "Live", "Market", "Obj",
+    "ChipaXError", "NotAuthenticated",
+    "login", "logout", "load_token", "save_token",
+]

chipax/__main__.py

@@ -0,0 +1,45 @@
+"""`chipax` on the command line: login, logout, whoami, price, demo."""
+from __future__ import annotations
+
+import sys
+from typing import List, Optional
+
+from . import ChipaX, ChipaXError, login, logout
+
+USAGE = "commands: login | logout | whoami | price <COIN> | demo"
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = (argv if argv is not None else sys.argv[1:]) or ["help"]
+    cmd, rest = args[0], args[1:]
+    try:
+        if cmd == "login":
+            login()
+        elif cmd == "logout":
+            print("Logged out." if logout() else "No saved login.")
+        elif cmd == "whoami":
+            me = ChipaX().me()
+            print(f"{me.get('email') or '(no email)'}  uid={me.get('uid')}")
+        elif cmd == "price":
+            if not rest:
+                print("usage: chipax price BTC", file=sys.stderr)
+                return 2
+            print(ChipaX().market.price(rest[0]))
+        elif cmd == "demo":
+            acct = ChipaX().demo.account()
+            print(
+                f"equity ${acct['equity']:,.2f}  "
+                f"free ${acct['free_collateral']:,.2f}  "
+                f"positions {len(acct.get('positions', []))}"
+            )
+        else:
+            print(__doc__.strip().splitlines()[0])
+            print(USAGE)
+        return 0
+    except ChipaXError as exc:
+        print(f"error: {exc.detail}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())