Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
159 changes: 139 additions & 20 deletions .agents/skills/omniclaw-cli/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,31 +14,57 @@ requires:
Scoped agent token tied to your wallet. Set by the owner before your
session starts. Never print, log, or transmit this value. If it is
missing, stop and notify the owner — you cannot proceed without it.
version: 1.0.0
version: 0.0.2
author: Omnuron AI
---

# OmniClaw Agent Skill

## What this skill does
## Installation

OmniClaw is the financial control plane your owner configured before your
session. It lets you:
Install the CLI:

- Pay for HTTP services that return 402 Payment Required (x402 protocol)
- Transfer USDC directly to a wallet address
- Expose your own service behind a payment gate so other agents can pay you
- Check your available balance and transaction history
```bash
pip install omniclaw
```

It does not let you change your own spending limits, add recipients to
whitelists, approve pending payments, or touch any wallet configuration.
Those are owner-only. If you need any of those, stop and notify the owner.
Verify installation:

```bash
omniclaw-cli --version
# or
omniclaw-cli ping
```

---

## Configuration (one-time setup)

Before using any payment commands, you must configure the CLI with your server details:

```bash
omniclaw-cli configure \
--server-url <OMNICLAW_SERVER_URL> \
--token <AGENT_TOKEN> \
--wallet <WALLET_ALIAS>
```

**Where to get these values:**
- `--server-url`: Your OmniClaw server URL (e.g., `https://api.omniclaw.com` or `http://localhost:8080`)
- `--token`: Your scoped agent token (from your owner)
- `--wallet`: Your wallet alias (e.g., `primary`)

**Verify configuration:**

```bash
omniclaw-cli configure --show
```

---

## Before you do anything
## Verify Setup

**Check your environment is ready:**
Before making any payments, always verify your environment is ready:

```bash
omniclaw-cli status
Expand All @@ -47,17 +73,30 @@ omniclaw-cli status
Expected output:
```
Agent: <your-agent-name>
Wallet: wlt_xxxxx
Wallet: 0x...
Balance: $X.XX available
Guards: active
Network: Arc Testnet
Circle: connected ✓
Circuit: CLOSED ✓
Circle: connected ✅
Circuit: CLOSED ✅
```

If `Circuit: OPEN` or `Circle: disconnected`, wait 30 seconds and run
`omniclaw-cli status` again before attempting any payment. If it stays degraded,
notify the owner.
If `Circuit: OPEN` or `Circle: disconnected`, wait 30 seconds and run `omniclaw-cli status` again. If it stays degraded, stop and notify the owner.

---

## What this skill does

OmniClaw is the financial control plane your owner configured before your
session. It lets you:

- Pay for HTTP services that return 402 Payment Required (x402 protocol)
- Transfer USDC directly to a wallet address
- Expose your own service behind a payment gate so other agents can pay you
- Check your available balance and transaction history

It does not let you change your own spending limits, add recipients to
whitelists, approve pending payments, or touch any wallet configuration.
Those are owner-only. If you need any of those, stop and notify the owner.

---

Expand Down Expand Up @@ -182,6 +221,64 @@ before you can pay.

---

## Payment Intents (authorize now, capture later)

For payments you want to authorize first and capture later:

**Create a payment intent (authorize):**
```bash
omniclaw-cli create-intent \
--recipient 0x742d35Cc6634C0532925a3b844Bc9e7595f5e4a0 \
--amount 1.00 \
--purpose "reserved-compute-job"
```

**Confirm (capture) the intent:**
```bash
omniclaw-cli confirm-intent --intent-id <intent-id-from-above>
```

**Get intent status:**
```bash
omniclaw-cli get-intent --intent-id <intent-id>
```

**Cancel an intent:**
```bash
omniclaw-cli cancel-intent --intent-id <intent-id> --reason "no longer needed"
```

---

## Network and Fee Options

**Specify destination chain:**
```bash
omniclaw-cli pay --recipient <address> --destination-chain ethereum
```

**Set gas fee level:**
```bash
omniclaw-cli pay --recipient <address> --fee-level HIGH
```
Options: LOW, MEDIUM, HIGH

**Run Trust Gate check:**
```bash
omniclaw-cli pay --recipient <address> --check-trust
```

---

## Simulate (standalone)

Use `--dry-run` on `pay` or the standalone `simulate` command:
```bash
omniclaw-cli simulate --recipient 0x742d35Cc6634C0532925a3b844Bc9e7595f5e4a0 --amount 0.50
```

---

## How to view your transactions

```bash
Expand Down Expand Up @@ -269,12 +366,21 @@ omniclaw-cli status
# Check available balance
omniclaw-cli balance

