开发者指南

API 参考手册 v1.1

Microcosm Open API 参考手册

版本: v1.1 | 日期: 2026-02-15

Base URL: https://api.microcosm.money

认证

OAuth 2.0 Bearer Token

Authorization: Bearer {access_token}

Token 通过 OAuth 登录获取，有效期 1 小时，SDK 自动刷新。

Scope 映射

OIDC Scope映射到说明
profileuser:read可访问用户资料 API
openid—OIDC 必需
email—获取邮箱声明

默认 scope ['openid', 'profile', 'email'] 即可访问所有用户端点。

项目 API Key（仅写操作）

X-API-Key: {api_key} X-API-Secret: {api_secret}

大多数第三方项目只需 OAuth Token，不需要 API Key。

响应格式

成功

json
{ "success": true, "data": { ... } }

列表 + 分页

json
{
  "success": true,
  "data": [...],
  "pagination": { "total": 100, "page": 1, "per_page": 20 }
}

错误 (RFC 7807)

json
{
  "type": "https://api.microcosm.money/errors/insufficient-scope",
  "title": "Insufficient Scope",
  "status": 403,
  "detail": "The access token does not have the required scope."
}

公开端点（无需认证）

MCC Token

方法端点说明
GET/v1/mcc/priceMCC 当前价格
GET/v1/mcc/statsMCC 全局统计（总量、流通量、持有者数）
GET/v1/mcc/balance/{address}指定地址 MCC 余额（传钱包地址）

GET /v1/mcc/balance/{address} 响应

json
{
  "success": true,
  "data": {
    "balance": 13.92,
    "raw_balance": 13921825942,
    "decimals": 9,
    "symbol": "MCC",
    "mint": "MCCpDtigJLYnfGe1fW5xrSA8AXo6AeAj8ECE7wVqP5e"
  }
}

注意: 此端点需要在 URL 中传递钱包地址。如果使用 SDK 的 useMCC() Hook，SDK 会自动调用需认证的 /v1/mcc/balance（不带地址），通过 Token 自动识别用户钱包。两个端点返回格式相同。

GET /v1/mcc/price 响应

json
{
  "success": true,
  "data": {
    "price": 1.1,
    "price_change_24h": null,
    "volume_24h": null,
    "market_cap": null,
    "source": "redis",
    "updated_at": "2026-02-14T12:00:00Z",
    "buyback_price": 1.155,
    "premium_rate": 0.05
  }
}
字段类型说明
pricenumber当前价格 (USDC)
price_change_24hnumber | null24h 变动（暂未实现）
volume_24hnumber | null24h 交易量（暂未实现）
market_capnumber | null市值（暂未实现）
sourcestring数据源: "redis" | "onchain" | "database"
updated_atstringISO 8601 时间
buyback_pricenumber回购价格 = price × (1 + premium_rate)
premium_ratenumber溢价率（0.05 = 5%）

MCD Token

方法端点说明
GET/v1/mcd/statsMCD 全局统计

钱包

方法端点说明
GET/v1/wallets/{address}/tokens指定钱包的完整代币组合（SOL/MCC/USDT）

GET /v1/wallets/{address}/tokens 响应

json
{
  "success": true,
  "data": {
    "sol_balance": 0.516,
    "mcc_balance": 125.5,
    "usdt_balance": 10.0,
    "usdc_balance": 0.0
  }
}

挖矿

方法端点说明
GET/v1/mining/global-stats全局挖矿统计
GET/v1/mining/ratio挖矿比率/阶段/速率

GET /v1/mining/ratio 响应

json
{
  "success": true,
  "data": {
    "current_phase": 1,
    "total_mined": 1500000.0,
    "phase_limit": 100000000,
    "mining_rate": "1:1",
    "price_multiplier": 2.0
  }
}

轮回池

方法端点说明
GET/v1/reincarnation/pool池子余额（USDC/USDT/MCC Vault）
GET/v1/reincarnation/buyback-price当前回购价格
POST/v1/reincarnation/quote回购报价计算
GET/v1/reincarnation/mining-history近 N 天挖矿聚合数据
GET/v1/reincarnation/holders持有者分布统计

POST /v1/reincarnation/quote 请求

json
{ "mcc_amount": 10.0 }

POST /v1/reincarnation/quote 响应

