참조 문서

기술 문서

Microcosm SDK v1.1 — 3개 npm 패키지 - 91 Hooks - 12 UI 컴포넌트 - 85 API 엔드포인트

인증 방법

OAuth 2.0 Bearer Token

SDK 로그인 후 Access Token이 자동 획득됩니다; 모든 API 요청에 이 Token을 포함해야 합니다

curl -X GET "https://api.microcosm.money/v1/mcc/balance" \
  -H "Authorization: Bearer <access_token>"

SDK 자동 처리

SDK에 Token 관리 내장: 자동 저장, 자동 갱신, 만료 시 재로그인

// SDK auto-injects Authorization Header
import { useMCC, useMCCPrice } from '@microcosmmoney/auth-react'

const { balance, loading } = useMCC()
const { data: price } = useMCCPrice()

프로젝트 API Key

프로젝트 서버 측 쓰기 작업용, X-API-Key와 X-Project-ID 헤더 사용

curl -X POST "https://api.microcosm.money/v1/mining/submit-activity" \
  -H "X-API-Key: <api_secret>" \
  -H "X-Project-ID: <project_id>"

HMAC 서명

고보안 프로젝트용, HMAC-SHA256으로 요청에 서명. 타임 윈도우 ±300초

curl -X POST "https://api.microcosm.money/v1/funds/lock" \
  -H "X-Project-ID: <project_id>" \
  -H "X-Timestamp: <unix_timestamp>" \
  -H "X-Signature: sha256=<hmac_hash>"

SDK v2.1

3개의 npm 패키지 계층 설계 — 인증 · 데이터 · 채굴 · 마켓메이킹 · 영토 · 경매 · 대출 · 프래그먼트 · 투표 · 110+ Hooks · 30+ UI 컴포넌트

빠른 시작 (React / Next.js)

5분 만에 SDK 연동 완료

1설치: npm install @microcosmmoney/auth-react
2앱을 <MicrocosmAuthProvider>으로 감싸고 clientId
3/auth/callback 페이지를 <AuthCallback />
4아무 컴포넌트에서 useAuth()을 호출하여 사용자 상태 가져오기

SDK 계층형 아키텍처

portal-react

UI 메뉴 컴포넌트

auth-react

React Hooks

auth-core

코어 엔진

portal-react → auth-react → auth-core

@microcosmmoney/auth-core

Stable

프레임워크 독립 OAuth 2.0 코어 라이브러리 + Open API 클라이언트 + 43+ TypeScript 타입 + 정적 API 메서드

v2.2.1

설치 명령어

npm install @microcosmmoney/auth-core

기능

OAuth 2.0 클라이언트자동 Token 갱신43+ 타입 정의정적 API 메서드

코드 예제

import { MicrocosmAuthClient, MicrocosmAPI } from '@microcosmmoney/auth-core'
import type { MCCBalance, MCCPrice, MiningStats } from '@microcosmmoney/auth-core'

const client = new MicrocosmAuthClient({
  clientId: 'your-client-id',
  redirectUri: '/auth/callback',
})

client.login()
const { user } = await client.handleCallback(code)

const api = client.getApiClient()
const price = await MicrocosmAPI.mcc.price(api)
const balance = await MicrocosmAPI.mcc.balance(api)

@microcosmmoney/auth-react

Stable

React / Next.js 어댑터, 110+ Hooks로 인증, 자산, 채굴, 영지, 경매, 대출, 프래그먼트, 투표 모듈 지원

v2.2.1

설치 명령어

npm install @microcosmmoney/auth-react

기능

110+ React HooksProvider + Route Guard서버사이드 유틸리티IoC Provider 모드

코드 예제

import { MicrocosmAuthProvider, MicrocosmProvider, useAuth } from '@microcosmmoney/auth-react'

// Standard mode
<MicrocosmAuthProvider clientId="myproject" redirectUri="/auth/callback">
  <App />
</MicrocosmAuthProvider>

// IoC mode (project has its own auth)
<MicrocosmProvider getAccessToken={async () => yourAuth.getAccessToken()}>
  <App />
</MicrocosmProvider>

const { user, isAuthenticated, login, logout } = useAuth()

import { useMCC, useMCCPrice, useMiningStats, useAuctions } from '@microcosmmoney/auth-react'
const { balance, loading } = useMCC()
const { data: price } = useMCCPrice()
const { data: mining } = useMiningStats()

@microcosmmoney/portal-react

Stable

30+ UI 컴포넌트 + Dashboard 프리빌트 + 내비게이션 메뉴 + 데이터 시각화, shadcn/ui 호환

v2.0.0

설치 명령어

npm install @microcosmmoney/portal-react

기능

30+ UI 컴포넌트내비게이션 메뉴 시스템데이터 시각화사용자 정의 설정

코드 예제

import {
  TerminalButton, TerminalCard, TerminalTable,
  TerminalTabs, TerminalDialog, TerminalCountdown,
  TerritoryCard, MiningProgressBar, VoteResultBar,
  KPIRadialChart
} from '@microcosmmoney/portal-react'

import { dashboardMenu, blockchainMenu, web3OsMenu } from '@microcosmmoney/portal-react'
<TerminalNavigation groups={dashboardMenu} onItemClick={(item) => router.push(item.href)} />

백엔드 Token 교환

OAuth 2.0 Confidential Client 모드에서는 백엔드에서 client_secret로 Token 교환을 완료해야 합니다. SDK에서 한 줄짜리 API Route Handler를 제공합니다:

app/api/auth/exchange/route.ts

import { createTokenExchangeHandler } from '@microcosmmoney/auth-react/server'

export const POST = createTokenExchangeHandler({
  clientId: process.env.OAUTH_CLIENT_ID!,
  clientSecret: process.env.OAUTH_CLIENT_SECRET!,
})

전체 개발자 문서

연동 가이드 - API 레퍼런스 - 코드 예제 — 91개 Hooks 및 85개 API 엔드포인트 포함

연동 가이드 GitHub

Base URL

모든 API 요청은 다음 Base URL을 사용합니다

https://api.microcosm.money