# Get your wallet address
omniclaw-cli address

# Health check
omniclaw-cli ping

# Check if you can pay a recipient
omniclaw-cli can-pay --recipient <address-or-url>

# Simulate a payment (no charge)
omniclaw-cli pay --recipient <url-or-address> --dry-run

# Standalone simulation
omniclaw-cli simulate --recipient <address> --amount <n>

# Pay an x402 URL (handles 402 automatically)
omniclaw-cli pay --recipient <url> --idempotency-key <unique-job-key>

Expand All @@ -294,6 +400,19 @@ omniclaw-cli pay --recipient <0xAddress> \
--purpose <description> \
--idempotency-key <unique-job-key>

# Pay with specific chain/fee
omniclaw-cli pay --recipient <address> --destination-chain ethereum --fee-level HIGH

# Payment Intents
omniclaw-cli create-intent --recipient <addr> --amount <n> --purpose <desc>
omniclaw-cli confirm-intent --intent-id <id>
omniclaw-cli get-intent --intent-id <id>
omniclaw-cli cancel-intent --intent-id <id>

# View transactions
omniclaw-cli ledger

# Configure (first time only)
omniclaw-cli configure --server-url <url> --token <token> --wallet <alias>
omniclaw-cli configure --show
```
1 change: 1 addition & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ dependencies = [
"typer>=0.15.0",
"fastapi>=0.100.0",
"uvicorn[standard]>=0.20.0",
"setuptools>=69.0.0",
]

[project.optional-dependencies]
Expand Down
2 changes: 1 addition & 1 deletion src/omniclaw/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,7 @@
)
from omniclaw.trust.gate import TrustGate

__version__ = "0.1.0"
__version__ = "0.0.2"
__all__ = [
# Main Client
"OmniClaw",
Expand Down
2 changes: 1 addition & 1 deletion src/omniclaw/agent/routes.py
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ async def get_current_agent(

@router.get("/health", response_model=HealthResponse)
async def health_check():
return HealthResponse(status="healthy")
return HealthResponse(status="ok")


@router.get("/address", response_model=AddressResponse)
Expand Down
47 changes: 33 additions & 14 deletions src/omniclaw/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,24 @@
from omniclaw.onboarding import print_doctor_status


BANNER = r"""
____ __ __ _ _ ___ ____ _ ___ __
/ __ \| \/ | \ | |_ _/ ___| | / \ \ / /
| | | | |\/| | \| || | | | | / _ \ \ /\ / /
| |__| | | | | |\ || | |___| |___ / ___ \ V V /
\____/|_| |_|_| \_|___\____|_____/_/ \_\_/\_/

OmniClaw is the economy and control layer for AI agent payments.
Economic Execution and Control Layer for Agentic Systems
"""


def print_banner():
"""Print the OmniClaw CLI banner."""
print(f"\033[1;36m{BANNER}\033[0m")
print("\033[90mOmniClaw Financial Infrastructure - v2.0 Production-Ready\033[0m\n")


ENV_VARS = {
"required": {
"CIRCLE_API_KEY": "Circle API key for wallet/payment operations",
Expand Down Expand Up @@ -40,23 +58,23 @@ def print_env_vars():
print("Required:")
for var, desc in ENV_VARS["required"].items():
value = os.environ.get(var, "")
status = f"✓ {value[:20]}..." if value else "✗ not set"
status = f" {value[:20]}..." if value else " not set"
print(f" {var}")
print(f" {desc}")
print(f" {status}\n")

print("\nOptional:")
for var, desc in ENV_VARS["optional"].items():
value = os.environ.get(var, "")
status = f"✓ {value[:30]}..." if value else "○ default"
status = f" {value[:30]}..." if value else " default"
print(f" {var}")
print(f" {desc}")
print(f" {status}\n")

print("\nProduction:")
for var, desc in ENV_VARS["production"].items():
value = os.environ.get(var, "")
status = f"✓ {value[:30]}..." if value else "○ not set"
status = f" {value[:30]}..." if value else " not set"
print(f" {var}")
print(f" {desc}")
print(f" {status}\n")
Expand Down Expand Up @@ -116,21 +134,21 @@ def handle_setup(args: argparse.Namespace) -> int:
api_key = input("Enter your Circle API Key: ").strip()

if not api_key:
print("❌ Error: Circle API Key is required.")
print(" Error: Circle API Key is required.")
return 1

entity_secret = resolve_entity_secret(api_key)
if entity_secret:
print("✅ Found existing Entity Secret in managed store.")
print(" Found existing Entity Secret in managed store.")
else:
print("💡 No Entity Secret found for this API key.")
print("💡 No Entity Secret found for this API key.")
entity_secret = input(
"Enter your 64-char Entity Secret (or press Enter to generate): "
).strip()
if not entity_secret:
from omniclaw.onboarding import auto_setup_entity_secret

print("🚀 Generating and registering new Entity Secret...")
print("🚀 Generating and registering new Entity Secret...")
entity_secret = auto_setup_entity_secret(api_key)

env_path = ".env.agent"
Expand All @@ -150,30 +168,30 @@ def handle_server(args: argparse.Namespace) -> int:
# Load .env.agent if it exists
if os.path.exists(".env.agent"):
load_dotenv(".env.agent")
print("📝 Loaded configuration from .env.agent")
print("📄 Loaded configuration from .env.agent")
elif os.path.exists(".env"):
load_dotenv(".env")
print("📝 Loaded configuration from .env")
print("📄 Loaded configuration from .env")

# Auto-Setup Logic: Check if we have an API key but no Entity Secret
api_key = os.getenv("CIRCLE_API_KEY")
entity_secret = os.getenv("ENTITY_SECRET")

if api_key and not entity_secret:
print("💡 Found API Key but no Entity Secret. Attempting auto-setup...")
print("💡 Found API Key but no Entity Secret. Attempting auto-setup...")
entity_secret = resolve_entity_secret(api_key)
if not entity_secret:
print("🚀 Generating new Entity Secret for this machine...")
print("🚀 Generating new Entity Secret for this machine...")
entity_secret = auto_setup_entity_secret(api_key)

if entity_secret:
os.environ["ENTITY_SECRET"] = entity_secret
print("✅ Credentials verified and injected.")
print(" Credentials verified and injected.")
else:
print("❌ Error: Failed to resolve or generate Entity Secret.")
print(" Error: Failed to resolve or generate Entity Secret.")
return 1

print(f"🚀 Starting OmniClaw Control Plane on {args.host}:{args.port}...")
print(f"🚀 Starting OmniClaw Control Plane on {args.host}:{args.port}...")
uvicorn.run(
"omniclaw.agent.server:app",
host=args.host,
Expand All @@ -188,6 +206,7 @@ def main(argv: Sequence[str] | None = None) -> int:
"""Run the OmniClaw CLI."""
parser = build_parser()
args = parser.parse_args(argv)
print_banner()

if args.command == "doctor":
print_doctor_status(
Expand Down
Loading
Loading