json
{
  "success": true,
  "data": {
    "mcc_amount": 10.0,
    "market_price": 1.1,
    "buyback_price": 1.155,
    "usdc_amount": 11.55,
    "premium_amount": 0.55
  }
}
字段类型说明
mcc_amountnumber输入的 MCC 数量
market_pricenumber当前市场价
buyback_pricenumber回购价格（市场价 × 1.05）
usdc_amountnumber可获得的稳定币总额
premium_amountnumber溢价部分

Dashboard

方法端点说明
GET/v1/dashboard/market市场概览（价格、24h 变动、交易量、流动性）
GET/v1/dashboard/platform平台统计（用户数、挖矿总量）
GET/v1/dashboard/stats/users用户等级分布统计
GET/v1/dashboard/stats/territories领地统计
GET/v1/dashboard/stats/mining-history每日挖矿聚合（?days=30，最大 90）

GET /v1/dashboard/stats/users 响应

json
{
  "success": true,
  "data": {
    "total_users": 1500,
    "by_level": {
      "recruit": 500,
      "prospect": 700,
      "miner": 300
    }
  }
}

科技树

方法端点说明
GET/v1/tech-tree/config科技树配置（节点列表、加成规则）

拍卖

方法端点说明
GET/v1/auction-solana/config拍卖配置
GET/v1/auction-solana/active活跃拍卖列表
GET/v1/auction-solana/auction/{id}拍卖详情
GET/v1/auction-solana/auction/{id}/bids竞价历史

领地 NFT

方法端点说明
GET/v1/territory/collectionNFT Collection 配置
GET/v1/territory/nft/{mint}NFT 元数据
GET/v1/territory/unit/{unit_id}/nft领地单位关联 NFT

Fragment

方法端点说明
GET/v1/fragment/config碎片化配置
GET/v1/fragment/vaultsVault 列表
GET/v1/fragment/vault/{id}Vault 详情

Lending

方法端点说明
GET/v1/lending/pool借贷池信息
GET/v1/lending/stats借贷池统计

用户端点（需 OAuth Token）

钱包管理

方法端点说明
GET/v1/wallets用户绑定的所有钱包列表

GET /v1/wallets 响应

json
{
  "success": true,
  "data": {
    "wallets": [
      {
        "wallet_address": "GhXBdLw8K9V1KKrQY5egGERF8vBNPDDeLXwAKqh8TAxJ",
        "wallet_type": "solana",
        "is_primary": true,
        "created_at": "2026-01-15T08:30:00Z"
      }
    ],
    "total": 1
  }
}
字段类型说明
wallet_addressstring钱包地址
wallet_typestring钱包类型（"solana"）
is_primaryboolean是否主钱包
created_atstring绑定时间 (ISO 8601)

MCC Token

方法端点说明
GET/v1/mcc/balance当前用户 MCC 余额（多钱包聚合，SDK 用这个）
GET/v1/mcc/transactionsMCC 交易记录（分页）
GET/v1/mcc/locks用户 MCC 锁仓列表
GET/v1/mcc/historyMCC 综合历史（挖矿/回购/转账，?tx_type=mining|buyback|transfer|all）

GET /v1/mcc/balance 响应

SDK 的 useMCC() Hook 调用此端点。服务端通过 OAuth Token 识别用户 → 查数据库获取钱包地址 → 查链上余额。无需前端传递钱包地址。 如需按地址查询（不登录），使用公开端点 /v1/mcc/balance/{address}。

json
{
  "success": true,
  "data": {
    "balance": 125.5,
    "raw_balance": 125500000000,
    "decimals": 9,
    "symbol": "MCC",
    "wallet_address": "GhXBdLw8K9V1KKrQY5egGERF8vBNPDDeLXwAKqh8TAxJ",
    "wallets": [
      { "wallet_address": "GhXB...TAxJ", "is_primary": true, "balance": 125.5, "raw_balance": 125500000000 }
    ]
  }
}
字段类型说明
balancenumberMCC 余额（人类可读，多钱包聚合）
raw_balancenumber原始余额（9 位精度）
decimalsnumber精度位数（固定 9）
symbolstring代币符号
wallet_addressstring | null主钱包地址
walletsarray各钱包分别余额

GET /v1/mcc/locks 响应

json
{
  "success": true,
  "data": {
    "locks": [
      {
        "lock_id": "lock_001",
        "amount": 1000.0,
        "reason": "mining_commitment",
        "lock_start": "2026-01-01T00:00:00Z",
        "lock_end": "2026-07-01T00:00:00Z",
        "status": "active"
      }
    ],
    "total": 1
  }
}
字段类型说明
lock_idstring锁仓 ID
amountnumber锁仓数量 (MCC)
reasonstring锁仓原因
lock_startstring开始时间 (ISO 8601)
lock_endstring | null结束时间
statusstring状态: "active" | "released" | "expired"

