# npm
npm install @helix-protocol/sdk

# yarn
yarn add @helix-protocol/sdk

# pnpm
pnpm add @helix-protocol/sdk

import { HelixClient, RiskProfile } from '@helix-protocol/sdk';

// 1. Create client
const helix = new HelixClient({
  chainId: 8453,                              // Base Mainnet
  rpcUrl:  'https://mainnet.base.org',
  apiKey:  process.env.HELIX_API_KEY,          // get at helix.finance/dashboard
});

// 2. Connect wallet (any EIP-1193 provider)
await helix.connect(window.ethereum);

// 3. Set risk profile
await helix.setRiskProfile({
  type:               RiskProfile.MODERATE,
  maxSlippage:        0.5,    // 0.5%
  maxPositions:       10,
  rebalanceThreshold: 2.0,    // rebalance when drift exceeds 2%
  protocols: ['aerodrome', 'moonwell', 'seamless', 'aave'],
});

// 4. Start the AI agent
const agent = await helix.startAgent();
console.log('Agent started:', agent.id);
console.log('Model:', agent.modelVersion);  // 'v2.3.1-beta'

agent.on('opportunity:found', (opp) => {
  console.log(`Found: ${opp.protocol} | score=${opp.score} | APY~${opp.estimatedApy}%`);
});

agent.on('position:opened', (pos) => {
  console.log(`Position #${pos.id} opened in ${pos.protocol}`);
  console.log(`TX: ${pos.txHash}`);
});

agent.on('rebalance', (evt) => {
  console.log(`Rebalanced: ${evt.reason} | delta=${evt.delta}%`);
});

agent.on('warning', (w) => console.warn(`[${w.code}] ${w.message}`));

score(P, S) = w₁·RA_yield(P,S) + w₂·Liquidity_depth(P)
            + w₃·Protocol_health(P) - w₄·Risk_penalty(S)

where:
  RA_yield        = risk-adjusted annualized yield (Sharpe-normalized)
  Liquidity_depth = log-normalized pool TVL score
  Protocol_health = smart contract risk score (audit grade × age factor)
  Risk_penalty    = volatility × max_drawdown × correlation_to_portfolio

  weights [w₁=0.38, w₂=0.22, w₃=0.24, w₄=0.16] — learnable, retrained per cycle

enum RiskProfile {
  CONSERVATIVE = 0,   // Stable LPs + Lending only. Max slippage 0.2%.
  MODERATE     = 1,   // All strategies. Max slippage 0.5%.
  AGGRESSIVE   = 2,   // All strategies incl. volatile LPs. Max slippage 1.0%.
}

interface RiskProfileConfig {
  type:               RiskProfile;
  maxSlippage:        number;        // % (e.g. 0.5 for 0.5%)
  maxPositions:       number;        // max concurrent open positions
  rebalanceThreshold: number;        // drift % to trigger rebalance
  minPositionSize:    number;        // minimum USDC equivalent
  protocols?:         string[];      // protocol whitelist (empty = all)
  stopLoss?:          number;        // optional % drawdown auto-close
}

npm install @helix-protocol/sdk viem

const helix = new HelixClient({
  chainId:     8453,                         // required — Base Mainnet
  rpcUrl:      'https://mainnet.base.org',   // required
  apiKey:      'hlx_live_...',               // required — from dashboard
  nodeUrl?:    'https://node.helix.finance', // optional — inference node
  timeout?:    30_000,                        // optional — ms, default 30s
  logLevel?:   'info' | 'debug' | 'silent', // optional
});

// Option A — Browser wallet (MetaMask, Coinbase, Rainbow…)
await helix.connect(window.ethereum);

// Option B — viem WalletClient
import { createWalletClient, custom } from 'viem';
import { base } from 'viem/chains';
const walletClient = createWalletClient({ chain: base, transport: custom(window.ethereum) });
await helix.connect({ walletClient });

// Option C — Private key (server-side only, never in browser)
await helix.connect({ privateKey: process.env.WALLET_PRIVATE_KEY });

// Option D — Read-only mode (no signing)
await helix.connect({ address: '0x...', readOnly: true });

const agent = await helix.startAgent({
  capital:     1000,           // USDC equivalent to deploy
  autoApprove: true,          // auto-sign position TXs
  simulate:    false,         // set true for dry-run mode
  gasBuffer:   1.25,          // 25% gas headroom
});

console.log(agent.id);            // 'agent_0x1234...abcd_1716213045'
console.log(agent.modelVersion);  // 'v2.3.1-beta'
console.log(agent.status);        // 'running'

// Pause (keeps positions open, stops new actions)
await agent.pause();

// Resume after pause
await agent.resume();

// Stop and close all positions
await agent.stop({ closeAll: true });

// Stop and leave positions open
await agent.stop({ closeAll: false });

// Get live agent stats
const stats = await agent.getStats();
// { uptime, totalTx, openPositions, closedPositions, totalPnl, winRate }

// Get all positions for connected wallet
const positions = await helix.getPositions();
// Returns: Position[]

