概述
XMoFit API 提供了完整的 RESTful 接口，支持所有核心功能的程序化访问。
基础 URL
生产环境: https://api.xmofit.com/v1 测试环境: https://testnet-api.xmofit.com/v1
请求格式
所有请求必须包含以下 Header：
Content-Type: application/json X-API-Key: YOUR_API_KEY
⚠️ 速率限制
默认限制：1000 请求/小时
认证用户：5000 请求/小时
认证
POST
/auth/login
使用钱包签名登录
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| address | string | 是 | 钱包地址 |
| signature | string | 是 | 签名数据 |
| message | string | 是 | 签名消息 |
请求示例
{
"address": "0x1234567890123456789012345678901234567890",
"signature": "0xabcdef...",
"message": "Sign in to XMoFit at 2025-01-25T10:00:00Z"
}
响应示例
{
"success": true,
"data": {
"token": "eyJhbGciOiJIUzI1NiIs...",
"expires_at": "2025-01-26T10:00:00Z",
"user": {
"address": "0x1234567890123456789012345678901234567890",
"kyc_status": "verified"
}
}
}
运动数据 API
GET
/motion/daily
获取用户每日运动数据
查询参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| date | string | 否 | 日期 (YYYY-MM-DD)，默认今天 |
| address | string | 否 | 用户地址，默认当前用户 |
响应示例
{
"success": true,
"data": {
"date": "2025-01-25",
"steps": 12500,
"distance": 9.8,
"duration": 7200,
"calories": 520,
"earnings": {
"mft": 25.5,
"k_day": 1.2,
"multipliers": {
"nft": 1.5,
"streak": 1.1,
"social": 1.0
}
}
}
}
POST
/motion/submit
提交运动数据
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| steps | number | 是 | 步数 |
| distance | number | 是 | 距离（公里） |
| duration | number | 是 | 运动时长（秒） |
| proof | string | 是 | zk-Motion 证明 |
| device_id | string | 否 | 设备 ID |
NFT 系统 API
GET
/nft/collection/{address}
获取用户 NFT 收藏
路径参数
| 参数名 | 类型 | 说明 |
|---|---|---|
| address | string | 用户钱包地址 |
查询参数
| 参数名 | 类型 | 说明 |
|---|---|---|
| type | string | NFT 类型：shoes | apparel | accessories |
| page | number | 页码，默认 1 |
| limit | number | 每页数量，默认 20 |
错误代码
| 错误码 | HTTP 状态 | 说明 |
|---|---|---|
| AUTH_001 | 401 | 未提供认证信息 |
| AUTH_002 | 401 | 认证信息无效或已过期 |
| RATE_001 | 429 | 请求频率超过限制 |
| MOTION_001 | 400 | 运动数据格式错误 |
| MOTION_002 | 400 | zk-Motion 证明验证失败 |
| NFT_001 | 404 | NFT 不存在 |
| CHAIN_001 | 503 | 区块链服务暂时不可用 |
错误响应格式
{
"success": false,
"error": {
"code": "AUTH_002",
"message": "认证信息无效或已过期",
"details": "Token expired at 2025-01-25T10:00:00Z"
}
}