GET /v1/mcc/history 参数

参数类型默认说明
tx_typestring"all"交易类型: "mining" | "buyback" | "transfer" | "all"
pageint1页码
page_sizeint20每页数量（最大 100）

GET /v1/mcc/history 响应

json
{
  "success": true,
  "data": {
    "records": [
      {
        "mcc_amount": 5.0,
        "stablecoin_amount": 11.0,
        "stablecoin": "USDT",
        "tx_signature": "5xYk...abc",
        "type": "mining",
        "wallet_address": "GhXBdLw8...",
        "created_at": "2026-02-14T08:30:00Z"
      }
    ],
    "total": 42,
    "page": 1,
    "page_size": 20
  }
}
字段类型说明
mcc_amountnumberMCC 数量
stablecoin_amountnumber稳定币金额
stablecoinstring币种
tx_signaturestringSolana 交易签名
typestring类型: "mining" | "buyback" | "transfer"
wallet_addressstring | null钱包地址
created_atstring时间 (ISO 8601)

MCD Token

方法端点说明
GET/v1/mcd/balance当前用户 MCD 余额
GET/v1/mcd/transactionsMCD 交易记录（分页 + 类型筛选）
GET/v1/mcd/rewardsMCD 每日奖励记录（分页 + 日期筛选）

GET /v1/mcd/transactions 参数

参数类型默认说明
pageint1页码
page_sizeint20每页数量（最大 100）
typestring—交易类型筛选: "mining_reward" | "vault_distribution" | "transfer"

GET /v1/mcd/transactions 响应

json
{
  "success": true,
  "data": {
    "transactions": [
      {
        "tx_type": "vault_distribution",
        "amount": 50.0,
        "from": "S-00001 Vault",
        "to": "user_wallet",
        "created_at": "2026-02-14T00:00:00Z"
      }
    ],
    "total": 156,
    "page": 1,
    "page_size": 20
  }
}

GET /v1/mcd/rewards 参数

参数类型默认说明
pageint1页码
page_sizeint20每页数量（最大 100）
start_datestring—开始日期 (YYYY-MM-DD)
end_datestring—结束日期 (YYYY-MM-DD)

GET /v1/mcd/rewards 响应

json
{
  "success": true,
  "data": {
    "rewards": [
      {
        "date": "2026-02-14",
        "amount": 12.5,
        "source": "vault_distribution",
        "territory_id": "S-00001"
      }
    ],
    "total_received": 450.0,
    "page": 1,
    "page_size": 20
  }
}

用户

方法端点说明
GET/v1/users/me当前用户信息
GET/v1/users/me/profile用户详细资料
PATCH/v1/users/me/profile更新资料（display_name，1-50 字符）
POST/v1/users/me/avatar上传头像（multipart，≤2MB，jpg/png/gif/webp）
GET/v1/users/{uid}指定用户公开信息

挖矿

方法端点说明
GET/v1/mining/records挖矿记录（分页）
GET/v1/mining/stats用户挖矿统计
GET/v1/mining/distribution伴生矿分配历史（分页）
GET/v1/mining/config挖矿合约配置
GET/v1/mining/history挖矿详细历史（x402 记录，分页）
POST/v1/mining/request创建挖矿请求（OAuth）
POST/v1/mining/confirm确认挖矿（提交链上交易签名）
POST/v1/mining/public/request公开挖矿请求（无需 OAuth，仅钱包地址）
POST/v1/mining/public/verify验证公开挖矿交易

GET /v1/mining/records 响应

json
{
  "success": true,
  "data": {
    "records": [
      {
        "mcc_amount": 3.0,
        "paid_amount": 6.6,
        "stablecoin": "USDT",
        "tx_signature": "5xYk...abc",
        "mined_at": "2026-02-14T08:30:00Z"
      }
    ],
    "total": 7,
    "page": 1,
    "page_size": 20
  }
}
字段类型说明
mcc_amountnumber挖矿获得 MCC 数量
paid_amountnumber支付稳定币金额
stablecoinstring支付币种: "USDC" | "USDT"
tx_signaturestringSolana 交易签名
mined_atstring | null挖矿时间 (ISO 8601)

分页参数: page (默认 1) / page_size (默认 20, 最大 100)

GET /v1/mining/stats 响应

