tenequm/mpp

MPP - Machine Payments Protocol

MPP는 Tempo와 Stripe가 공동 개발한 개방형 프로토콜로, 기계 간(machine-to-machine) 결제를 위한 HTTP 402 Payment Required를 표준화합니다. 클라이언트는 동일한 HTTP 요청 내에서 결제합니다. 계정, API 키 또는 체크아웃 흐름이 필요하지 않습니다.

핵심 프로토콜 사양은 Payment HTTP Authentication Scheme으로 IETF에 제출되었습니다.

이 스킬의 코드는 플레이스홀더 토큰 이름(<USDC_TEMPO_MAINNET>, <PATHUSD_TESTNET>)을 사용합니다. 실제 주소는 Tempo 문서 및 references/tempo-method.md에 있습니다.

핵심 아키텍처

세 가지 기본 요소가 모든 MPP 결제를 구동합니다:

1. Challenge - 서버가 발행하는 결제 요구 사항 (WWW-Authenticate: Payment 헤더)
2. Credential - 클라이언트가 제출하는 결제 증명 (Authorization: Payment 헤더)
3. Receipt - 성공적인 결제에 대한 서버 확인 (Payment-Receipt 헤더)

결제 방법 및 인텐트

MPP는 결제 방법에 구애받지 않습니다. 각 방법은 자체 정산 레일을 정의합니다:

방법	레일	SDK 패키지	상태
Tempo	TIP-20 스테이블코인 (Tempo 체인)	mppx (내장)	프로덕션
Stripe	카드/지갑 (SPT) + 온체인 암호화폐 입금	mppx (내장)	프로덕션
EVM	EIP-3009 스테이블코인 승인 (x402-exact 호환)	mppx (내장)	프로덕션
Lightning	라이트닝 네트워크를 통한 비트코인	@buildonspark/lightning-mpp-sdk	프로덕션
Stellar	SEP-41 토큰 (Stellar), charge + channel	@stellar/mpp	프로덕션 (channel 와이어 사양은 아직 초안 단계로 변경될 수 있음)
Solana	Solana 네이티브 charge + session (SOL, SPL, Token-2022)	@solana/mpp	프로덕션
Monad	Monad charge (ERC-3009, 정산 모드)	@monad-crypto/mpp	프로덕션
NEAR Intents	1Click 입금 주소를 통한 크로스체인 charge	@defuse-protocol/nearintents-mpp-sdk	프로덕션 (신뢰할 수 없음 - 정산 백엔드를 통해 라우팅되며, 방법별 위험 정책을 위해 methodDetails.settlementBackend: "near-intents"로 광고됨)
RedotPay	RedotPay 잔액 (rdt) 또는 스테이블코인 증명, charge 전용	@redotpay/mpp	프로덕션
Card	암호화된 네트워크 토큰 (Visa)	mpp-card	프로덕션
맞춤형	모든 레일	Method.from() + Method.toClient/toServer	확장 가능

방법별 심층 분석: references/tempo-method.md, references/stripe-method.md, references/lightning-method.md, references/custom-methods.md

인텐트	패턴	최적 사용 사례
charge	요청당 일회성 결제	API 호출, 콘텐츠 액세스, 고정 가격 엔드포인트
session	결제 채널을 통한 사용량 기반 과금 (Pay-as-you-go)	LLM 스트리밍, 종량제 과금, 고빈도 API
subscription	승인된 키(Tempo)를 통한 정기 액세스 - references/subscriptions.md 참조	요청별 과금과 분리된 액세스가 필요한 플랜/티어

빠른 시작: 서버 (TypeScript)

import { Mppx, tempo } from 'mppx/server'

const mppx = Mppx.create({
  methods: [tempo({
    currency: '<PATHUSD_TESTNET>', // pathUSD 테스트넷
    recipient: '0xYourAddress',
  })],
})

export async function handler(request: Request) {
  const result = await mppx.charge({ amount: '0.01' })(request)
  if (result.status === 402) return result.challenge
  return result.withReceipt(Response.json({ data: '...' }))
}

