Zerion CLI
[Zerion Wallet]용 CLI입니다. 에이전트 관리형 지갑을 사용하여 EVM 체인과 Solana에서 온체인(on-chain)으로 지갑 분석, 서명(sign), 스왑(swap), 브릿지(bridge) 작업을 모두 커맨드 라인에서 수행할 수 있습니다. 지갑 관리는 [Open Wallet Standard]를 기반으로 구축되었습니다.
[!NOTE]
알파 프리뷰 (Alpha Preview) — 이 CLI는 활발하게 개발 중입니다. 릴리스 간에 명령어, 플래그 및 출력 형식이 예고 없이 변경되거나 제거될 수 있습니다. 운영 워크플로우에서 현재 동작에 의존하지 마십시오.
설치 (Installation)
모든 것을 한 번의 명령어로 설정합니다 (CLI를 전역 설치하고, API 키를 구성하며, 코딩 에이전트에 스킬을 추가합니다):
npx zerion-cli@latest init
- [dashboard.zerion.io]를 통해 브라우저에서 인증하고 키를 자동으로 저장해 줍니다 — 복사/붙여넣기 불필요
- 사용자의 코딩 에이전트(Claude Code, Cursor, Codex, Gemini)를 감지하고 Zerion 스킬을 전역으로 설치합니다
- 프롬프트 건너뛰기를 하려면
-y를 추가하십시오: 브라우저 로그인 후 모든 스킬 설치 과정에서 사용
원격 또는 헤드리스(headless) 호스트의 경우, --no-open을 추가하여 브라우저를 여는 대신 인증 URL을 출력합니다. 터미널이 없는 환경 (CI, 파이프 처리 등)에서는 init이 브라우저 로그인을 기다리는 대신 API 키 지침을 출력하므로, 이 경우 ZERION_API_KEY 환경 변수를 설정하십시오.
또는 설정 없이 CLI만 설치할 수 있습니다:
npm install -g zerion-cli
CLI는 zerion 또는 zerion-cli로 사용할 수 있으며, 둘 다 동일한 바이너리를 실행합니다.
Node.js 22.12 이상 (또는 Node 20의 경우 20.19 이상)이 필요합니다. 이전 버전은 unsupported_node 오류와 함께 종료됩니다.
에이전트 스킬 (Agent skill)
하나의 스킬인 zerion는 ./skills/zerion/에 있으며, [agentskills.io] 오픈 표준을 따릅니다. 모든 기능 및 파트너 통합은 온디맨드(on demand)로 로드되는 중첩된 파일 형태로 존재하므로 (점진적 공개 방식, progressive disclosure), 단 한 번의 설치와 하나의 선택 항목만으로 아래에 있는 모든 것을 노출할 수 있습니다.
기능 (capabilities/skills/zerion/capabilities/)
파일별 기능
| File | 포함 내용 |
|---|
analyze.md | 포트폴리오, 보유 포지션, 거래 내역, 손익(PnL), 토큰 검색, 관심 목록 (읽기 전용; x402 / MPP 지원) |
| ... | |
파트너 통합 (skills/zerion/partners/)
Zerion CLI와 자체 제품을 결합하는 생태계 파트너들입니다. 기여하려면 partner-skill-creator.md를 참조하세요.
zerion CLI를 통한 설치 (권장)
감지된 모든 코딩 에이전트에 전역적으로 설치됩니다. 특정 에이전트에 범위를 지정하려면 --agent <name>을 사용하고, 강제 전역 설치를 하려면 -g를 사용하세요.
Claude Code를 통한 설치
/plugin marketplace add zeriontech/zerion-ai
/plugin install zerion-agent@zerion
Cursor를 통한 설치
Cursor Marketplace에서 zerion-agent를 설치하세요: 사이드바에서 Customize를 열고, Zerion을 찾아 Install을 누른 후 프로젝트 또는 사용자 범위를 선택합니다.
이 플러그인은 zerion 스킬과 호스팅되는 Zerion API 문서 MCP 서버(https://developers.zerion.io/mcp)를 함께 제공하므로, 에디터를 벗어나지 않고도 엔드포인트 참조를 조회할 수 있습니다.
OpenAI Codex CLI를 통한 설치
codex plugin marketplace add zeriontech/zerion-ai
그런 다음 Codex에서 /plugins를 실행하고, zerion 마켓플레이트를 선택한 후 zerion-agent를 설치하세요.
Gemini CLI를 통한 설치
gemini extensions install https://github.com/zeriontech/zerion-ai
agentskills.io를 통한 설치 (20개 이상의 인기 에이전트와 작동)
npx skills add zeriontech/zerion-ai
설치된 에이전트를 자동 감지합니다. 플래그: -g (사용자 전체), -a <agent> (대상 지정 호스트), -y (비대화형). 전체 생태계: https://agentskills.io/clients.
이용 방법
설치 후에는 에이전트에게 자연어로 질문하세요.
지갑 분석 (Wallet analysis)
지갑 vitalik.eth을 분석하세요. 총 포트폴리오 가치, 상위 5개 보유 자산, 최근 거래 내역을 요약해 주세요.
지난 30일 동안 0xFe89Cc7Abb2C4183683Ab71653c4cCd1b9cC194e의 PnL(손익)은 얼마인가요?
기본 지갑에 대한 DeFi 포지션(대출, 스테이킹, LP)을 보여주세요.
거래 (Trading)
Base에서 100 USDC를 ETH로 스왑하세요.
Arbitrum에서 Optimism으로 50 USDC를 브릿지(Bridge)하세요.
Base에서 0.1 ETH를 vitalik.eth로 보내세요.
Base에 있는 제 USDC와 DAI를 ETH로 판매해 주세요. (두 자산 모두 하나의 서명 세션으로 처리)
사용자 검토 (Human review)
bot-1에서 500달러가 넘는 모든 거래에 대해 저에게 물어봐 주세요.
제 Ledger 주소를 콜드(cold)로 추적하고, 거기서 1 ETH를 USDC로 스왑해 주세요. (저는 브라우저에서 서명할 것입니다.)
지갑 관리 (Wallet management)
bot-1이라는 이름의 새로운 암호화된 지갑을 생성해 주세요.
bot-1에 대해 Base에서만 스왑이 허용되고 만료 기간이 7일인 에이전트 토큰을 설정해 주세요.
제 지갑 목록과 활성화된 에이전트 토큰을 보여주세요.
서명 (Signing)
제 bot-1 지갑을 사용하여 typed.json의 EIP-712 메시지에 서명해 주세요.
에이전트는 zerion 스킬을 사용하며, 이 스킬은 작업별로 capabilities/ 또는 partners/ 아래의 적절한 중첩 파일로 라우팅됩니다. 점진적 공개(Progressive disclosure)는 일치하는 기능 문서만 로드됨을 의미하므로 컨텍스트가 깨끗하게 유지됩니다. "지갑 생성, 에이전트 토큰 설정, 스왑" 흐름은 순서대로 capabilities/wallet.md → capabilities/agent-management.md → capabilities/trading.md를 읽습니다.
수동 설정 및 에이전트 실행 (Manual setup, agent execution)
Zerion CLI는 설계상 두 가지 인터페이스로 분리됩니다.
- 지갑 관리 및 에이전트 토큰 설정은 수동으로 수행해야 합니다.
wallet create, import, backup, export-key, 그리고 delete 명령어는 모두 암호 구문(passphrase)을 요청합니다. wallet sync는 Zerion 앱으로 스캔할 수 있는 QR 코드를 생성합니다. agent create-token은 특정 지갑에 바인딩된 범위가 지정된 거래 자격 증명(scoped trading credential)을 발행하며, agent create-policy는 이 토큰이 준수해야 할 규칙들—허용되는 체인, 만료일, 전송/승인 게이트, 컨트랙트 허용 목록—을 연결합니다. 형제 관리 명령어(agent list-tokens, use-token, revoke-token, list-policies, show-policy, delete-policy) 역시 사용자가 직접 수행하는 작업입니다. 키 자료가 이동하거나 지출 자격 증명이 확대될 때도 반드시 사용자 개입이 필요합니다. CI 및 헤드리스 서버의 경우, agent create-token은 --passphrase-file <path>를 허용하여(파일은 mode 0600이어야 함) 대화형 TTY 없이 토큰 발급을 스크립트할 수 있습니다—자세한 내용은 capabilities/agent-management.md를 참조하십시오.
- 분석, 서명, 거래 및 검색은 에이전트를 위한 것입니다.
analyze, portfolio, positions, history, pnl, sign-message, sign-typed-data, swap, bridge, send, swap tokens, search, chains, wallet list, wallet fund, 그리고 watch list 명령어들은 JSON을 stdout으로, 구조화된 오류를 stderr로 출력하며 확인 대화 상자를 건너뜁니다. 에이전트 토큰이 설정되면 서명 및 거래는 즉시 실행됩니다—토큰은 암호 구문 요청 없이 지갑을 대신하여 작업을 승인합니다.
- 지갑별로 사용자 개입을 다시 할 수 있습니다. 비대면 서명(Unattended signing)이 기본값일 뿐, 유일한 모드는 아닙니다. 읽기 전용 지갑(key가 없는 주소만 있는
wallet add) 또는 검토 임계값(review threshold, wallet set-review-threshold)은 영향을 받는 트랜잭션을 자동 서명하는 대신 Zerion 웹 앱으로 보내 사람이 브라우저에서 검토하고 서명하도록 합니다. 에이전트 정책(Agent policies)은 토큰이 절대 할 수 없는 것을 명시하며; 검토 임계값은 사용자에게 무엇에 대해 질문할지 결정합니다. 서명 경로를 참조하십시오.
설정 작업(Setup gestures)(init, setup skills, config set/unset/list, watch add/remove)은 자동화가 작동하기 전에 사용자가 직접 실행하는 일회성 구성 단계입니다.
핵심은 '분리(split)'입니다. 사용자가 수동으로 한 번 스테이징합니다—지갑을 생성하거나 가져오고, 암호를 설정하고, 에이전트 토큰을 민팅하며, 정책을 첨부하는 식입니다. 그런 다음 이 에이전트 토큰을 해당 정책이 허용하는 작업만 수행할 수 있는 자동화 시스템에 전달합니다. 에이전트 토큰은 지출 권한을 가진 API 키처럼 취급해야 하며, agent policies를 사용하여 특정 체인(chains), 주소(addresses) 또는 만료 기간(expiry windows)으로 범위를 제한하세요.
인증 (Authentication)
세 가지 옵션이 있습니다. CLI가 어떤 것이 활성화되었는지 자동으로 감지합니다.
A) API 키 (권장)
dashboard.zerion.io에서 키를 받으세요—무료이며 몇 분이면 됩니다. 키는 zk_로 시작합니다.
가장 빠른 방법은 브라우저 로그인입니다—claude나 gh auth login처럼, 대시보드가 열리고 사용자가 승인하면 로컬 루프백 리디렉션을 통해 키가 캡처되어 설정에 저장됩니다. 이 키는 절대 사용자 기기를 벗어나지 않습니다.
zerion login
zerion login --browser
또는 수동으로 키를 설정/유지합니다:
export ZERION_API_KEY="zk_..."
zerion config set apiKey zk_...
- HTTP Basic Auth
- 분석 및 거래 명령에 필요합니다 (분석은 x402 / MPP 종량제 호출 방식도 사용할 수 있습니다—옵션 B와 C 참조)
B) x402 종량제 호출 (x402 pay-per-call)
API 키가 필요 없습니다. x402 프로토콜을 통해 요청당 0.01 USDC를 지불합니다. EVM (Base) 및 Solana를 지원합니다.
종량제 호출 방식은 분석 명령에만 적용됩니다 (portfolio, positions, history, pnl, analyze). 거래 명령은 항상 API 키를 사용합니다.
export WALLET_PRIVATE_KEY="0x..."
export WALLET_PRIVATE_KEY="5C1y..."
...
두 체인 동시 사용:
export EVM_PRIVATE_KEY="0x..."
export SOLANA_PRIVATE_KEY="5C1y..."
export ZERION_X402_PREFER_SOLANA=true # 선택 사항, 둘 다 설정된 경우 Solana를 선호함
C) MPP pay-per-call
API 키 불필요. MPP 프로토콜을 통해 Tempo(https://tempo.xyz)에서 요청당 0.01 USDC를 지불합니다. EVM 전용입니다.
export WALLET_PRIVATE_KEY="0x..."
export TEMPO_PRIVATE_KEY="0x..."
...
명령어 (Commands)
모든 명령어는 전체 플래그 문서를 위해 --help를 지원합니다. 최상위 명령어 목록은 zerion --help를 실행하세요.
지갑 분석 (Wallet Analysis)
읽기 전용(Read-only)입니다. pay-per-call을 위해 --x402 및 --mpp를 지원합니다.
| 명령어 | 설명 | 예시 |
|---|
| `zerion analyze <address | ens>` | 포트폴리오, 포지션, 거래 내역, PnL(손익)을 병렬로 분석하는 전체 분석 기능 |
| ... | | |
거래 (Trading)
API 키(또는 무인 사용을 위한 에이전트 토큰)가 필요합니다.
| 명령어 | 설명 | 예시 |
|---|
zerion swap <chain> <amount> <from-token> <to-token> | 같은 체인 내 스왑 (Same-chain swap) | zerion swap base 1 USDC ETH |
| ... | | |
서명 경로 — 로컬 서명 대 웹 앱 핸드오프
모든 거래(및 모든 메시지 서명)는 다음 두 가지 경로 중 하나를 거치며, 이는 무언가에 서명되기 전에 자동으로 결정됩니다:
- 로컬 서명 (Local signing) (기본값) — CLI가 에이전트 토큰을 암호 구문(passphrase)으로 사용하여 서명하고 브로드캐스트합니다. 한 번의 시도로, 무인 환경에서 작동합니다.
- 웹 앱 핸드오프 (Web-app handoff) — CLI가 거래를
app.zerion.io 링크로 인코딩하고 브라우저를 열어 사용자가 직접 서명할 때까지 **대기(blocks)**하며, 이 과정이 완료될 때까지 프로그램 실행을 멈춥니다 (기본값 300초, --timeout으로 변경 가능). 해당 URL은 또한 표준 에러(stderr)로 출력되므로, 헤드리스/에이전트 환경에서 사용자에게 전달할 수 있습니다. 로컬에서는 아무것도 서명되지 않으며, 에이전트 토큰도 필요하지 않습니다.
핸드오프는 다음 트리거 중 하나가 발생하면 작동합니다:
| Trigger | Set by |
|---|
| Read-only wallet (no key material) | zerion wallet add <address|ens> --name <name> |
| ... | |
메시지는 USD 가치가 없으므로, sign-message / sign-typed-data는 임계값을 무시합니다. 이 경우 읽기 전용(read-only) 및 --review 트리거만 적용됩니다. | |
두 경로 모두 동일한 사전 검증(pre-flight: 잔액 게이트, 블로킹 쿼트 확인, 에이전트 정책 등)을 실행하며, 모든 거래는 stderr에 Signing route: <route> — <reason>를 출력하고 JSON 출력물에는 signedVia: "local" | "web-app"을 포함합니다. 임계값이 설정되었으나 해당 값을 가격 책정할 수 없는 경우, 거래는 검토(review)를 위해 폐쇄적으로 실패합니다(fails closed). 핸드오프는 completed / rejected / failed / timeout (또는 Ctrl-C 시 aborted)로 종료되며, 이는 동일한 JSON의 status로 보고됩니다. 오직 completed만이 0을 반환합니다.
임계값은 트랜잭션별 상한선입니다. 따라서 consolidate --execute는 항상 로컬(local)에서 실행됩니다. 스윕(sweep)은 N개의 독립적인 트랜잭션이며, 각각의 행이 임계값 미만이라도 검토에 통합되지 않습니다 (또한 키 자료가 필요하므로 읽기 전용 지갑에서는 실행할 수 없습니다). 전체 스윕을 하나의 개체로 판단하고 서명하려면 다음 명령어를 사용해야 합니다: zerion bundle --group "$(zerion consolidate <chain> <token> --prepare)". 전체 참조: capabilities/trading.md 및 capabilities/bundle.md.