Reference Docs

Technical Documentation

Microcosm SDK v1.1 — 3 npm packages - 91 Hooks - 12 UI Components - 85 API Endpoints

Authentication Method

OAuth 2.0 Bearer Token

Access Token is automatically obtained after SDK login; all API requests must include this Token

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

SDK Auto-Handled

SDK has built-in Token management: auto-store, auto-refresh, re-login on expiry

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

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

Project API Key

For project server-side write operations, use X-API-Key and X-Project-ID headers

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

HMAC Signature

For high-security projects, sign requests with HMAC-SHA256. Time window ±300s

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

Three npm packages in layered design — auth · data · mining · market-making · territory · auction · lending · fragment · voting · 110+ Hooks · 30+ UI components

Quick Start (React / Next.js)

Complete SDK integration in 5 minutes

1Install: npm install @microcosmmoney/auth-react
2Wrap your app with <MicrocosmAuthProvider>, pass in clientId
3Create a /auth/callback page with <AuthCallback />
4Call useAuth() in any component to get user state

SDK Layered Architecture

portal-react

UI Menu Components

auth-react

React Hooks

auth-core

Core Engine

portal-react → auth-react → auth-core

@microcosmmoney/auth-core

Stable

Framework-agnostic OAuth 2.0 core library + ApiClient + MicrocosmAPI static methods + 43+ TypeScript types

v2.2.1

Install Command

npm install @microcosmmoney/auth-core

Features

OAuth 2.0 ClientAuto Token Refresh43+ Type DefinitionsStatic API Methods

Code Example

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 adapter with 110+ Hooks covering auth, assets, mining, territory, auction, lending, fragment, voting modules

v2.2.1

Install Command

npm install @microcosmmoney/auth-react

Features

110+ React HooksProvider + Route GuardServer-side UtilsIoC Provider Mode

Code Example

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+ Terminal UI components + Dashboard prebuilt components + navigation menu, compatible with shadcn/ui

v2.0.0

Install Command

npm install @microcosmmoney/portal-react

Features

30+ UI ComponentsNavigation Menu SystemData VisualizationCustom Configuration

Code Example

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)} />

Backend Token Exchange

OAuth 2.0 Confidential Client mode requires client_secret to complete Token exchange on the backend. SDK provides a one-line 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!,
})

Full Developer Documentation

Integration guide - API reference - Code examples — covering 91 Hooks and 85 API endpoints

Integration Guide GitHub

Base URL

All API requests use the following base URL

https://api.microcosm.money