返回开发者中心

参考文档

技术文档

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

三个 npm 包分层设计 — 认证 · 数据 · 挖矿 · 做市 · 领地 · 拍卖 · 借贷 · 碎片 · 投票 · 110+ Hooks · 30+ UI 组件

快速开始 (React / Next.js)

5 分钟内完成 SDK 集成

  1. 1安装: npm install @microcosmmoney/auth-react
  2. 2用 <MicrocosmAuthProvider> 包裹应用，传入 clientId
  3. 3创建 /auth/callback 页面放入 <AuthCallback />
  4. 4任意组件调用 useAuth() 获取用户状态

SDK 分层架构

portal-react

UI 菜单组件

auth-react

React Hooks

auth-core

核心引擎

portal-react → auth-react → auth-core

@microcosmmoney/auth-core

稳定版

Framework-agnostic OAuth 2.0 核心库 + ApiClient + MicrocosmAPI 静态方法 + 43+ TypeScript 类型

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

稳定版

React / Next.js 适配器，110+ 个 Hooks 覆盖认证、资产、挖矿、领地、拍卖、借贷、碎片、投票全模块

v2.2.1
安装命令
npm install @microcosmmoney/auth-react
特性
110+ React HooksProvider + 路由守卫Server 端工具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

稳定版

30+ Terminal 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 Exchange

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

基础 URL

所有 API 请求使用以下基础 URL

https://api.microcosm.money
APEX 顾问