allium-cli 0.2.0__py3-none-any.whl

allium_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,306 @@
+Metadata-Version: 2.4
+Name: allium-cli
+Version: 0.2.0
+Summary: CLI for Allium blockchain data APIs
+Project-URL: Documentation, https://docs.allium.so
+Project-URL: Homepage, https://allium.so
+Project-URL: Repository, https://github.com/Allium-Science/allium-cli
+Author-email: Allium <support@allium.so>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database :: Front-Ends
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: eth-account~=0.13
+Requires-Dist: httpx~=0.27
+Requires-Dist: privy-client~=0.5
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pympp[tempo]==0.3
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich-click>=1.9.7
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli-w>=1.0
+Description-Content-Type: text/markdown
+
+# Allium CLI
+
+Command-line interface for querying blockchain data across 80+ chains via the [Allium](https://allium.so) platform. Supports realtime token prices, wallet balances, transaction history, and SQL queries against Allium's data warehouse.
+
+## Installation
+
+```bash
+curl -sSL https://raw.githubusercontent.com/Allium-Science/allium-cli/main/install.sh | sh
+```
+
+Or install directly with your preferred package manager:
+
+```bash
+uv tool install allium-cli   # recommended
+pipx install allium-cli
+pip install allium-cli
+```
+
+This installs the `allium` command. Run `allium auth setup` to configure authentication.
+
+## Authentication
+
+The CLI supports four authentication methods. Run the interactive wizard, or pass arguments directly for scripted/CI setups:
+
+```bash
+# Interactive wizard (arrow-key selection)
+allium auth setup
+
+# Non-interactive one-liners
+allium auth setup --method api_key --api-key sk-...
+allium auth setup --method x402_key --private-key 0x... --network eip155:8453
+allium auth setup --method x402_privy \
+    --privy-app-id ... --privy-app-secret ... \
+    --privy-wallet-id ... --network eip155:8453
+allium auth setup --method tempo --private-key 0x... --chain-id 42431
+```
+
+| Method | Description |
+|---|---|
+| **API Key** | Standard key from [app.allium.so/settings/api-keys](https://app.allium.so/settings/api-keys) |
+| **x402 Private Key** | Pay-per-call with USDC on Base -- no API key needed |
+| **x402 Privy** | x402 via Privy server wallets -- no private key handling |
+| **Tempo MPP** | Tempo micropayment protocol |
+
+Optional flags: `--name <profile-name>` (defaults to the method name), `--no-active` (skip setting as active profile).
+
+Credentials are stored in `~/.config/allium/credentials.toml` (file permissions restricted to owner).
+
+### Profile management
+
+```bash
+allium auth list          # Show all profiles
+allium auth use <name>    # Switch active profile
+allium auth remove <name> # Delete a profile
+```
+
+## Global Options
+
+```
+--profile TEXT             Override the active auth profile for this command
+--format [json|table|csv]  Output format (default: json)
+-v, --verbose              Show progress details (run IDs, spinners, status)
+--help                     Show help and exit
+```
+
+## Commands
+
+### `allium realtime` -- Realtime Blockchain Data
+
+Query realtime blockchain data with 3-5s freshness across 20+ chains.
+
+#### Prices
+
+Token prices derived from on-chain DEX trades with VWAP calculation and outlier detection.
+
+```bash
+# Latest minute-level price and OHLC values
+allium realtime prices latest \
+  --chain solana --token-address So11111111111111111111111111111111111111112
+
+# Price at a specific timestamp
+allium realtime prices at-timestamp \
+  --chain ethereum --token-address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
+  --timestamp 2026-01-15T12:00:00Z --time-granularity 1h
+
+# Historical price series
+allium realtime prices history \
+  --chain ethereum --token-address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
+  --start-timestamp 2026-01-01T00:00:00Z --end-timestamp 2026-01-07T00:00:00Z \
+  --time-granularity 1d
+
+# 24h/1h price stats (high, low, volume, trade count, percent change)
+allium realtime prices stats \
+  --chain solana --token-address So11111111111111111111111111111111111111112
+```
+
+**Options:** `--chain`, `--token-address` (repeatable, paired in order), `--body` (JSON override), `--timestamp`, `--start-timestamp`, `--end-timestamp`, `--time-granularity [15s|1m|5m|1h|1d]`
+
+#### Tokens
+
+```bash
+# List top tokens by volume
+allium realtime tokens list --chain ethereum --sort volume --limit 10
+
+# Fuzzy search by name or symbol
+allium realtime tokens search -q "USDC"
+
+# Exact lookup by chain + contract address
+allium realtime tokens chain-address \
+  --chain ethereum --token-address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
+```
+
+**Options:** `--chain`, `--token-address` (repeatable), `--sort [volume|trade_count|fully_diluted_valuation|address|name]`, `--order [asc|desc]`, `--limit`, `-q/--query`
+
+#### Balances
+
+```bash
+# Current token balances for a wallet
+allium realtime balances latest \
+  --chain ethereum --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+
+# Historical balance snapshots
+allium realtime balances history \
+  --chain ethereum --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 \
+  --start-timestamp 2026-01-01T00:00:00Z --limit 100
+```
+
+**Options:** `--chain`, `--address` (repeatable, paired), `--start-timestamp`, `--end-timestamp`, `--limit`, `--body`
+
+#### Transactions
+
+```bash
+# Wallet transaction activity with decoded activities and labels
+allium realtime transactions \
+  --chain ethereum --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 \
+  --activity-type dex_trade --lookback-days 7 --limit 50
+```
+
+**Options:** `--chain`, `--address` (repeatable), `--activity-type`, `--lookback-days`, `--limit`, `--body`
+
+#### PnL
+
+```bash
+# Wallet profit and loss
+allium realtime pnl \
+  --chain ethereum --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+
+# With historical breakdown
+allium realtime pnl \
+  --chain ethereum --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 \
+  --with-historical-breakdown
+```
+
+**Options:** `--chain`, `--address` (repeatable), `--with-historical-breakdown`, `--body`
+
+---
+
+### `allium explorer` -- SQL Query Execution
+
+Run SQL queries on Allium's data warehouse. By default, the CLI polls silently and prints results. Use `-v` for progress details.
+
+```bash
+# Execute ad-hoc SQL (requires x402 or Tempo auth)
+allium explorer run-sql "SELECT chain, COUNT(*) FROM crosschain.dex.trades GROUP BY chain LIMIT 10"
+
+# Execute SQL from a file
+allium explorer run-sql query.sql --limit 1000
+
+# Run a saved query by ID with parameters
+allium explorer run abc123 --param start_date=2026-01-01 --param chain=ethereum
+
+# Just get the run ID without waiting
+allium explorer run-sql "SELECT 1" --no-wait
+
+# Check status of a query run
+allium explorer status <run_id>
+
+# Fetch results of a completed run
+allium explorer results <run_id>
+
+# Pipe CSV output directly
+allium --format csv explorer run-sql "SELECT 1" > output.csv
+```
+
+| Command | Description |
+|---|---|
+| `run-sql <SQL_OR_FILE>` | Execute ad-hoc SQL (x402/Tempo auth required) |
+| `run <QUERY_ID>` | Execute a saved Explorer query by ID |
+| `status <RUN_ID>` | Check query run status (created, running, success, failed, canceled) |
+| `results <RUN_ID>` | Download results of a completed run |
+
+**Options:** `--limit`, `--no-wait`, `--param key=value` (repeatable), `--compute-profile`
+
+---
+
+### `allium mp` -- Machine Payment Tracking
+
+Track costs for x402 and Tempo micropayment API calls. Payments are logged automatically to `~/.config/allium/cost_log.csv`.
+
+```bash
+# Total spend summary grouped by method and network
+allium mp cost
+
+# Full itemized payment history
+allium mp cost list
+
+# Export as CSV
+allium --format csv mp cost list
+
+# Clear the cost log
+allium mp cost clear
+```
+
+| Command | Description |
+|---|---|
+| `mp cost` | Total spend summary (grouped by method/network with call counts) |
+| `mp cost list` | Full itemized history with per-row details |
+| `mp cost clear` | Delete the cost log (with confirmation prompt) |
+
+---
+
+### `allium auth` -- Authentication Management
+
+```bash
+# Interactive setup wizard (arrow-key selection)
+allium auth setup
+
+# Non-interactive setup (for scripts/CI)
+allium auth setup --method api_key --api-key sk-...
+allium auth setup --method tempo --private-key 0x... --chain-id 42431
+
+# List all configured profiles
+allium auth list
+
+# Switch active profile
+allium auth use <name>
+
+# Delete a profile
+allium auth remove <name>
+```
+
+## JSON Body Override
+
+All realtime commands support a `--body` flag that accepts either inline JSON or a path to a `.json` file. When provided, it overrides all other options:
+
+```bash
+# Inline JSON
+allium realtime prices latest --body '[{"chain":"solana","token_address":"So111..."}]'
+
+# From file
+allium realtime prices latest --body tokens.json
+```
+
+## Shell Completions
+
+Tab-completion is available for all commands, subcommands, and options. Add one of the following to your shell config:
+
+```bash
+# Bash — add to ~/.bashrc
+eval "$(_ALLIUM_COMPLETE=bash_source allium)"
+
+# Zsh — add to ~/.zshrc
+eval "$(_ALLIUM_COMPLETE=zsh_source allium)"
+
+# Fish — add to ~/.config/fish/config.fish
+_ALLIUM_COMPLETE=fish_source allium | source
+```
+
+Reload your shell to activate completions.
+
+## Documentation
+
+Full API documentation: [docs.allium.so](https://docs.allium.so)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and release instructions.

allium_cli-0.2.0.dist-info/RECORD

@@ -0,0 +1,44 @@
+cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cli/main.py,sha256=9eV1TaJhIbVyp6B6i4mfc82dpfgNavwWleGnJYk1DnM,3042
+cli/auth/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cli/auth/api_key.py,sha256=Md52mwytMhBfJieNnsqtw8DfDt4N7ayXM4SLFXeu1Rs,184
+cli/auth/tempo.py,sha256=bY-Do6zWTZqZE177ynfS7xz-E3VpjyZymw1dxIOT91U,3309
+cli/auth/x402_key.py,sha256=61BGrcwX-GNSvZgr_C--gWn0mhvUgCNNysfgCHGqetI,1047
+cli/auth/x402_privy.py,sha256=GsBImZk_qGliILA6ITZ8kp6OeJ-YaZs_iZ6BXb1kBHk,832
+cli/clients/__init__.py,sha256=Y0lLc0ZL4-Y24sbul6_G_Tc0N0ygnHDaDRKRs-el7Ps,135
+cli/clients/factory.py,sha256=dvq5r2KuDN9sECVq2AyowgmxUTfVPiJQ7NgJ9jCKOr4,2630
+cli/clients/http.py,sha256=d33N3AnVToHNOgJM3BRat732T-CqpoN1kl5A2vv_GR8,2877
+cli/clients/protocol.py,sha256=Z-SrpRuMulcfPxgb3EDADYwHoxfchch9cKbTl1qsd2I,518
+cli/clients/tempo.py,sha256=mtkjjZFoG8SLxNUp0bwvq28oXwJHHAIff4JGlw12NOM,1606
+cli/clients/x402.py,sha256=_RyvjAvKLcM2esP12pobGeasMxjfx4NDbow0i40B5lY,5929
+cli/commands/__init__.py,sha256=QcGvn8b-5lURzbZh-6RJndY1cbaNqQlBDVNW3XJ9Ywc,448
+cli/commands/auth.py,sha256=39gD2z7EdhyuWgiCC7FCBvK3OLTjUFLnFUib-wQGoFg,12256
+cli/commands/explorer.py,sha256=JX0dlzUYWcH4BszdxTHm5yxpg6mQFth9YDdnsy_BbHQ,8930
+cli/commands/mp.py,sha256=se26EafW2o4gTGURIWfEiF_3pjnE-qgFFWFwGscD4-M,4954
+cli/commands/realtime.py,sha256=VQQaq5g_Tkfwvt35xOwbC_3J28tcST8gDoe5w_Bujus,12312
+cli/constants/__init__.py,sha256=FEM6EUJ2FPh_7s0sdO8ejyz4tpQjzBflAibDXgwrHKU,589
+cli/constants/api.py,sha256=ge9bm1FDueq6IEsugZyQwtsmJiCmlWpc7TWqacwiCR4,126
+cli/constants/config.py,sha256=dUTqHRRZ2ZHfIVYxkd4VuQpnp82AbEKJAykEP4mB5-Q,421
+cli/constants/ui.py,sha256=FDJ-zlo4m_OpYImsC_DcRUkjeE7UD2VtSc_0ww287sU,1371
+cli/types/__init__.py,sha256=WHsiIfqi42_J3bXvQwTrqE7zWI_aToYc0Qwc9Fn0YIw,769
+cli/types/config.py,sha256=ZATqu0LdSlc3myBFljQ7Aduqu7dMbG5noWD0rnZkW2w,885
+cli/types/context.py,sha256=YIhRgSajB4Th1L_qme1Wzn3uj79zQPwu3xS4Lem5o84,347
+cli/types/enums.py,sha256=Czw5kId_mu198T_S0AX3-CyaOfM-zAZ-ePH21mSA4Tw,1196
+cli/types/labels.py,sha256=Ye2FdzvoFT8FWiHHKhqiYJcCzn6LNX5u3Y5tm_G0ssk,693
+cli/types/profiles.py,sha256=abgoV-XFauYn1BdtzXBPelra5YVXz5MlYcrTs77zp2I,1142
+cli/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cli/utils/async_cmd.py,sha256=kq-A4pccLChOTYBJ-er9PnQgtGBfUoX5R4YLK6mI39g,339
+cli/utils/body.py,sha256=c9kXdbovnD7efivYxMDnPVtgjE5bqvRAB1mVPOYPTF8,1287
+cli/utils/config.py,sha256=Uaaa7eHvxYQatrUMjeF0x04XzD0fp9al82XSd7L_KSQ,2753
+cli/utils/console.py,sha256=vTMOYCq6FEhOeTxrePCHIzg_goyTI25JWFYUIcRYR08,129
+cli/utils/cost_log.py,sha256=tej5nFR1MyKHGBziQEUNR71z001ioW8gx1FM4XFtJSk,3186
+cli/utils/errors.py,sha256=KZ1sjKRmyixIxASG_ZdilD7toFiknwXZmxYutEiRhJI,2062
+cli/utils/options.py,sha256=tvzSxSObkD-7ycg0HlZKsCGzDZ3tpqcy6oTA6HoHaaU,1220
+cli/utils/output.py,sha256=YvqlPu6dwT3VXQtQqYzgFg8xy1dqTHqdZH23ygGy_Xg,3141
+cli/utils/payment.py,sha256=P5SoOuqvwi5U4eEt4QfvKvY1oErvjLxUqNf01jiSVxU,644
+cli/utils/version.py,sha256=pVT9UaRZfREUOA1FwgJGcjYxnjvhNJaKyrNB6B-7uXc,1580
+allium_cli-0.2.0.dist-info/METADATA,sha256=yexBYxaBDAePDv8xDq5_DubQz924-JnAshbvMZCikD8,9562
+allium_cli-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+allium_cli-0.2.0.dist-info/entry_points.txt,sha256=L7gMV98VY361HCDk8oWm0JfSMNmW9Gvoi6R0WNISIZs,41
+allium_cli-0.2.0.dist-info/licenses/LICENSE,sha256=A0_y9c4gKSgfkof9sHKFRbnaT7euA2hl0J1Ucqde5DA,1063
+allium_cli-0.2.0.dist-info/RECORD,,

allium_cli-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

allium_cli-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+allium = cli.main:main

allium_cli-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Allium
+
+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.

cli/auth/api_key.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from cli.types.profiles import ApiKeyProfile
+
+
+def get_headers(profile: ApiKeyProfile) -> dict[str, str]:
+    return {"X-API-Key": profile.api_key}

cli/auth/tempo.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+from mpp import Challenge
+from mpp.client.transport import PaymentTransport
+from mpp.methods.tempo import ChargeIntent, TempoAccount, tempo
+from mpp.methods.tempo._defaults import CHAIN_RPC_URLS
+
+from cli.types.profiles import TempoProfile
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TempoPaymentInfo:
+    """cost details from the most recent 402 challenge."""
+
+    amount: str = "0"
+    currency: str = ""
+    recipient: str = ""
+
+
+class _CostCapturingTransport(httpx.AsyncBaseTransport):
+    """captures payment amounts from 402 challenges during transport."""
+
+    def __init__(self, inner: httpx.AsyncBaseTransport | None = None) -> None:
+        self._inner = inner or httpx.AsyncHTTPTransport()
+        self.last_payment = TempoPaymentInfo()
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        response = await self._inner.handle_async_request(request)
+        if response.status_code == 402:
+            self._capture_challenge(response)
+        return response
+
+    def _capture_challenge(self, response: httpx.Response) -> None:
+        for header in response.headers.get_list("www-authenticate"):
+            if not header.lower().startswith("payment "):
+                continue
+            try:
+                challenge = Challenge.from_www_authenticate(header)
+                req = challenge.request
+                self.last_payment = TempoPaymentInfo(
+                    amount=str(req.get("amount", "0")),
+                    currency=str(req.get("currency", "")),
+                    recipient=str(req.get("recipient", "")),
+                )
+                return
+            except Exception:
+                logger.debug("Failed to parse challenge header", exc_info=True)
+
+    async def aclose(self) -> None:
+        await self._inner.aclose()
+
+
+@dataclass
+class TempoResult:
+    """bundles HTTP response with payment metadata."""
+
+    response: httpx.Response
+    payment: TempoPaymentInfo
+
+
+def _get_tempo_config(profile: TempoProfile) -> tuple[TempoAccount, str, int]:
+    chain_id = int(profile.chain_id)
+    rpc_url = CHAIN_RPC_URLS.get(chain_id)
+    if rpc_url is None:
+        supported = ", ".join(str(cid) for cid in sorted(CHAIN_RPC_URLS))
+        raise ValueError(
+            f"Unsupported Tempo chain ID: {chain_id}. Supported chain IDs: {supported}"
+        )
+    account = TempoAccount.from_key(profile.private_key)
+    return account, rpc_url, chain_id
+
+
+async def tempo_request(
+    profile: TempoProfile,
+    method: str,
+    url: str,
+    **kwargs: Any,
+) -> TempoResult:
+    account, rpc_url, _ = _get_tempo_config(profile)
+    kwargs.setdefault("timeout", 30.0)
+
+    cost_transport = _CostCapturingTransport()
+    payment_transport = PaymentTransport(
+        methods=[
+            tempo(
+                account=account,
+                rpc_url=rpc_url,
+                intents={"charge": ChargeIntent()},
+            )
+        ],
+        inner=cost_transport,
+    )
+
+    async with httpx.AsyncClient(transport=payment_transport) as client:
+        response = await client.request(method, url, **kwargs)
+        return TempoResult(response=response, payment=cost_transport.last_payment)

cli/auth/x402_key.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from eth_account import Account
+from eth_account.messages import encode_typed_data
+
+from cli.types.profiles import X402KeyProfile
+
+
+def make_signer(profile: X402KeyProfile) -> tuple[str, Callable[[dict[str, Any]], str]]:
+    """return (wallet_address, sign_fn) for x402 using a raw private key."""
+    account = Account.from_key(profile.private_key)
+    address: str = account.address
+
+    def sign(typed_data: dict[str, Any]) -> str:
+        domain = typed_data["domain"]
+        msg = typed_data["message"]
+        primary = typed_data.get("primary_type", typed_data.get("primaryType"))
+        types = {k: v for k, v in typed_data["types"].items() if k != "EIP712Domain"}
+        signable = encode_typed_data(
+            primaryType=primary,
+            domain_data=domain,
+            types=types,
+            message=msg,
+        )
+        signed = account.sign_message(signable)
+        return signed.signature.hex()
+
+    return address, sign

cli/auth/x402_privy.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from privy import PrivyAPI
+
+from cli.types.profiles import X402PrivyProfile
+
+
+def make_signer(
+    profile: X402PrivyProfile,
+) -> tuple[str, Callable[[dict[str, Any]], str]]:
+    """return (wallet_address, sign_fn) for x402 using privy wallet RPC."""
+    privy = PrivyAPI(app_id=profile.privy_app_id, app_secret=profile.privy_app_secret)
+    wallet = privy.wallets.get(wallet_id=profile.privy_wallet_id)
+    address: str = wallet.address
+
+    def sign(typed_data: dict[str, Any]) -> str:
+        result = privy.wallets.rpc(
+            wallet_id=profile.privy_wallet_id,
+            method="eth_signTypedData_v4",
+            params={"typed_data": typed_data},
+        )
+        return result.data.signature
+
+    return address, sign

cli/clients/__init__.py

@@ -0,0 +1,4 @@
+from cli.clients.factory import get_client
+from cli.clients.protocol import ClientProtocol
+
+__all__ = ["ClientProtocol", "get_client"]

cli/clients/factory.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from typing import Any
+
+from cli.clients.http import AlliumHTTPClient
+from cli.clients.protocol import ClientProtocol
+from cli.clients.x402 import X402Client
+from cli.constants.config import EXIT_AUTH
+from cli.types.profiles import (
+    ApiKeyProfile,
+    ProfileUnion,
+    TempoProfile,
+    X402KeyProfile,
+    X402PrivyProfile,
+)
+from cli.utils.console import err_console
+
+
+class _X402SignerAdapter:
+    """adapts auth provider to X402Signer protocol."""
+
+    def __init__(
+        self,
+        wallet_address: str,
+        sign_fn: Callable[[dict[str, Any]], str],
+        target_network: str,
+    ) -> None:
+        self._address = wallet_address
+        self._sign_fn = sign_fn
+        self._target_network = target_network
+
+    @property
+    def address(self) -> str:
+        return self._address
+
+    @property
+    def target_network(self) -> str:
+        return self._target_network
+
+    def sign(self, typed_data: dict[str, Any]) -> str:
+        return self._sign_fn(typed_data)
+
+
+def _make_x402_client(
+    base_url: str,
+    make_signer: Callable[..., tuple[str, Callable[[dict[str, Any]], str]]],
+    profile: X402KeyProfile | X402PrivyProfile,
+) -> X402Client:
+    try:
+        address, sign_fn = make_signer(profile)
+    except Exception as exc:
+        err_console.print(f"[red]Failed to initialize wallet signer:[/red] {exc}")
+        sys.exit(EXIT_AUTH)
+    signer = _X402SignerAdapter(address, sign_fn, str(profile.target_network))
+    http = AlliumHTTPClient(base_url=base_url)
+    return X402Client(http, signer)
+
+
+def get_client(profile: ProfileUnion) -> ClientProtocol:
+    """create an authenticated client from a profile."""
+    base_url = profile.base_url
+
+    if isinstance(profile, ApiKeyProfile):
+        from cli.auth.api_key import get_headers
+
+        return AlliumHTTPClient(base_url=base_url, headers=get_headers(profile))
+
+    if isinstance(profile, X402KeyProfile):
+        from cli.auth.x402_key import make_signer
+
+        return _make_x402_client(base_url, make_signer, profile)
+
+    if isinstance(profile, X402PrivyProfile):
+        from cli.auth.x402_privy import make_signer
+
+        return _make_x402_client(base_url, make_signer, profile)
+
+    if isinstance(profile, TempoProfile):
+        from cli.clients.tempo import TempoClient
+
+        try:
+            return TempoClient(profile)
+        except Exception as exc:
+            err_console.print(f"[red]Failed to initialize Tempo client:[/red] {exc}")
+            sys.exit(EXIT_AUTH)
+
+    raise ValueError(f"Unknown profile type: {type(profile)}")