온체인 에이전트 구축 방법: 지갑, 결제, 실시간 데이터

마지막 업데이트: 2026년 5월 27일8분 읽기

대부분의 "AI 에이전트" 튜토리얼은 LLM에서 멈춘다. 어려운 부분은 에이전트가 지갑을 필요로 하고, 호출하는 서비스에 대한 비용을 지불할 방법이 필요하고, 자신이 작동 중인 체인에 대한 실시간 뷰가 필요할 때부터 시작된다.

온체인 에이전트를 구축하려면 에이전트에게 세 가지 프리미티브를 주어야 한다: 서명을 위한 범위가 제한된 지갑, x402 같은 결제 레일, 그리고 webhooks, WebSockets, gRPC를 통한 실시간 데이터 피드다. 모델은 결정을 내리고, 이 프리미티브들은 온체인에서 행동할 수 있게 해준다.

코드를 작성하는 LLM은 코파일럿이다. 돈을 보유하고, 트랜잭션에 서명하고, 온체인 이벤트에 실시간으로 반응하는 에이전트는 다른 존재다: 경제의 참여자다. 이를 위한 인프라는 존재하지만, 지갑, 결제, 실시간 데이터 프리미티브에 흩어져 있다. 이 가이드는 실제로 필요한 세 가지를 살펴보고 이를 연결하는 방법을 다룬다. Alchemy CLI와 우리의 agentic 제품들은 각각을 직접 사용할 수 있는 프리미티브로 제공한다.

온체인 에이전트를 구축하는 것은 무엇이 다른가?

일반적인 AI 에이전트 스택의 대부분은 온체인에서도 그대로 작동한다: 모델, 프레임워크, 툴 콜링 패턴, 오케스트레이션 루프, 평가 하네스, 프롬프트 저장소. 이 모든 것이 그대로 이어진다. Slack 봇, 코딩 에이전트, 리서치 에이전트를 만들어봤다면 스택의 상위 절반은 이미 익숙할 것이다.

세 가지는 그대로 이어지지 않는다: 지갑, 결제 레일, 실시간 데이터 피드다. 이 세 가지 모두 LLM 툴링 세계에 깔끔한 대응물이 없고, 더 똑똑한 모델을 선택한다고 해결되지 않으며, 이 중 하나라도 잘못 처리하면 지갑이 비거나 프로덕션에서 에이전트가 멈추는 종류의 실수가 된다.

아이덴티티는 이메일 주소가 아니라 프라이빗 키다. 에이전트가 서명할 수 있는 것은 무엇이든 지출할 수 있다. 키 관리는 설정 파일이 아니라 보안 모델이 된다.
결제는 프로토콜 계층에서 일어난다. Stripe는 "저는 에이전트입니다"를 결제자로 받아주지 않는다. 크립토 레일은 HTTP 402/x402 같은 표준을 통해 받아준다.
실시간 데이터는 기본 모드이지, 기능이 아니다. 블록 타임은 짧고 파이널리티가 중요하다. 폴링은 예산을 소모하며, 에이전트는 체인이 상태를 자신에게 푸시해주어야 한다.

아래의 세 가지 빌딩 블록 각각은 이러한 변화 중 하나에 대응한다.

온체인 에이전트의 세 가지 빌딩 블록은 무엇인가?

프로덕션 온체인 에이전트에는 보통 세 가지가 필요하다:

지갑. 에이전트가 이것으로 서명할 수 있으며, 탈취된 프롬프트가 자금을 빼가지 못하도록 범위가 제한되어 있다.
결제 레일. 에이전트가 사람 개입 없이 오프체인 API와 온체인 가스 비용을 지불한다.
실시간 데이터 파이프. 에이전트가 새 블록, 트랜잭션, 컨트랙트 이벤트가 발생하는 즉시 반응한다.

이 가이드의 나머지 부분은 각 빌딩 블록에 대한 섹션과, 마지막으로 이들을 모두 결합하는 워크스루로 구성된다.