json
{
  "success": true,
  "data": {
    "total_mined": 125.5,
    "total_paid": 276.1,
    "mining_count": 42,
    "today_mined": 3.0,
    "last_30d_mined": 85.2,
    "active_days_30d": 18,
    "last_mined_at": "2026-02-14T08:30:00Z"
  }
}
字段类型说明
total_minednumber累计挖矿获得 MCC
total_paidnumber累计支付稳定币
mining_countnumber挖矿次数
today_minednumber今日挖矿获得 MCC
last_30d_minednumber近 30 天挖矿获得 MCC
active_days_30dnumber近 30 天活跃挖矿天数
last_mined_atstring | null最后挖矿时间 (ISO 8601)

GET /v1/mining/distribution 参数

参数类型默认说明
pageint1页码
page_sizeint20每页数量（最大 100）

GET /v1/mining/distribution 响应

json
{
  "success": true,
  "data": {
    "records": [
      {
        "user_mcc": 3.0,
        "team_mcc": 0.6,
        "magistrate_mcc": 0.6,
        "vault_mcd": 1.8,
        "source": "mining",
        "territory_id": "S-00001",
        "tx_signature": "5xYk...abc",
        "created_at": "2026-02-14T08:30:00Z"
      }
    ],
    "total": 42,
    "page": 1,
    "page_size": 20
  }
}
字段类型说明
user_mccnumber用户获得 MCC
team_mccnumber团队伴生矿 MCC
magistrate_mccnumber政务官伴生矿 MCC
vault_mcdnumber金库伴生矿 MCD
sourcestring来源
territory_idstring | null领地 ID
tx_signaturestring交易签名
created_atstring时间 (ISO 8601)

POST /v1/mining/request 请求

json
{
  "mcc_amount": 5.0,
  "stablecoin": "USDT",
  "wallet_address": "GhXBdLw8..."
}
字段类型必填说明
mcc_amountnumber✅挖矿 MCC 数量
stablecoinstring—支付币种（默认 "USDT"）
wallet_addressstring✅用户钱包地址

POST /v1/mining/request 响应

json
{
  "success": true,
  "data": {
    "request_id": "req_abc123",
    "mcc_amount": 5.0,
    "usdc_amount": 11.0,
    "mining_price": 2.2,
    "stablecoin": "USDT",
    "payment_address": "MCWe3gEY...",
    "expires_at": "2026-02-15T12:30:00Z"
  }
}

POST /v1/mining/confirm 请求

json
{
  "request_id": "req_abc123",
  "tx_signature": "5xYk...abc",
  "mcc_amount": 5.0,
  "usdc_amount": 11.0,
  "stablecoin_type": "USDT"
}
字段类型必填说明
request_idstring✅mining/request 返回的 ID
tx_signaturestring✅链上支付交易签名
mcc_amountnumber✅MCC 数量
usdc_amountnumber✅稳定币金额
stablecoin_typestring—币种（默认 "USDT"）

POST /v1/mining/public/request 请求

无需 OAuth，仅需钱包地址。

json
{
  "wallet_address": "GhXBdLw8...",
  "mcc_amount": 1.0,
  "stablecoin": "USDT"
}

POST /v1/mining/public/verify 请求

json
{
  "request_id": "req_abc123",
  "tx_signature": "5xYk...abc"
}

GET /v1/mining/config 响应

json
{
  "success": true,
  "data": {
    "program_id": "REn8oKyydvjRsistZ2cVi6tksPubvR3bEuLdVTyGknb",
    "pool_address": "...",
    "mcc_mint": "MCCpDtigJLYnfGe1fW5xrSA8AXo6AeAj8ECE7wVqP5e",
    "usdt_mint": "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB",
    "usdc_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "distribution_ratios": { "user": 50, "team": 10, "magistrate": 10, "vault": 30 },
    "min_amount": 0.01,
    "max_amount": 100000
  }
}

轮回回购（用户相关）

方法端点说明
GET/v1/reincarnation/user-history用户回购记录（分页）
GET/v1/reincarnation/config轮回合约配置（Program/Vault 地址等）
GET/v1/reincarnation/cycle-history月度轮回执行历史
POST/v1/reincarnation/record记录链上回购交易（用户签名后提交）

GET /v1/reincarnation/user-history 响应

