# ⚡ 5-Minute Developer Guide: Add Julie Security to Your Trading Bot

Protect your automated trading bot, sniper, or AI agent from honeypots, malicious fee traps, unverified proxies, and liquidity drains across 35 EVM chains.

---

### Quickest Start: 3-Line Honeypot Check (Python)

```python
from julie_guard import JulieGuard

guard = JulieGuard(auto_pass="starter")  # Auto-activates $1.00 session pass (125 scans) on quota limit
is_safe, details = guard.audit("base", "0xTokenAddress")
if not is_safe:
    print(f"Rugpull/Honeypot detected! Risks: {details.get('risks')}. Trade cancelled.")
```

> **Free Health-Check**: Ping `GET https://julie.freysa.dev/api/status` anytime for 100% free uptime monitoring without consuming audit quota.  
> **1-Click Auto-Pass**: Use `auto_pass="starter"` or append `?auto_pass=starter` to auto-activate a 125-scan pass ($1.00 Base USDC) in a single request.

---

### Step 1: Recommended Integration Flow
To conserve quota and optimize execution latency:
1. **Health Check**: `GET https://julie.freysa.dev/api/status` (Free, 0 quota consumed)
2. **Pre-Trade Audit**: `GET https://julie.freysa.dev/api/audit?contract=0x...&chain=base` (5 free trial scans, then $0.01 Base USDC via x402)
3. **Fastest Path for Simple Bots (1-Click Fallback)**:
   - When free quota is reached, append `?auto_pass=starter` to audit URL.
   - Activates 125-scan pass ($1.00 Base USDC) + returns audit in the same request.
   - Reuse returned `X-Session-Key` on future calls for 0.5ms zero-latency scans.
4. **Pre-Funded High-Speed Session Pass**: `POST https://julie.freysa.dev/api/session/create` ($1.00 for 125 scans or $5.00 for 750 scans) for sub-millisecond priority execution without per-trade signing.

---

### Step 2: Instant Integration (Python)

```python
# pip install requests eth-account web3
from julie_guard import JulieGuard

# Option A: Zero config (uses 5 free trial scans)
guard = JulieGuard()

# Option B: High-frequency sniper (pre-funded session pass for zero latency)
# guard = JulieGuard(session_key="your_session_key")

# Option C: Autonomous on-chain wallet (auto-signs $0.01 x402 permits on Base)
# guard = JulieGuard(private_key="0xYOUR_BASE_WALLET_PRIVATE_KEY")

# Check before swapping on Uniswap / Aerodrome
report = guard.audit(target_token_address, chain="base")

if report.get("verdict") == "SAFE":
    print("Contract is safe! Executing buy...")
    execute_swap(target_token_address)
else:
    print(f"ABORT TRADE: {report.get('verdict')} - {report.get('plain_english_summary')}")
```

---

### Step 3: Instant Integration (Node.js / TypeScript)

```javascript
// npm install ethers axios
const { JulieGuard } = require('./julie_guard.js');

const guard = new JulieGuard({
  privateKey: process.env.BASE_WALLET_KEY // optional for auto-402 payment
});

async function safeSwap(tokenAddress) {
  const audit = await guard.audit(tokenAddress, 'base');
  
  if (audit.verdict === 'SAFE') {
    console.log('Contract verified. Proceeding with trade.');
    await buyToken(tokenAddress);
  } else {
    console.warn(`Blocked trade! Verdict: ${audit.verdict}`);
  }
}
```

---

### Step 3.5: 5-Line Production-Ready Trading Loop (with 1-Click Fallback)

```python
import os, requests
SESSION = os.getenv("JULIE_SESSION_KEY", "")
def preflight_audit(token, chain="base"):
    global SESSION
    r = requests.get(f"https://julie.freysa.dev/api/audit?contract={token}&chain={chain}&auto_pass=starter&payer={os.getenv('MY_WALLET')}", headers={"X-Session-Key": SESSION} if SESSION else {})
    SESSION = r.headers.get("X-Session-Key", SESSION)
    return r.json().get("verdict") == "SAFE"

# In production loop:
# if preflight_audit("0xToken..."): execute_swap("0xToken...")
```

---

### Step 4: Direct cURL & Cast CLI (Zero Dependencies)

```bash
# 1. Free Health Check
curl -s https://julie.freysa.dev/api/status

# 2. Audit a Token (Free demo or 1-Click Session Pass in a single request)
curl -s "https://julie.freysa.dev/api/audit?contract=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&auto_pass=starter&payer=0xYOUR_WALLET"

# 3. Direct On-Chain Transfer (Foundry cast send):
# Starter Pass ($1.00 USDC for 125 priority scans):
cast send 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 "transfer(address,uint256)" 0x75F05Da87cDFf3f6bAcAc3C07CD49F1D7dC7b20C 1000000 --rpc-url https://mainnet.base.org --private-key $YOUR_KEY

# Pro Sniper Pass ($5.00 USDC for 750 priority scans):
cast send 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 "transfer(address,uint256)" 0x75F05Da87cDFf3f6bAcAc3C07CD49F1D7dC7b20C 5000000 --rpc-url https://mainnet.base.org --private-key $YOUR_KEY

# 4. Instant Unlock with Tx Hash:
curl -H "X-Payment-Tx: <TX_HASH_FROM_CAST>" "https://julie.freysa.dev/api/audit?contract=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
```

---

### Step 4.5: Fastest Way to Test a Paid Scan Right Now (3 Steps)

1. **Send 1 USDC with Foundry `cast`:**
   ```bash
   cast send 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 "transfer(address,uint256)" 0x75F05Da87cDFf3f6bAcAc3C07CD49F1D7dC7b20C 1000000 --rpc-url https://mainnet.base.org --private-key $YOUR_KEY
   ```
2. **Execute scan with returned transaction hash:**
   ```bash
   curl -i -H "X-Payment-Tx: <TX_HASH>" "https://julie.freysa.dev/api/audit?contract=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
   ```
3. **Save and reuse the returned `X-Session-Key` header:**
   ```bash
   # Future scans run with 0.5ms latency — no further payment needed for 125 scans!
   curl -H "X-Session-Key: <RETURNED_SESSION_KEY>" "https://julie.freysa.dev/api/audit?contract=0x..."
   ```

---

### Endpoints & Machine Discovery
- **OpenAPI 3.1 Spec**: `https://julie.freysa.dev/openapi.json`
- **MCP Endpoint**: `https://julie.freysa.dev/mcp`
- **Agent Card**: `https://julie.freysa.dev/.well-known/agent.json`
- **Machine Instructions**: `https://julie.freysa.dev/agents.txt` & `https://julie.freysa.dev/llms.txt`
- **Direct Settlement Vault**: `0x75F05Da87cDFf3f6bAcAc3C07CD49F1D7dC7b20C` (Base Mainnet Native USDC)