키를 유출하지 않고 에이전트에게 지갑을 주려면 어떻게 해야 하는가?

가장 순진한 패턴은 누구나 처음 시도하는 방식이다: 프라이빗 키를 .env 파일에 넣고, dotenv로 불러와서, 에이전트 루프 내부에서 그것으로 트랜잭션에 서명한다. 로컬 데모에서는 작동한다. 하지만 프로덕션에서는 프롬프트 인젝션 한 번이면 지갑이 비게 된다.

더 안전한 기본값으로 두 가지 패턴이 떠오르고 있다.

첫 번째 패턴은 위임된 서명을 사용하는 임베디드 스마트 계정(원시 프라이빗 키 계정이 아니라 프로그래머블 지갑 컨트랙트)이다. 키는 커스터디 서비스(Privy, Turnkey, 다자간 계산을 위한 Coinbase MPC) 내부에 존재한다. 에이전트는 이를 절대 보지 못한다. 서명 API를 호출하면, 서비스가 정책에 따라 요청을 검증하고 서명된 트랜잭션을 반환한다. 에이전트는 당신이 설정한 규칙(트랜잭션당 최대 금액, 허용된 컨트랙트, 일일 한도) 내에서만 서명할 수 있다.

두 번째 패턴은 개발자 인터페이스에서 승인되는 세션 범위 지갑이다. 에이전트는 특정 지갑에 바인딩된, 시간 제한이 있고 취소 가능한 세션을 받는다. 세션은 당신이 제어하는 UI에서 승인한다. 취소는 클릭 한 번이면 된다.

패턴 2에 대한 최신 구현은 Alchemy CLI의 agent wallet 기능으로, CLI 자체의 일부로 제공된다:

bashCopied
# Install the latest Alchemy CLI
npm i -g @alchemy/cli@latest
# Authenticate your CLI session
alchemy auth
# Connect the wallet your agent will use
alchemy wallet connect

alchemy wallet connect는 브라우저에서 대시보드를 연다. 에이전트가 사용할 지갑을 선택하고 세션을 승인하면, 그 시점부터 CLI가 에이전트를 대신해 서명할 수 있다. 프라이빗 키는 Privy에 남아 있다. 모든 서명 호출은 2단계 흐름을 거친다: 우리 백엔드가 페이로드를 구성하고, CLI가 로컬에서 서명하고, 요청이 Privy에 도달한다. 세션이 만료되었거나, 취소되었거나, 바인딩 검사에 실패하면 요청은 우리 인프라를 벗어나기 전에 거부된다.

CLI는 사람뿐 아니라 에이전트를 위한 툴 인터페이스로 설계되었다. 다음 명령어들이 중요하다:

bashCopied
# Run any command with structured output and no prompts
alchemy <command> --json --no-interactive
# Print the JSON manifest of every command and flag
alchemy --json --no-interactive agent-prompt
# Install Alchemy Skills for agent clients
npx skills add alchemyplatform/skills --yes

alchemy --json --no-interactive agent-prompt이 이를 에이전트 네이티브로 만드는 부분이다. LLM에게 CLI 인터페이스를 암기하라고 요구하는 대신, 세션 시작 시 JSON 매니페스트를 제공하면 모델이 전체 명령어 공간, 에러 코드, 예시 호출을 알게 된다. 이는 "에이전트가 존재하지 않는 플래그를 환각으로 만들어낸" 종류의 실패를 통째로 제거한다. 라이브 체인 데이터 툴을 위해서는 hosted MCP server를 별도로 연결한다.

두 패턴 중 선택하는 방법:

Pattern	Best for	Trade-off
Embedded smart account with delegated signing	Production agents acting on behalf of end users (consumer apps, agent commerce)	More setup, but per-user isolation and granular policy
Session-scoped CLI wallet	Single-developer agents, automation, internal tools, prototypes	Faster to wire up, scoped per session, revocable from one dashboard