json
{
  "success": true,
  "data": {
    "records": [
      {
        "mcc_amount": 10.0,
        "usdc_amount": 11.55,
        "stablecoin": "USDT",
        "tx_signature": "3kLm...xyz",
        "buyback_price": 1.155,
        "created_at": "2026-02-14T10:00:00Z"
      }
    ],
    "total": 5,
    "page": 1,
    "page_size": 20
  }
}
字段类型说明
mcc_amountnumber回购 MCC 数量
usdc_amountnumber获得稳定币数量
stablecoinstring稳定币类型: "USDC" | "USDT"
tx_signaturestring交易签名
buyback_pricenumber | null回购时价格
created_atstring回购时间 (ISO 8601)

POST /v1/reincarnation/record 请求

用户在前端构建 execute_buyback 指令并签名后，将交易信息提交到后端记录。

json
{
  "tx_signature": "3kLm...xyz",
  "wallet_address": "GhXBdLw8...",
  "mcc_amount": 10.0,
  "usdc_amount": 11.55,
  "stablecoin": "USDT"
}
字段类型必填说明
tx_signaturestring✅Solana 交易签名
wallet_addressstring✅用户钱包地址
mcc_amountnumber✅回购 MCC 数量
usdc_amountnumber✅获得稳定币数量
stablecoinstring—币种（默认 "USDT"）

409 Conflict: 重复提交同一 tx_signature

GET /v1/reincarnation/config 响应

json
{
  "success": true,
  "data": {
    "program_id": "REn8oKyydvjRsistZ2cVi6tksPubvR3bEuLdVTyGknb",
    "pool_address": "...",
    "mcc_vault": "...",
    "usdc_vault": "...",
    "usdt_vault": "...",
    "min_buyback": 0.01,
    "max_buyback": 100000,
    "premium_rate": 0.05
  }
}

GET /v1/reincarnation/cycle-history 响应

json
{
  "success": true,
  "data": [
    {
      "cycle_id": 1,
      "executed_at": "2026-02-01T00:00:00Z",
      "mcc_returned": 150.5,
      "mcd_returned": 4500.0,
      "status": "completed"
    }
  ]
}

领地管理

方法端点说明
GET/v1/territories领地列表（筛选: unit_type / parent_id，分页）
GET/v1/territories/summary领地汇总统计（总数/成员/金库）
GET/v1/territories/{id}领地详情
GET/v1/territories/{id}/stats领地统计（成员/容量/金库）
GET/v1/territories/{id}/members领地成员列表（分页）
GET/v1/territories/{id}/income-chart收入图表（`?period=7d
GET/v1/territories/{id}/kpi-historyKPI 历史
GET/v1/territories/{id}/member-ranking成员 MCD 排名（分页）
PUT/v1/territories/{id}更新领地信息（描述/图片）
PUT/v1/territories/{id}/name更新领地名称（90 天冷却期）

GET /v1/territories 参数

参数类型默认说明
unit_typestring—领地类型: "station" | "matrix" | "sector" | "system"
parent_idstring—父级领地 ID
pageint1页码
page_sizeint20每页数量（最大 100）

GET /v1/territories/{id}/stats 响应

json
{
  "success": true,
  "data": {
    "territory_id": "S-00001",
    "unit_type": "station",
    "member_count": 45,
    "capacity": 1000,
    "vault_balance": 5000.0,
    "daily_distribution": 50.0,
    "magistrate_uid": "abc123"
  }
}

GET /v1/territories/{id}/income-chart 参数

参数类型默认说明
periodstring"30d"时间范围: "7d" | "30d" | "90d"

PUT /v1/territories/{id} 请求

json
{
  "description": "Updated description",
  "image_url": "https://example.com/image.png"
}
字段类型必填说明
unit_namestring—领地名称
descriptionstring—领地描述
image_urlstring—领地图片 URL

所有字段均为可选，仅更新传入的字段。

PUT /v1/territories/{id}/name 请求

json
{ "name": "New Station Name" }
字段类型必填说明
namestring✅新名称

查询参数: ?force=true（仅管理员可跳过 90 天冷却期）

409 Conflict: 90 天内已改名

社区投票

方法端点说明
GET/v1/voting/proposals提案列表（`?status=active
GET/v1/voting/proposals/{id}提案详情 + 投票结果
GET/v1/voting/power用户投票权
POST/v1/voting/proposals创建提案
POST/v1/voting/proposals/{id}/vote投票

GET /v1/voting/proposals 参数

参数类型默认说明
statusstring—提案状态: "active" | "closed" | "pending"
pageint1页码
page_sizeint20每页数量（最大 100）

GET /v1/voting/proposals/{id} 响应

