x402로 시작하기

x402 프로토콜(또는 L402로도 알려짐)은 구독 없이 사용량 기반 접근을 가능하게 하는 API 수익화의 새로운 표준입니다.

Minara x402 엔드포인트: https://x402.minara.ai

x402란 무엇인가요?

x402는 웹을 위한 네이티브 "페이-투-플레이" 시스템입니다. 구독을 선결제하는 대신 $USDC와 같은 스테이블코인으로 각 API 호출에 대해 직접 결제합니다.

주요 이점:

• 구독 불필요: 사용한 만큼만 결제

• 권한 없는(무허가) 접근: 계정 생성이나 승인 절차 불필요

• 즉시 활성화: 결제 후 즉시 API 사용 시작

• 크립토 네이티브: Base, Solana 또는 Polygon에서 USDC로 결제

• 투명한 가격 책정: 각 API 호출의 비용을 정확히 확인 가능

작동 방식:

x402 프로토콜은 다음 주요 단계로 구성된 결제-챌린지 흐름을 따릅니다:

전체 흐름

1. 초기 요청 (클라이언트 → 서버)

   • 결제 없이 보호된 엔드포인트에 API 요청을 보냅니다

2. 결제 챌린지 (서버 → 클라이언트)

   • 서버가 다음으로 응답합니다 402 Payment Required 상태

   • 결제 지침(금액, 통화, 수신자 주소, 체인)을 반환합니다

3. 결제 선택 (클라이언트)

   • 결제 방법을 선택하고 결제 페이로드를 생성합니다

   • 지정된 체인에서 USDC로 결제할 준비를 합니다

4. 인증된 요청 (클라이언트 → 서버)

   • 결제 증명을 포함하세요 x-payment-response 헤더

   • 원래 요청을 재시도합니다

5. 검증 (서버 → 중개자)

   • 서버가 검증을 위해 중개자에게 결제 증명을 전송합니다

   • 결제 유효성을 확인합니다

6. 결제 처리 (중개자 → 블록체인)

   • 중개자가 거래를 블록체인에 제출합니다

   • 거래가 온체인에서 확인됩니다

7. 정산 (중개자 → 서버)

   • 중개자가 서버에 정산을 확인합니다

   • 결제가 완료됩니다

8. 접근 허용 (서버 → 클라이언트)

   • API 응답을 받습니다

   • 결제 영수증이 포함됩니다 X-PAYMENT-RESPONSE 헤더

핵심 구성 요소

• 클라이언트: API 요청을 하는 귀하의 애플리케이션

• 서버: Minara API 엔드포인트 (https://x402.minara.ai)

• 중개자: 결제 검증 및 정산 서비스

• 블록체인: 온체인 결제 정산 (Base, Solana 또는 Polygon)

---

Minara에서 x402 사용 방법

1. x402 SDK 사용(권장)

대부분의 개발자는 공식 x402 SDK를 사용하며, 모든 결제 흐름을 자동으로 처리합니다.

귀하는 요청만 하면 되며 SDK가 결제 챌린지, 검증 및 정산을 처리합니다.

사전 요구사항

시작하기 전에 다음을 확인하세요:

• USDC가 있는 암호화폐 지갑(임의의 EVM 호환 지갑)

• Node.js 및 npm, Go, 또는 Python 및 pip

• 지갑의 개인 키(결제 서명을 위해)

1단계: 종속성 설치

Node.js / TypeScript

# fetch 기반 클라이언트용(권장)
npm install @x402/fetch @x402/evm

# axios 기반 클라이언트용
npm install @x402/axios @x402/evm

# Solana 지원을 위해 추가:
npm install @x402/svm

Python

# httpx (비동기)용 - 권장
pip install "x402[httpx]"

# requests (동기)용
pip install "x402[requests]"

# Solana 지원을 위해 추가:
pip install "x402[svm]"

Go

go get github.com/coinbase/x402/go

2단계: 지갑 서명자 설정

Node.js (viem 사용)

npm install viem

import { privateKeyToAccount } from "viem/accounts";

// 개인 키로 서명자 생성(환경 변수 사용)
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

Solana의 경우:

import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";

const svmSigner = await createKeyPairSignerFromBytes(
  base58.decode(process.env.SOLANA_PRIVATE_KEY!)
);

Python (eth-account 사용)

pip install eth_account

import os
from eth_account import Account
from x402.mechanisms.evm import EthAccountSigner

account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
signer = EthAccountSigner(account)

Go

import (
    evmsigners "github.com/coinbase/x402/go/signers/evm"
)

evmSigner, err := evmsigners.NewClientSignerFromPrivateKey(os.Getenv("EVM_PRIVATE_KEY"))
if err != nil {
    log.Fatal(err)
}

3단계: 요청하기: 결제가 자동으로 처리됩니다!

SDK가 결제 챌린지를 자동으로 처리합니다. 평소처럼 요청만 하세요!

Node.js (fetch 사용)

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

// 서명자 생성
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

// x402 클라이언트 생성 및 EVM 스킴 등록
const client = new x402Client();
registerExactEvmScheme(client, { signer });

// 결제 처리를 위한 fetch 래핑
const fetchWithPayment = wrapFetchWithPayment(fetch, client);

// 요청하기 - 결제가 자동으로 처리됩니다! 🎉
const response = await fetchWithPayment("https://x402.minara.ai/x402/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    userQuery: "현재 BTC 가격은 얼마인가요?"
  })
});