어느 쪽을 선택하든 규칙은 같다: 에이전트는 원시 프라이빗 키를 절대 보지 않는다. 설계상 메모리에 프라이빗 키가 존재한다면, 그것은 에이전트가 아니라 취약점을 만든 것이다.

에이전트는 자신이 호출하는 서비스에 대한 비용을 어떻게 지불하는가?

에이전트가 지갑을 갖게 되어도 여전히 무언가에 대한 비용을 지불해야 한다. 두 종류의 비용이 있다:

온체인 비용. 가스, 스왑 수수료, 브리지 수수료 등 체인이 상태 변경에 부과하는 모든 것.
오프체인 비용. RPC 요청, 인덱싱된 데이터 API, 추론 등 에이전트가 서버로부터 필요로 하는 모든 것.

온체인 비용은 가스 스폰서십으로 해결된다. 많은 계정 추상화 제공업체가 paymaster API를 제공하는데, paymaster는 다른 누군가를 대신해 가스를 지불하는 컨트랙트다. 에이전트가 유저 오퍼레이션(스마트 계정을 위한 ERC-4337의 트랜잭션 대응물)을 제출하면, paymaster가 이를 커버하고, 사용량은 당신 쪽에서 정산한다. 이 패턴은 이미 스마트 계정 시스템에서 흔하다.

오프체인 비용은 더 어려운 문제인데, 에이전트에게 등록된 신용카드가 없고 모든 에이전트에게 API 키를 프로비저닝하고 싶지도 않기 때문이다. 생태계 전반에서 수렴하고 있는 패턴이 x402다: HTTP 402 Payment Required 상태 코드에, 에이전트에게 결제 방법을 알려주는 작은 페이로드를 더한 것이다.

전체 흐름은 다음과 같다:

에이전트가 서비스에 HTTP 요청을 보낸다.
서비스가 가격, 허용 토큰, 체인을 설명하는 JSON 본문과 함께 402 Payment Required로 응답한다.
에이전트가 결제(Base 위의 USDC가 일반적인 기본값)를 구성하고, 자신의 지갑으로 서명한 뒤, 헤더에 결제 증명을 담아 원래 요청을 재시도한다.
서비스가 검증하고, 정산하고, 데이터를 반환한다.

우리는 이를 처음부터 끝까지 구현한다. 에이전트는 API 키나 대시보드 가입 없이 우리의 RPC API, Token API, Portfolio API, NFT API, Prices API를 호출할 수 있다. 첫 요청은 402를 받고, 이후 요청은 엔드포인트가 요청한 금액을 Base 위의 USDC로 지불하고 데이터를 반환받는다. 사람의 개입은 없다.

최소한의 클라이언트 측 핸들러는 다음과 같다:

typescriptCopied
async function paidFetch(url: string, wallet: AgentWallet) {
  let res = await fetch(url);

  if (res.status === 402) {
    const requirement = await res.json();
    const payment = await wallet.signX402Payment(requirement);

    res = await fetch(url, {
      headers: { "X-PAYMENT": payment },
    });
  }

  return res.json();
}

에이전트는 서명된 결제 헤더와 함께 같은 URL을 재시도한다. 엔드포인트는 온체인에서 결제를 정산하고, 데이터를 돌려주며, 에이전트는 계속 진행한다. 이 패턴은 프로바이더 전반에 걸쳐 조합 가능하다: x402를 지원하는 서비스라면 커스텀 인증을 작성하지 않고도 에이전트 결제를 받을 수 있다.

에이전트는 어떻게 체인과 동기화 상태를 유지하는가?

체인은 기본적으로 당신의 앱에 푸시하지 않는다. 에이전트가 무슨 일이 일어나는지 알기 위해 eth_blockNumber를 매초 폴링한다면, 폴링 비용을 지불하면서도 정작 신경 써야 할 모든 이벤트에는 늦게 도착하게 된다.

거의 모든 실시간 사용 사례는 세 가지 패턴으로 커버된다. 전체 분석은 webhooks vs WebSockets vs gRPC 비교에 있지만, 에이전트 개발자를 위한 요약 버전은 다음과 같다:

Pattern	Use when
Webhooks	The agent runs as a service with a public URL and wants the provider to push events (new transactions, mined blocks, address activity). Cheapest to operate at low-to-medium event volume.
WebSockets	The agent runs a persistent process and needs sub-second pickup on logs and pending transactions. Best for in-process loops.
gRPC streaming	The agent is throughput-bound on Solana or another high-TPS chain. Lowest latency, highest cost to integrate.

대부분의 에이전트에게는 webhooks와 몇 가지 Data API 호출(token balances, transaction history, portfolio)로 충분하다. webhook이 발생하면 에이전트가 깨어나서, 보강된 상태를 조회하고, 무엇을 할지 결정하고, 트랜잭션에 서명한 뒤 다시 잠든다.

전체 연결하기: 최소한의 온체인 에이전트 아키텍처

세 가지 빌딩 블록을 모두 결합한 간결한 아키텍처 스케치를 살펴본다. 이것은 자신의 지갑을 지켜보다가, 무언가 도착하면 유료 엔드포인트를 조회하고, LLM에게 무엇을 할지 묻고, 응답 트랜잭션에 서명한다. 프로덕션에서 실행하기 전에 x402 서명 헬퍼를 당신의 커스터디 프로바이더로 교체하라.

typescriptCopied
import { createPublicClient, webSocket } from "viem";
import { base } from "viem/chains";
import { execFile } from "node:child_process";
import { promisify } from "node:util";
import OpenAI from "openai";

const run = promisify(execFile);
const openai = new OpenAI();
const agentWallet = process.env.AGENT_WALLET_ADDRESS!.toLowerCase();
const client = createPublicClient({
  chain: base,
  transport: webSocket(process.env.ALCHEMY_RPC_WSS!),
});

async function signX402Payment(requirement: unknown) {
  // Plug in your x402 client and custody provider here.
  // The signer should construct the payment payload and sign it with the agent wallet.
  throw new Error("Implement x402 signing with your wallet provider");
}

// 1. Signing through the agent wallet session (no private key in process).
// Use the session approved via `alchemy wallet connect` to sign and broadcast.
async function refund(to: string, amountEth: string) {
  // Plug in your agent wallet signing provider here.
  throw new Error("Implement refund signing with your agent wallet session");
}

// 2. Paid data fetch via x402 against an Alchemy endpoint.
async function paidFetch(url: string) {
  let res = await fetch(url);
  if (res.status === 402) {
    const requirement = await res.json();
    const payment = await signX402Payment(requirement);
    res = await fetch(url, { headers: { "X-PAYMENT": payment } });
  }
  return res.json();
}

// 3. Real-time trigger: react to inbound transactions on the agent wallet.
client.watchBlocks({
  includeTransactions: true,
  onBlock: async (block) => {
    for (const tx of block.transactions) {
      if (tx.to?.toLowerCase() !== agentWallet) continue;

      const portfolio = await paidFetch(
        `https://api.g.alchemy.com/data/v1/portfolio/${tx.from}`
      );

      const decision = await openai.chat.completions.create({
        model: "gpt-4o",
        messages: [
          {
            role: "system",
            content: "You are a treasury agent. Decide whether to refund.",
          },
          {
            role: "user",
            content: JSON.stringify({ tx, sender_portfolio: portfolio }),
          },
        ],
      });

      const action = JSON.parse(decision.choices[0].message.content!);
      if (action.refund) {
        await refund(tx.from, action.amount);
      }
    }
  },
});

이 구조에서 주목할 세 가지가 있다:

프로세스 내에 프라이빗 키가 없다. 모든 서명 호출은 CLI 세션을 거치며, 이는 Privy와 통신한다. 이 프로세스가 침해되더라도 공격자는 지갑이 아니라 취소 가능한 세션을 얻을 뿐이다.
데이터 호출에 API 키가 없다. paidFetch은 x402를 지원하는 모든 엔드포인트에 대해 작동한다. 엔드포인트는 요청당 USDC로 과금한다.
LLM은 가장 작은 부분이다. 대부분의 영역은 지갑, 결제, 데이터 배관이다. 모델은 그저 결정만 한다.