json
{
  "success": true,
  "data": {
    "id": "prop_001",
    "title": "增加 Station 容量",
    "description": "将 Station 容量从 1000 提升到 2000",
    "proposal_type": "standard",
    "status": "active",
    "options": ["赞成", "反对"],
    "votes": [150, 30],
    "total_votes": 180,
    "voting_hours": 72,
    "created_at": "2026-02-10T00:00:00Z",
    "ends_at": "2026-02-13T00:00:00Z",
    "creator_uid": "abc123"
  }
}

GET /v1/voting/power 响应

json
{
  "success": true,
  "data": {
    "vote_power": 10,
    "source": "mcc_holding",
    "details": {
      "base_power": 1,
      "mcc_bonus": 5,
      "level_bonus": 4
    }
  }
}

POST /v1/voting/proposals 请求

json
{
  "title": "提案标题",
  "description": "提案详细描述",
  "proposal_type": "standard",
  "voting_hours": 72,
  "options": ["赞成", "反对"]
}
字段类型必填说明
titlestring✅标题（1-200 字符）
descriptionstring✅描述
proposal_typestring—类型（默认 "standard"）
voting_hoursint—投票时长（1-720 小时，默认 72）
optionsstring[]✅选项（2-10 个）

POST /v1/voting/proposals/{id}/vote 请求

json
{
  "option_index": 0,
  "vote_count": 1
}
字段类型必填说明
option_indexint✅选项索引（从 0 开始）
vote_countint—投票数量（默认 1）

拍卖（用户相关）

方法端点说明
GET/v1/auction-solana/bids/{wallet}用户竞价记录（按钱包地址）
GET/v1/auction-solana/auctions/{wallet}用户创建的拍卖
GET/v1/auction-solana/my-bids我的竞价（OAuth 认证）
POST/v1/auction-solana/auction/{id}/bid出价
POST/v1/auction-solana/bid/cancel/prepare准备取消竞价（返回链上交易参数）
GET/v1/auction-solana/history拍卖历史记录

POST /v1/auction-solana/auction/{id}/bid 请求

json
{ "bid_amount": 100.0 }

POST /v1/auction-solana/bid/cancel/prepare 请求

json
{ "auction_id": 42 }

返回链上交易构建参数（Vault 地址、退款金额等），前端需据此构建 Solana 交易并由用户签名。

GET /v1/auction-solana/history 响应

json
{
  "success": true,
  "data": [
    {
      "auction_id": 42,
      "unit_name": "Station Alpha",
      "winner_wallet": "GhXBdLw8...",
      "winning_bid": 150.0,
      "status": "completed",
      "ended_at": "2026-02-10T00:00:00Z"
    }
  ]
}

组织

方法端点说明
GET/v1/organizations组织列表（分页）
GET/v1/organizations/{id}组织详情
GET/v1/organizations/{id}/members组织成员（分页）
GET/v1/organizations/{id}/stats组织统计

科技树

方法端点说明
GET/v1/tech-tree/user用户科技树进度
GET/v1/tech-tree/bonus用户科技树加成（bonus_multiplier）
POST/v1/tech-tree/unlock解锁科技树节点
POST/v1/tech-tree/upgrade升级科技树节点

Dashboard

方法端点说明
GET/v1/dashboard/user/{wallet}用户汇总数据

领地 NFT（用户相关）

方法端点说明
GET/v1/territory/nfts/{wallet}用户 NFT 列表

Fragment（用户相关）

方法端点说明
GET/v1/fragment/holdings/{wallet}用户持仓
GET/v1/fragment/vault/{id}/holdersVault 持仓分布

Lending（用户相关）

方法端点说明
GET/v1/lending/position/{wallet}用户仓位
GET/v1/lending/loans/{wallet}用户贷款列表
GET/v1/lending/loan/{wallet}/{loan_id}贷款详情
GET/v1/lending/lp-balance/{wallet}LP Token 余额
POST/v1/lending/calculate-interest计算利息
POST/v1/lending/estimate-borrow-cost估算借款成本

写操作端点（需项目 API Key）

大多数第三方项目不需要这些端点。仅在项目需要代替用户执行链上操作时使用。

方法端点说明
POST/v1/mining/submit-activity提交挖矿活动
POST/v1/funds/lock锁定资金
POST/v1/funds/unlock解锁资金
POST/v1/transfer/request请求转账
GET/v1/transfer/{transfer_id}查询转账状态
POST/v1/transfer/{transfer_id}/cancel取消转账

项目管理端点