설치: npm install mppx viem (mppx 0.8.15는 viem >= 2.54.0 필요)

완성된 서버를 종단 간 검증하려면 npx mppx validate http://localhost:3000을 실행하세요.

빠른 시작: 클라이언트 (TypeScript)

import { privateKeyToAccount } from 'viem/accounts'
import { Mppx, tempo } from 'mppx/client'

// globalThis.fetch를 패치하여 402를 자동으로 처리합니다.
Mppx.create({
  methods: [tempo({ account: privateKeyToAccount('0x...') })],
})

const res = await fetch('https://api.example.com/paid')
// 서버가 402를 반환하면 결제가 투명하게 이루어집니다.

브라우저에서 mppx 0.6.0은 기본값을 변경했습니다: 패치된 fetch는 동일 출처(same-origin) 엔드포인트에만 Accept-Payment를 전송하므로, 교차 출처 유료 API는 acceptPaymentPolicy ('always' / { origins: [...] })가 필요합니다. 클라이언트 fetch는 maxPaymentRetries(기본값 3)까지 증분 챌린지를 재시도합니다. 전역 대안(Fetch.from/polyfill/restore, Mppx.restore())은 references/typescript-sdk.md를 참조하세요.

빠른 시작: 서버 (Python)

from fastapi import FastAPI
from mpp import Credential, Receipt
from mpp.server import Mpp
from mpp.methods.tempo import tempo, ChargeIntent

app = FastAPI()
server = Mpp.create(method=tempo(
    currency="<PATHUSD_TESTNET>",
    recipient="0xYourAddress", intents={"charge": ChargeIntent()},
))

@app.get("/resource")
@server.pay(amount="0.50")
async def get_resource(request, credential: Credential, receipt: Receipt):
    return {"data": "paid content", "payer": credential.source}

설치: pip install "pympp[tempo]". 전체 패턴은 references/python-sdk.md를 참조하세요.

빠른 시작: 서버 (Rust)

설치: cargo add mpp --features tempo,server. 전체 패턴은 references/rust-sdk.md를 참조하세요.

프레임워크 미들웨어 (TypeScript)

각 프레임워크는 자체 임포트(mppx/nextjs, mppx/hono, mppx/express, mppx/elysia)를 사용합니다:

// Next.js
import { Mppx, tempo } from 'mppx/nextjs'
const mppx = Mppx.create({ methods: [tempo({ currency: '<PATHUSD_TESTNET>', recipient: '0x...' })] })
export const GET = mppx.charge({ amount: '0.1' })(() => Response.json({ data: '...' }))

// Hono
import { Mppx, tempo } from 'mppx/hono'
app.get('/resource', mppx.charge({ amount: '0.1' }), (c) => c.json({ data: '...' }))

Express 및 Elysia 예제는 references/typescript-sdk.md를 참조하세요.

세션: 사용량 기반 과금 스트리밍

세션은 결제 채널을 한 번 연 다음, 각 요청에 대해 오프체인 바우처를 사용합니다. 요청당 블록체인 트랜잭션이 없습니다. 100ms 미만의 지연 시간, 요청당 거의 0에 가까운 수수료.

세션 v2 (mppx 0.7.0부터 기본값): tempo.session()은 TIP-1034 프리컴파일 채널 흐름입니다. 이전 에스크로 컨트랙트 구현은 세션 v1이며, 여전히 더 이상 사용되지 않는 tempo.sessionLegacy로 사용 가능합니다. v2를 기대하는 클라이언트는 v1 세션을 거부하고 charge 경로로 폴백하므로, 클라이언트와 서버를 일치된 흐름으로 유지하세요. 두 가지 클라이언트 API: tempo.session({ account, maxDeposit })는 Mppx.create()로 메서드를 등록하고 (fetch를 통한 투명한 402 처리), tempo.session.manager({ account, maxDeposit })는 직접 수명 주기 제어를 위한 관리형 클라이언트를 반환합니다 (.sse(), .close()).