이것이 그 패턴이다. 트리거(Discord 메시지, cron, 마켓플레이스 이벤트)를 바꾸고, 액션(스왑, 투표, 브리지, 민팅)을 바꾸고, 모델을 바꾸면 다른 에이전트가 된다.

Claude로 만들기

혹은 Claude가 대신 만들도록 할 수도 있다. Alchemy Skills를 설치하고 hosted MCP server를 연결하라:

bash

Copied

npx skills add alchemyplatform/skills --yes

# Claude Code — see the MCP server docs for other clients
claude mcp add alchemy --transport http https://mcp.alchemy.com/mcp

그런 다음 이 프롬프트를 Claude Code에 붙여넣는다:

text

Copied

Build a TypeScript onchain agent on Base that:
1. Watches a wallet address for incoming transactions in real time
2. When a transaction arrives, queries an x402-payable portfolio API for the sender's holdings
3. Asks an LLM whether to refund
4. Signs the refund without holding the private key in the process

Use production-grade primitives.

출력은 위 스크립트를 그대로 반영한다: 우리 RPC를 대상으로 하는 viem WebSocket, x402 뒤에 있는 Portfolio API, 그리고 환불을 위해 승인된 agent wallet 세션을 통한 CLI 서명. 프로세스 내에는 프라이빗 키가 없다.

어떤 에이전트 프레임워크를 사용해야 하는가?

프레임워크는 위의 세 가지 프리미티브 위에 계층으로 얹힌다. 에이전트 루프, 툴 등록, 메모리, 그리고 (일부는) 소셜 플랫폼 클라이언트를 처리한다. 올바른 선택은 체인 깊이, 멀티체인 폭, 완전한 런타임 중 무엇을 최적화하느냐에 달려 있다.

Framework	Best for	Chains	Notes
LangChain / LangGraph	General-purpose orchestration with any model and any tool	Any (via tool wrappers)	Most flexible, least opinionated. You wire the wallet and RPC tools yourself.
GOAT SDK by Crossmint	Multi-chain agents that need EVM and Solana under one API	EVM + Solana	Plugin model. Good fit when the agent crosses chains.
ElizaOS agent runtime	Social agents (Twitter, Discord, Farcaster) with character files	Any	Full runtime including memory and platform clients. Heavier than a library.
Solana Agent Kit by SendAI	Deepest Solana protocol coverage (Jupiter, Raydium, Drift, etc.)	Solana only	Tool library, not a runtime. Bring your own loop.
Vercel AI SDK	Streaming agent responses to a web UI	Any (via tools)	Good fit for streaming agent responses to a browser UI.

지갑 설정, RPC 통합, Jupiter 스왑을 포함한 체인 네이티브 엔드투엔드 빌드는 Solana AI agent build guide를 참고하라. 체인에 구애받지 않는 프로바이더 비교는 the best blockchain APIs for autonomous onchain agents를 참고하라.

프레임워크는 빌딩 블록과 달리 서로 교체 가능하다. LangChain을 GOAT로 바꾸는 데는 오후 한나절이면 충분하다. 하지만 에이전트가 서명하는 방식을 바꾸는 것은 보안 검토가 필요한 일이다.

다음으로 무엇을 만들어야 하는가

세 가지 빌딩 블록은 조합된다. 세션 범위 지갑을 보유하고, x402로 데이터 비용을 지불하고, 실시간 이벤트에 반응하는 에이전트를 갖게 되면, 질문은 "에이전트가 이걸 할 수 있는가"에서 "에이전트가 무엇을 해야 하는가"로 바뀐다.