const data = await response.json();
console.log("Response:", data.content);

// 결제 영수증 받기(선택 사항)
if (response.ok) {
  const httpClient = new x402HTTPClient(client);
  const paymentResponse = httpClient.getPaymentSettleResponse(
    (name) => response.headers.get(name)
  );
  console.log("Payment settled:", paymentResponse);
}

📖 GitHub에 전체 예제가 있습니다

Node.js (axios 사용)

import { x402Client, wrapAxiosWithPayment } from "@x402/axios";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import axios from "axios";

// 서명자 생성
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

// x402 클라이언트 생성 및 EVM 스킴 등록
const client = new x402Client();
registerExactEvmScheme(client, { signer });

// 결제 처리를 포함한 Axios 인스턴스 생성
const api = wrapAxiosWithPayment(
  axios.create({ baseURL: "https://x402.minara.ai" }),
  client
);

// 요청하기 - 결제가 자동으로 처리됩니다! 🎉
const response = await api.post("/x402/chat", {
  userQuery: "ETH 가격 움직임 분석"
});

console.log("Response:", response.data.content);

📖 GitHub에 전체 예제가 있습니다

Python (httpx 비동기)

import asyncio
import os
from eth_account import Account

from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client


async def call_minara():
    # 클라이언트 생성 및 EVM 스킴 등록
    client = x402Client()
    account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
    register_exact_evm_client(client, EthAccountSigner(account))

    # 요청하기 - 결제가 자동으로 처리됩니다! 🎉
    async with x402HttpxClient(client) as http:
        response = await http.post(
            "https://x402.minara.ai/x402/chat",
            json={"userQuery": "BTC 가격은 얼마인가요?"}
        )
        await response.aread()
        
        data = response.json()
        print(f"Response: {data['content']}")


asyncio.run(call_minara())

📖 GitHub에 전체 예제가 있습니다

Python (requests 동기)

import os
from eth_account import Account

from x402 import x402ClientSync
from x402.http.clients import x402_requests
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client


def call_minara():
    # 클라이언트 생성 및 EVM 스킴 등록
    client = x402ClientSync()
    account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
    register_exact_evm_client(client, EthAccountSigner(account))

    # 요청하기 - 결제가 자동으로 처리됩니다! 🎉
    with x402_requests(client) as session:
        response = session.post(
            "https://x402.minara.ai/x402/chat",
            json={"userQuery": "BTC 가격은 얼마인가요?"}
        )
        
        data = response.json()
        print(f"Response: {data['content']}")


call_minara()

📖 GitHub에 전체 예제가 있습니다

Go

package main

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
    "time"

    x402 "github.com/coinbase/x402/go"
    x402http "github.com/coinbase/x402/go/http"
    evm "github.com/coinbase/x402/go/mechanisms/evm/exact/client"
    evmsigners "github.com/coinbase/x402/go/signers/evm"
)

func main() {
    // EVM 서명자 생성
    evmSigner, _ := evmsigners.NewClientSignerFromPrivateKey(os.Getenv("EVM_PRIVATE_KEY"))

    // x402 클라이언트 생성 및 EVM 스킴 등록
    x402Client := x402.Newx402Client().
        Register("eip155:*", evm.NewExactEvmScheme(evmSigner))

    // 결제 처리를 위한 HTTP 클라이언트 래핑
    httpClient := x402http.WrapHTTPClientWithPayment(
        http.DefaultClient,
        x402http.Newx402HTTPClient(x402Client),
    )

    // 요청 본문 준비
    reqBody := map[string]string{"userQuery": "BTC 가격은 얼마인가요?"}
    jsonData, _ := json.Marshal(reqBody)

    // 요청하기 - 결제가 자동으로 처리됩니다! 🎉
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    req, _ := http.NewRequestWithContext(ctx, "POST", "https://x402.minara.ai/x402/chat", bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    
    resp, err := httpClient.Do(req)
    if err != nil {
        fmt.Printf("Request failed: %v\n", err)
        return
    }
    defer resp.Body.Close()

    var data map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&data)
    fmt.Printf("Response: %v\n", data["content"])
}

📖 GitHub에 전체 예제가 있습니다

다중 체인 지원 (Base + Solana + Polygon)

모든 Minara 체인을 지원하도록 여러 결제 스킴을 등록할 수 있습니다:

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { registerExactSvmScheme } from "@x402/svm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";