// 서버 - 자동 정산이 있는 세션 엔드포인트
const mppx = Mppx.create({
  methods: [tempo.session({
    currency: '<PATHUSD_TESTNET>', recipient: '0x...',
    store: Store.redis(redis),
    settlementSchedule: { amount: '1.00', intervalMs: 300_000 },
    bootstrap: true, // 재방문 클라이언트가 이 경로에서 채널을 복구할 수 있도록 함
  })],
})
const result = await mppx.session({ amount: '0.001', unitType: 'token' })(request)
if (result.status === 402) return result.challenge
return result.withReceipt(Response.json({ data: '...' }))

// 서버 - 단어별 과금이 있는 SSE 스트리밍
export const GET = mppx.session({ amount: '0.001', unitType: 'word' })(
  async () => async function* (stream) {
    for (const word of ['hello', 'world']) {
      await stream.charge()
      yield word
    }
  }
)

// 클라이언트 - 자동 관리 채널이 있는 세션
Mppx.create({ methods: [tempo({ account, maxDeposit: '1' })] })
const res = await fetch('http://localhost:3000/api/resource')
// 첫 번째 요청: 온체인 채널 열기; 두 번째 요청부터: 오프체인 바우처

세션은 Ws.serve()를 통해 WebSocket으로도 스트리밍됩니다. 전체 수명 주기, 정산, 저장소, SSE 및 WebSocket 패턴, 채널 복구는 references/sessions.md를 참조하세요.

다중 방법 지원

단일 엔드포인트에서 Tempo 스테이블코인, Stripe 카드 및 Lightning 비트코인을 지원합니다:

const mppx = Mppx.create({
  methods: [
    tempo({ currency: '<PATHUSD_TESTNET>', recipient: '0x...' }),
    stripe.charge({ client: new Stripe(key), networkId: 'profile_...', paymentMethodTypes: ['card'] }),
    spark.charge({ mnemonic: process.env.MNEMONIC! }),
  ],
})

Mppx.compose()를 사용하여 경로별 가격 책정이 있는 단일 402 응답에 여러 방법을 표시하세요. 챌린지 사이트와 확인 사이트에 동일한 분기를 적용하거나, 402가 서버가 허용하는 것보다 적은 옵션을 광고합니다. references/typescript-sdk.md를 참조하세요.

결제 링크 (HTML)

결제 방법 구성에서 html: true를 설정하면 브라우저에서 402 엔드포인트를 방문할 때 테마, 다중 방법 구성 탭 및 Solana 지갑 지원이 포함된 브라우저 친화적인 결제 페이지가 렌더링됩니다. 서비스 워커가 크레덴셜 제출을 처리한 다음, 페이지가 지불된 응답과 함께 다시 로드됩니다.

mppx/html 내보내기(Config, Text, Theme)를 통해 사용자 정의하고, Html.init(methodName)으로 사용자 정의 방법의 결제 링크를 빌드하세요.

제로 달러 인증 (증명 크레덴셜)

결제 없이 에이전트 신원을 인증합니다. 클라이언트는 트랜잭션을 생성하는 대신 챌린지 ID에 대해 EIP-712 증명에 서명합니다. 가스가 소모되지 않고, 자금이 이체되지 않습니다.

// 서버 - 재생 방지를 위한 저장소가 있는 제로 달러 charge
const mppx = Mppx.create({
  methods: [tempo.charge({ currency: '<PATHUSD_TESTNET>', recipient: '0x...', store })],
})
const result = await mppx.charge({ amount: '0' })(request)

mppx 0.8.0부터 이러한 증명은 지갑 소유자에 바인딩됩니다. EIP-712 Proof 유형 데이터(tempo.Proof로 노출됨)는 도메인 버전 3에서 account 필드를 전달하므로, 한 계정에 대해 서명된 증명이 다른 계정에 대해 더 이상 확인되지 않습니다.

사용 사례: 신원 확인, 장기 실행 작업 폴링, 무료 후속 액세스가 있는 유료 잠금 해제, 다단계 에이전트 파이프라인. mpp.dev/advanced/identity를 참조하세요.