우리는 이 세 가지 빌딩 블록 각각을 프리미티브로 제공한다. 우리의 CLI는 Privy 기반의 취소 가능한 세션을 통해 지갑을 처리한다. 우리의 RPC, Token, Portfolio, NFT, Prices API는 x402를 직접 지원한다. API 키도, 대시보드 가입도, 계약도 필요 없다. Webhooks, WebSocket subscriptions, Solana gRPC streaming이 실시간 데이터 피드를 커버한다.

npx skills add alchemyplatform/skills --yes를 실행하고, hosted MCP server를 연결한 다음, LangChain, GOAT, ElizaOS, 또는 당신의 프레임워크를 Alchemy의 API로 향하게 하라. npm i -g @alchemy/cli@latest과 alchemy auth로 시작하라. 더 알아보려면 alchemy.com/agents를 방문하라.

자주 묻는 질문

온체인 에이전트란 무엇인가?

온체인 에이전트는 블록체인 상태를 읽고, 지갑을 보유하거나 제어하고, 정책이나 모델의 결정에 따라 트랜잭션에 서명할 수 있는 AI 에이전트다. 모델이 무엇을 할지 결정하고, 지갑, 결제 레일, 데이터 피드가 그것을 실행할 수 있게 해준다.

온체인 에이전트는 어떻게 구축하는가?

세 가지 프리미티브로 시작하라: 서명을 위한 범위가 제한된 지갑, 유료 API 호출을 위한 x402 같은 결제 레일, webhooks, WebSockets, gRPC를 통한 실시간 데이터 피드. 그런 다음 이 프리미티브들을 이미 사용 중인 에이전트 프레임워크나 오케스트레이션 루프에 연결하라.

AI 에이전트는 어떤 지갑을 사용해야 하는가?

원시 프라이빗 키를 에이전트 프로세스 밖에 두는 지갑 패턴을 사용하라. 위임된 서명을 사용하는 임베디드 스마트 계정은 사용자 대면 앱에 잘 맞고, 세션 범위 CLI 지갑은 개발자 에이전트, 내부 자동화, 프로토타입에 잘 맞는다.

온체인 에이전트는 API 비용을 어떻게 지불하는가?

x402 결제를 사용할 수 있다. 에이전트가 요청을 보내고, 결제 세부사항이 담긴 402 Payment Required 응답을 받고, 자신의 지갑으로 결제에 서명한 뒤, 결제 증명과 함께 요청을 재시도한다.

온체인 에이전트는 webhooks, WebSockets, gRPC 중 무엇을 사용해야 하는가?

에이전트가 서비스로 실행되고 푸시된 이벤트를 받을 수 있다면 webhooks를 사용하라. 에이전트가 지속적인 프로세스로 실행되고 로그나 대기 중인 트랜잭션에 대한 낮은 지연 시간이 필요하다면 WebSockets를 사용하라. 지연 시간이 통합 작업량을 정당화할 만큼 중요한 고처리량 Solana 스타일 워크로드에는 gRPC streaming을 사용하라.

온체인 에이전트를 위한 최고의 프레임워크는 무엇인가?

최고의 프레임워크는 필요한 루프에 따라 다르다. LangChain 또는 LangGraph는 범용 오케스트레이션에 유연하고, GOAT는 멀티체인 툴 커버리지에 유용하며, ElizaOS는 소셜 에이전트를 위해 만들어졌고, Solana Agent Kit은 Solana에 깊이 파고들며, Vercel AI SDK는 브라우저 대면 에이전트 UI에 적합하다.

핵심 인프라는 구축할 준비가 되어 있다. 이를 가지고 무엇을 할지는 다른 누구도 대신 써줄 수 없는 부분이다.

Alchemy 뉴스레터

출시 소식을 가장 먼저 받아보세요

뉴스레터 구독하기

Alchemy의 최신 제품 업데이트와 리소스 받기

구독자 80,000명 이상

이메일 주소를 입력하면 마케팅 커뮤니케이션 및 제품 업데이트 수신에 동의하게 됩니다. Alchemy는 저희 개인정보 처리방침에 따라 수집한 정보를 처리합니다. 언제든지 구독을 취소할 수 있습니다.