// 서로 다른 체인용 서명자 생성
const evmSigner = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const svmSigner = await createKeyPairSignerFromBytes(
  base58.decode(process.env.SOLANA_PRIVATE_KEY!)
);

// 여러 스킴을 가진 클라이언트 생성
const client = new x402Client();
registerExactEvmScheme(client, { signer: evmSigner });  // Base + Polygon
registerExactSvmScheme(client, { signer: svmSigner });  // Solana

const fetchWithPayment = wrapFetchWithPayment(fetch, client);

// 이제 모든 Minara 엔드포인트를 호출할 수 있습니다! 🚀
// Base 엔드포인트
await fetchWithPayment("https://x402.minara.ai/x402/chat", {...});

// Solana 엔드포인트  
await fetchWithPayment("https://x402.minara.ai/x402/solana/chat", {...});

// Polygon 엔드포인트
await fetchWithPayment("https://x402.minara.ai/x402/polygon/chat", {...});

전체 예제: Minara와 채팅

다음은 Minara의 AI 채팅 엔드포인트를 호출하는 전체 작동 예제입니다:

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client, x402HTTPClient } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

async function chatWithMinara(query: string) {
  // 1. 서명자 설정
  const signer = privateKeyToAccount(
    process.env.EVM_PRIVATE_KEY as `0x${string}`
  );

  // 2. x402 클라이언트 생성
  const client = new x402Client();
  registerExactEvmScheme(client, { signer });

  // 3. fetch 래핑
  const fetchWithPayment = wrapFetchWithPayment(fetch, client);

  // 4. 요청하기 - SDK가 결제를 자동으로 처리합니다!
  const response = await fetchWithPayment("https://x402.minara.ai/x402/chat", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ userQuery: query })
  });

  const data = await response.json();
  return data.content;
}

// 사용 예
const answer = await chatWithMinara("현재 BTC 가격은 얼마인가요?");
console.log(answer);
// 출력: "BTC는 현재 $98,450에 거래되고 있습니다. 주요 지지 수준..."

자세한 내용은 공식 x402 문서를 확인하세요: 구매자용 빠른 시작 가이드

---

2. 수동 결제 흐름(SDK 없이)

SDK를 사용하지 않으려면 결제를 수동으로 처리할 수 있습니다:

1단계: 초기 요청 보내기

curl -X POST https://x402.minara.ai/x402/chat \
  -H "Content-Type: application/json" \
  -d '{"userQuery": "BTC 가격은 얼마인가요?"}'

2단계: 결제 챌린지 수신

{
  "error": "payment_required",
  "message": "이 리소스에 접근하려면 결제가 필요합니다",
  "paymentInstructions": {
    "amount": "0.20",
    "currency": "USDC",
    "recipient": "0xCF5815e9063FA0b04Be0Cb5C1DB583eeF9ef5fbB",
    "chain": "base"
  }
}

3단계: 지갑으로 결제

MetaMask, Phantom 또는 기타 Web3 지갑을 사용하여 수신자 주소로 USDC를 전송하세요.

4단계: 결제 증명과 함께 재시도

curl -X POST https://x402.minara.ai/x402/chat \
  -H "x-payment-response: <payment_proof_token>" \
  -H "Content-Type: application/json" \
  -d '{"userQuery": "BTC 가격은 얼마인가요?"}'

5단계: 응답 받기

{
  "content": "BTC는 현재 $98,450에 거래되고 있습니다..."
}

---

오류 처리

Minara API의 일반적인 오류

402 Payment Required

{ "error": "payment_required" }

→ 정상입니다! SDK가 이를 자동으로 처리합니다.

401 Unauthorized

{ "error": "unauthorized", "message": "유효하지 않은 결제 응답 토큰" }

→ 결제 증명이 잘못되었거나 만료되었습니다. SDK가 재시도합니다.

400 Bad Request

{ "error": "bad_request", "message": "필수 매개변수 누락: userQuery" }

→ 요청 본문에 필수 필드가 있는지 확인하세요.

요청 한도

x402 엔드포인트는 지갑 주소별로 속도 제한이 적용됩니다:

• AI 엔드포인트: 분당 60 요청

• 거래 엔드포인트: 분당 30 요청

제한을 초과하면:

{
  "error": "rate_limit_exceeded",
  "message": "요청이 너무 많습니다. 30초 후에 다시 시도하세요.",
  "retryAfter": 30
}

---

리소스 및 지원

📚 공식 x402 리소스

• x402 프로토콜 문서

• 구매자용 빠른 시작 가이드

• x402 GitHub 저장소

• x402 Discord

📦 NPM 패키지

• @x402/fetch - Fetch 래퍼

• @x402/axios - Axios 인터셉터

• @x402/evm - EVM 지원(Base, Polygon)

• @x402/svm - Solana 지원

• x402 Python 패키지

🔍 Minara 전용

• x402scan의 Minara - 모든 엔드포인트 보기

• Minara API 참조 (x402) - API 참조 (x402)

API 참조

API 참조 (x402)