方法端点说明
POST/v1/projects/register注册项目
GET/v1/projects项目列表
GET/v1/projects/{id}项目详情
PATCH/v1/projects/{id}更新项目信息
POST/v1/projects/{id}/regenerate-secret重新生成密钥
POST/v1/projects/{id}/domains添加 CORS 域名
GET/v1/projects/{id}/domains查看域名列表
DELETE/v1/projects/{id}/domains/{domain_id}移除域名

OAuth 端点（microcosm.money）

方法端点说明
GET/login?oauth=true&...授权页面
POST/api/oauth/tokenToken 交换 / 刷新
POST/api/oauth/introspectToken 验证

Token Exchange 请求

json
POST /api/oauth/token
{
  "grant_type": "authorization_code",
  "code": "<code>",
  "redirect_uri": "https://your-app.com/auth/callback",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}

Token Exchange 响应

json
{
  "access_token": "eyJhbGci...",
  "refresh_token": "dGhpcyBp...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email",
  "user": {
    "uid": "abc123",
    "email": "user@example.com",
    "display_name": "User Name",
    "role": "user",
    "level": "miner",
    "title": "commander",
    "station_id": 1
  }
}

Token Introspect 响应

json
{
  "active": true,
  "uid": "abc123",
  "email": "user@example.com",
  "role": "user",
  "level": "miner",
  "scope": "openid profile email",
  "client_id": "doublehelix",
  "exp": 1703577600,
  "iat": 1703574000
}

错误码

错误码HTTP说明
invalid_request400请求参数错误
invalid_client401client_id / client_secret 错误
invalid_token401Token 无效
token_expired401Token 已过期
insufficient_scope403权限不足
user_not_found404用户不存在
rate_limit_exceeded429请求过频
server_error500服务器错误

速率限制

类型限制
免费开发者100 次/分钟
标准项目1,000 次/分钟
企业项目10,000 次/分钟

响应头

X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 998 X-RateLimit-Reset: 1704700800 Retry-After: 60 // 仅限制时返回

分页

列表端点支持 page 和 page_size（或 per_page）参数：

GET /v1/mcd/transactions?page=2&page_size=20

响应中包含分页信息：

json
{
  "success": true,
  "data": {
    "records": [...],
    "total": 156,
    "page": 2,
    "page_size": 20
  }
}

用户类型定义

typescript
interface User {
  uid: string
  email: string
  displayName?: string
  avatarUrl?: string
  role: 'admin' | 'user' | 'agent'
  level?: 'recruit' | 'prospect' | 'miner'
  title?: 'commander' | 'pioneer' | 'warden' | 'admiral' | null
  stationId?: number
  emailVerified?: boolean
}
字段说明
role系统角色
level用户级别（Recruit → Prospect → Miner）
title职级头衔（基于 NFT 持有）
stationId所属 Station ID（Miner 才有）

端点总览

公开端点（21 个）

#方法端点分类
1GET/v1/mcc/priceMCC
2GET/v1/mcc/statsMCC
3GET/v1/mcc/balance/{address}MCC
4GET/v1/mcd/statsMCD
5GET/v1/wallets/{address}/tokens钱包
6GET/v1/mining/global-stats挖矿
7GET/v1/mining/ratio挖矿
8GET/v1/mining/config挖矿
9POST/v1/mining/public/request挖矿
10POST/v1/mining/public/verify挖矿
11GET/v1/reincarnation/pool轮回
12GET/v1/reincarnation/buyback-price轮回
13POST/v1/reincarnation/quote轮回
14GET/v1/reincarnation/mining-history轮回
15GET/v1/reincarnation/holders轮回
16GET/v1/reincarnation/config轮回
17GET/v1/dashboard/marketDashboard
18GET/v1/dashboard/platformDashboard
19GET/v1/dashboard/stats/usersDashboard
20GET/v1/dashboard/stats/territoriesDashboard
21GET/v1/dashboard/stats/mining-historyDashboard

认证端点（45+ 个）