// Get portfolio summary
const portfolio = await helix.getPortfolio();
console.log(portfolio.totalValueUsd);  // 4218.54
console.log(portfolio.pnl24h);         // +2.14%
console.log(portfolio.positions);      // Position[]

// Open a position manually
const pos = await helix.openPosition({
  protocol:  'aerodrome',
  strategy:  'stable-lp',
  pair:      'USDC/USDbC',
  amount:    '500',        // USDC string
  slippage:  0.3,
});
console.log(pos.txHash);  // '0x...'

// Close a position
await helix.closePosition(positionId);

// Get specific position value
const val = await helix.getPositionValue(positionId);
console.log(val.usd);       // current USD value
console.log(val.pnlPct);    // PnL since open (%)

npm install @helix-protocol/react wagmi viem @tanstack/react-query

import { WagmiProvider, createConfig } from 'wagmi';
import { base } from 'wagmi/chains';
import { HelixProvider } from '@helix-protocol/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const wagmiConfig = createConfig({ chains: [base], connectors: [...] });
const queryClient = new QueryClient();

export function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <WagmiProvider config={wagmiConfig}>
        <HelixProvider apiKey={process.env.NEXT_PUBLIC_HELIX_KEY}>
          <YourApp />
        </HelixProvider>
      </WagmiProvider>
    </QueryClientProvider>
  );
}

import { useHelix } from '@helix-protocol/react';
import { useAccount, useWalletClient } from 'wagmi';

export function HelixDashboard() {
  const { address } = useAccount();
  const { data: walletClient } = useWalletClient();
  const { agent, portfolio, status, startAgent, stopAgent } = useHelix({ walletClient });

  if (!address) return <button onClick={connect}>Connect Wallet</button>;

  return (
    <div>
      <p>Status: {status}</p>                    // 'idle' | 'running' | 'paused'
      <p>Portfolio: ${portfolio?.totalValueUsd}</p>
      <p>24h PnL: {portfolio?.pnl24h}%</p>
      <button onClick={startAgent}>Start AI Agent</button>
      {portfolio?.positions.map(pos => (
        <div key={pos.id}>{pos.protocol}: ${pos.valueUsd.toFixed(2)}</div>
      ))}
    </div>
  );
}

curl https://api.helix.finance/v1/opportunities \
  -H "Authorization: Bearer hlx_live_xxxxxxxxxxxx"

{
  "opportunities": [
    {
      "id":           "opp_aerodrome_stable-lp_usdc_20250115",
      "protocol":     "aerodrome",
      "strategy":     "stable-lp",
      "pair":         "USDC/USDbC",
      "score":        88.4,
      "estimatedApy": 12.3,
      "tvl":          45200000,
      "risk":         "low",
      "confidence":   0.94
    }
  ],
  "blockNumber": 24847932,
  "timestamp":   "2025-01-15T10:30:00Z"
}

curl -X POST https://api.helix.finance/v1/positions \
  -H "Authorization: Bearer hlx_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "opportunityId": "opp_aerodrome_stable-lp_usdc_20250115",
    "amount":        "1000",
    "token":         "USDC",
    "slippage":      0.5,
    "walletAddress": "0x..."
  }'

const ws = new WebSocket('wss://ws.helix.finance/v1/stream?key=hlx_live_xxx');

ws.onmessage = ({ data }) => {
  const msg = JSON.parse(data);
  if (msg.type === 'opportunity') console.log('New opp:', msg.payload);
  if (msg.type === 'block')       console.log('Block:',   msg.blockNumber);
};

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IHelixRouter {

    struct DepositParams {
        address  token;
        uint256  amount;
        uint8    riskProfile;    // 0=conservative 1=moderate 2=aggressive
        uint16   maxSlippage;    // basis points (50 = 0.5%)
        bytes32  strategyId;     // keccak256 of strategy identifier
    }

    event PositionOpened(
        uint256 indexed positionId,
        address indexed user,
        address         token,
        uint256         amount,
        bytes32         strategyId
    );

    event PositionClosed(
        uint256 indexed positionId,
        address indexed user,
        uint256         returned,
        int256          pnl
    );

    function deposit(DepositParams calldata params)
        external returns (uint256 positionId);

    function withdraw(uint256 positionId, uint256 amount)
        external returns (uint256 received);

    function rebalance(uint256[] calldata positionIds) external;

    function getPositionValue(uint256 positionId)
        external view returns (uint256 value);

    function getActivePositions(address user)
        external view returns (uint256[] memory);
}

const gov = helix.governance();

// Get active proposals
const proposals = await gov.getProposals({ state: 'active' });

// Vote on a proposal (requires veHLX balance)
await gov.castVote({
  proposalId: 7,
  support:    true,   // true=for, false=against, null=abstain
  reason:     'Aerodrome integration increases yield diversity',
});

// Lock HLX for voting power
await gov.lock({
  amount:      '10000',     // HLX tokens
  durationDays: 365,        // 1 year lock = 1x voting power
});

// Submit a proposal (requires 100k veHLX)
await gov.propose({
  title:       'Add Beefy Finance integration',
  description: 'Integrate Beefy auto-compound vaults as a yield source...',
  calldata:    encodedCalldata,   // on-chain execution payload
});