결제 프록시

MPP 결제 뒤에 기존 API를 게이트합니다:

// import { openai, Proxy } from 'mppx/proxy' - Proxy.create({ services: [...] }) 내부의 서비스
openai({
  apiKey: process.env.OPENAI_API_KEY,
  routes: {
    'POST /v1/chat/completions': mppx.charge({ amount: '0.05' }),
    'GET /v1/models': true, // 리터럴 `true`는 무료 경로를 표시합니다.
  },
})

내장 프리셋 openai(), anthropic(), stripe() 및 모든 업스트림을 위한 custom(). Proxy.create(), 제공하는 검색 엔드포인트 및 비프록시 서버를 위한 discovery() 헬퍼는 references/discovery-and-proxy.md를 참조하세요.

MCP 전송

MCP 도구 호출은 JSON-RPC 오류 코드 -32042를 사용하여 결제를 요구할 수 있습니다(서버는 -32043도 발행할 수 있음):

// 서버 - mppx/tempo가 아닌 mppx/server에서 tempo 가져오기
import { McpServer } from 'mppx/mcp/server'
import { tempo } from 'mppx/server'
const server = McpServer.wrap(baseServer, { methods: [tempo.charge({ /* ... */ })], secretKey })

// 클라이언트 - 결제 인식 MCP 클라이언트 (mppx/client에서 tempo 가져오기)
import { McpClient } from 'mppx/mcp/client'
import { tempo } from 'mppx/client'
const mcp = McpClient.wrap(client, { methods: [tempo({ account })] })
const result = await mcp.callTool({ name: 'premium_tool', arguments: {} })

HTTP를 통한 MCP 챌린지는 동일한 결제 인식 fetch에서 정산되며, 전송은 양쪽에서 Transport.from/http/mcp/mcpSdk를 통해 플러그 가능합니다. references/transports.md를 참조하세요.

Privy 서버 지갑

@privy-io/node/viem의 createViemAccount (@privy-io/node >= 0.20.0 필요)는 Privy 서버 지갑으로 백업되는 viem Account를 반환하므로, 로컬 계정이 들어갈 수 있는 모든 곳에서 tempo({ account })에 사용할 수 있습니다.

서버 측 서명은 앱 소유 서버 지갑에서 작동합니다. 사용자 소유 임베디드 지갑은 인증 키 또는 키 정족수가 필요합니다. 전체 설정 및 수동 toAccount() 구축은 references/typescript-sdk.md를 참조하세요.

테스트 및 CLI

# 계정 생성 (키체인에 저장됨), 테스트넷에서 자금 조달
npx mppx account create
npx mppx account fund --network testnet

# 유료 요청 보내기
npx mppx http://localhost:3000/resource

# 서명하지 않고 챌린지 구문 분석
npx mppx sign --dry-run --challenge '<www-authenticate value>'

# 서버 구현 종단 간 검증
npx mppx validate http://localhost:3000

CLI는 또한 init, sessions (목록/보기/닫기), discover, services, mcp add 및 skills add를 다룹니다. 구성은 MPPX_CONFIG 또는 명시적인 --config에서 가져옵니다. 작업 디렉토리에서 자동 검색은 없습니다. 전체 참조: references/cli.md

SDK 패키지

언어	패키지	설치
TypeScript	mppx	npm install mppx
Python	pympp	pip install "pympp[tempo]"
Rust	mpp	cargo add mpp --features tempo,client,server
Ruby	mpp-rb (공식, Stripe 제공)	gem 이름은 저장소 참조
Go	mpp-go (공식, Tempo 제공)	go get github.com/tempoxyz/mpp-go
Elixir	mpp (커뮤니티)	hex.pm/packages/mpp
Swift	mpp-swift (커뮤니티)	저장소 참조

기능 참고 사항(문서 매트릭스가 아닌 SDK 소스 기준 확인, 업스트림은 일치하지 않는 두 개를 게시함):

• Session 인텐트: TypeScript 및 Rust 전용
• Proof Credentials (제로 달러 인증): TypeScript