项目 API

项目 API 提供了 8 个方法，用于管理项目。项目是 ONE 平台中的顶级组织单元——每个项目拥有自己的 API 密钥、功能开关、使用配额和 Webhook 配置。

方法

方法	参数	返回值	描述
getProjects()	--	ApiResponse<Project[]>	列出已认证用户拥有的所有项目。
createProject(input)	input: CreateProjectInput	ApiResponse<Project>	创建新项目并返回生成的 API 密钥。
getProject(projectId)	projectId: string	ApiResponse<Project>	返回单个项目的详细信息。
updateProject(projectId, input)	projectId: string, input: UpdateProjectInput	ApiResponse<Project>	更新项目的名称、描述或设置。
getProjectFeatures(projectId)	projectId: string	ApiResponse<ProjectFeatures>	返回项目已启用的功能开关。
updateProjectFeatures(projectId, features)	projectId: string, features: ProjectFeaturesUpdate	ApiResponse<ProjectFeatures>	启用或禁用项目的功能开关。
regenerateProjectApiKey(projectId)	projectId: string	ApiResponse<ProjectApiKeys>	重新生成项目的 API 密钥。之前的密钥立即失效。
deleteProject(projectId)	projectId: string	ApiResponse<{ deleted: boolean }>	永久删除项目及所有关联数据。

类型

Project

interface Project {
  id: string;
  name: string;
  description?: string;
  ownerId: string;
  /** Client ID for API authentication. */
  clientId: string;
  /** Masked secret key (only full key shown on creation / regeneration). */
  secretKey: string;
  plan: 'free' | 'starter' | 'pro' | 'enterprise';
  status: 'active' | 'suspended' | 'archived';
  /** Allowed origins for CORS (web apps). */
  allowedOrigins: string[];
  /** API calls used in the current billing period. */
  apiCallsUsed: number;
  /** API call limit for the current plan. */
  apiCallLimit: number;
  createdAt: string;
  updatedAt: string;
}

CreateProjectInput

interface CreateProjectInput {
  /** Project name (must be unique per user). */
  name: string;
  /** Optional description. */
  description?: string;
  /** Allowed origins for CORS. Default: ["*"]. */
  allowedOrigins?: string[];
}

UpdateProjectInput

interface UpdateProjectInput {
  name?: string;
  description?: string;
  allowedOrigins?: string[];
}

ProjectFeatures

interface ProjectFeatures {
  projectId: string;
  /** Feature flags and their enabled/disabled state. */
  features: {
    wallet: boolean;
    swap: boolean;
    onramp: boolean;
    offramp: boolean;
    aiTrading: boolean;
    forex: boolean;
    contracts: boolean;
    nfts: boolean;
    bills: boolean;
    staking: boolean;
    bridge: boolean;
    webhooks: boolean;
    /** Free price endpoints are always enabled. */
    price: true;
  };
  updatedAt: string;
}

ProjectFeaturesUpdate

interface ProjectFeaturesUpdate {
  wallet?: boolean;
  swap?: boolean;
  onramp?: boolean;
  offramp?: boolean;
  aiTrading?: boolean;
  forex?: boolean;
  contracts?: boolean;
  nfts?: boolean;
  bills?: boolean;
  staking?: boolean;
  bridge?: boolean;
  webhooks?: boolean;
}

ProjectApiKeys

interface ProjectApiKeys {
  projectId: string;
  /** New client ID. */
  clientId: string;
  /** New secret key (shown in full only at generation time). */
  secretKey: string;
  /** Timestamp when new keys become active. */
  generatedAt: string;
}

示例

列出项目

const res = await engine.getProjects();

if (res.success && res.data) {
  for (const proj of res.data) {
    console.log(`${proj.name} (${proj.id}) | Plan: ${proj.plan} | Usage: ${proj.apiCallsUsed}/${proj.apiCallLimit}`);
  }
}

创建项目

const res = await engine.createProject({
  name: 'My DApp',
  description: 'Production application',
  allowedOrigins: ['https://mydapp.com', 'https://staging.mydapp.com'],
});

if (res.success && res.data) {
  const proj = res.data;
  console.log('Project created:', proj.id);
  console.log('Client ID:', proj.clientId);
  console.log('Secret Key:', proj.secretKey);
  // Store these credentials securely
}

更新项目

const res = await engine.updateProject('proj_abc123', {
  name: 'My DApp (Production)',
  allowedOrigins: [
    'https://mydapp.com',
    'https://staging.mydapp.com',
    'https://preview.mydapp.com',
  ],
});

if (res.success && res.data) {
  console.log('Project updated:', res.data.name);
}

获取项目详情

const res = await engine.getProject('proj_abc123');

if (res.success && res.data) {
  const proj = res.data;
  console.log(`Name: ${proj.name}`);
  console.log(`Plan: ${proj.plan}`);
  console.log(`Status: ${proj.status}`);
  console.log(`Usage: ${proj.apiCallsUsed} / ${proj.apiCallLimit} calls`);
  console.log(`Origins: ${proj.allowedOrigins.join(', ')}`);
}

管理功能开关

// Check current features
const featRes = await engine.getProjectFeatures('proj_abc123');

if (featRes.success && featRes.data) {
  const f = featRes.data.features;
  console.log('Enabled features:');
  for (const [key, value] of Object.entries(f)) {
    if (value) console.log(`  - ${key}`);
  }
}

// Enable AI trading and forex
const updateRes = await engine.updateProjectFeatures('proj_abc123', {
  aiTrading: true,
  forex: true,
});

if (updateRes.success) {
  console.log('Features updated');
}

重新生成 API 密钥

const res = await engine.regenerateProjectApiKey('proj_abc123');

if (res.success && res.data) {
  console.log('New Client ID:', res.data.clientId);
  console.log('New Secret Key:', res.data.secretKey);
  console.log('Generated at:', res.data.generatedAt);
  // Update your environment variables with the new keys
  // The old keys are immediately invalidated
}

警告

重新生成 API 密钥会立即使之前的密钥失效。所有使用旧密钥的活跃客户端将收到 "unauthorized" 错误。请在生产环境重新生成密钥前先更新应用配置。

删除项目

const res = await engine.deleteProject('proj_abc123');

if (res.success && res.data?.deleted) {
  console.log('Project permanently deleted');
}

危险

删除项目是不可逆的操作。所有关联数据、Webhook 和使用历史将被永久删除。

项目生命周期

createProject() --> getProject() --> updateProject() --> deleteProject()
                                  |
                                  +--> getProjectFeatures() / updateProjectFeatures()
                                  |
                                  +--> regenerateProjectApiKey()

计划限制

功能	Free	Starter	Pro	Enterprise
API 调用 / 月	1,000	10,000	100,000	无限制
Webhook 数量	2	10	50	无限制
团队成员	1	3	10	无限制
AI Trading	--	是	是	是
Forex	--	--	是	是
优先支持	--	--	是	是

后续步骤

• Admin API -- 管理员级别的项目管理。
• Webhooks API -- 为项目配置事件通知。
• Engine Client -- 使用项目 API 密钥创建客户端。