#方法端点分类
1GET/v1/wallets钱包
2GET/v1/mcc/balanceMCC
3GET/v1/mcc/transactionsMCC
4GET/v1/mcc/locksMCC
5GET/v1/mcc/historyMCC
6GET/v1/mcd/balanceMCD
7GET/v1/mcd/transactionsMCD
8GET/v1/mcd/rewardsMCD
9GET/v1/mining/records挖矿
10GET/v1/mining/stats挖矿
11GET/v1/mining/distribution挖矿
12GET/v1/mining/history挖矿
13POST/v1/mining/request挖矿
14POST/v1/mining/confirm挖矿
15GET/v1/reincarnation/user-history轮回
16GET/v1/reincarnation/cycle-history轮回
17POST/v1/reincarnation/record轮回
18GET/v1/territories领地
19GET/v1/territories/summary领地
20GET/v1/territories/{id}领地
21GET/v1/territories/{id}/stats领地
22GET/v1/territories/{id}/members领地
23GET/v1/territories/{id}/income-chart领地
24GET/v1/territories/{id}/kpi-history领地
25GET/v1/territories/{id}/member-ranking领地
26PUT/v1/territories/{id}领地
27PUT/v1/territories/{id}/name领地
28GET/v1/voting/proposals投票
29GET/v1/voting/proposals/{id}投票
30GET/v1/voting/power投票
31POST/v1/voting/proposals投票
32POST/v1/voting/proposals/{id}/vote投票
33GET/v1/auction-solana/active拍卖
34GET/v1/auction-solana/my-bids拍卖
35GET/v1/auction-solana/history拍卖
36POST/v1/auction-solana/auction/{id}/bid拍卖
37POST/v1/auction-solana/bid/cancel/prepare拍卖
38GET/v1/users/me用户
39GET/v1/users/me/profile用户
40PATCH/v1/users/me/profile用户
41POST/v1/users/me/avatar用户
42POST/v1/auction-solana/create拍卖(创建)
43POST/v1/auction-solana/auction/{id}/end拍卖(管理员结束)
44GET/v1/auction-solana/auction/{id}/bids拍卖(出价列表)
45GET/v1/auction-solana/config拍卖(全局配置)
46GET/v1/organizations/tree组织(树形结构)
47GET/v1/organizations/summary组织(全局统计)
48POST/v1/territories/{id}/join领地(加入)
49POST/v1/territories/{id}/leave领地(离开)
50GET/v1/territories/queue领地(分配队列)
51GET/v1/territories/{id}/detailed-stats领地(详细统计)
52GET/v1/territories/{id}/name-status领地(名称状态)
53GET/v1/territories/{id}/distribution-plan领地(分配方案)
54PUT/v1/territories/{id}/distribution-plan领地(设置分配方案)
55GET/v1/territories/manager/income领地(政务官收入)
56GET/v1/territories/team/custody领地(代管钱包)
57POST/v1/territories/{id}/nft/mint领地 NFT(铸造)
58POST/v1/territories/{id}/nft/transfer领地 NFT(转移)
59POST/v1/territories/{id}/nft/burn领地 NFT(销毁)
60GET/v1/territory/collection领地 NFT(集合)
61GET/v1/tech-tree/config科技树(配置)
62GET/v1/tech-tree/bonus科技树(加成)
63POST/v1/tech-tree/unlock科技树(解锁)
64POST/v1/tech-tree/upgrade科技树(升级)
65GET/v1/notifications通知(列表)
66POST/v1/notifications/{id}/read通知(标记已读)
67POST/v1/notifications/read-all通知(全部已读)
68POST/v1/proposals/{id}/settle提案(管理员结算)
69GET/v1/fragment/vaults碎片(金库列表)
70GET/v1/fragment/vault/{id}碎片(金库详情)
71GET/v1/fragment/config碎片(配置)
72GET/v1/lending/pool借贷(池信息)
73GET/v1/lending/position/{wallet}借贷(仓位)
74GET/v1/lending/stats借贷(统计)
75GET/v1/reincarnation/holdersMCC 持有者
76GET/v1/reincarnation/mining-historyMCC 铸造趋势
77GET/v1/dashboard/marketDashboard(市场)
78GET/v1/dashboard/platformDashboard(平台)
79GET/v1/dashboard/stats/mining-historyDashboard(挖矿趋势)
80GET/v1/dashboard/stats/usersDashboard(用户统计)
81GET/v1/dashboard/stats/territoriesDashboard(领地统计)
82POST/v1/mining/request挖矿(请求)
83POST/v1/mining/confirm挖矿(确认)
84POST/v1/reincarnation/quote回购(报价)
85POST/v1/reincarnation/record回购(记录)

交互式文档

URL说明
https://api.microcosm.money/docsSwagger UI
https://api.microcosm.money/redocReDoc
https://api.microcosm.money/openapi.jsonOpenAPI 3.1 规范
上一页
第三方接入指南 v1.1
下一页
代码示例 v1.1
询问 AI
询问 AI