Finatic 客户端 SDK

浏览器 SDK 将 Finatic 连接和账户第一数据嵌入到 您的前端。公司 API 密钥从不属于此软件包。 您的后端( Server SDK) 薄荷能一次性地得到一个符; 浏览器只接收该符.

安装

npm install @finatic/client

快开始

import { FinaticConnect, isPortalLifecycleEventPayload } from '@finatic/client';

const finatic = await FinaticConnect.init('one-time-token', undefined, {
  apiEnvironment: 'sandbox', // or 'live'
});

await finatic.openPortal({
  mode: 'dark',
  onSuccess: (userId) => {
    // OTP / session ready. The user has not necessarily granted an account yet.
    console.log('Portal user linked:', userId);
  },
  onEvent: async (eventName, payload) => {
    if (eventName !== 'account.grant.created') return;
    const grant = payload as { accountId?: string };
    const accounts = await finatic.v1.listAccounts({ includeSyncStatus: true });
    const ready = accounts.success?.data ?? [];
    console.log('Grant created for', grant.accountId, 'accounts', ready);
  },
});

openPortal 必须使用 对象 要收到的表格 onEvent. 职位超载没有赠款活动.

连接解除时嵌入应用程序控制 。 打电话 closePortal() 从主机 UI 或处理可选的门户事件后; 重复呼叫为 在没有门户打开时安全无事:

await finatic.openPortal({
  onEvent: (eventName) => {
    if (eventName === 'account.grant.created') {
      finatic.closePortal();
    }
  },
  onClose: () => {
    // Runs once for either the portal close control or closePortal().
  },
});

门户认证和连接准备

onSuccess(userId) 表示门户会话认证. 这并不意味着 中间连接已经存在或连接器数据已经准备好 。 连接 schema v1 通过键入方式发布后期的转换 portal.lifecycle 事件:

await finatic.openPortal({
  onEvent: (eventName, payload) => {
    if (eventName !== 'portal.lifecycle' || !isPortalLifecycleEventPayload(payload)) return;

    switch (payload.stage) {
      case 'portal_authenticated':
        console.log('Portal authenticated', payload.userId);
        break;
      case 'broker_connection_created':
        console.log('Connection persisted', payload.connectionId);
        break;
      case 'push_agent_state_changed':
        // Only LIVE_DATA and STALE_LIVE_DATA can report dataReady: true.
        console.log(payload.state, payload.dataReady ?? 'not asserted');
        break;
    }
  },
});

SDK只有在符合Schema版本1和时才会接受生命周期消息 导出阶段/状态允许列表。 不支持的版本,错误的有效载荷, 出乎意料的字段(包括有秘密字段),以及无效的准备状态 放弃索赔。 现有范围 (eventName: string, payload?: unknown) 处理者仍然可以指派,非生命周期事件继续被转交.

客户端数据方法返回电线信封 { success, error, warning } (无) { data, errors }) (中文(简体) ).

精确的仪器描述符

账户订单、订单填充和事件、职位、位置、位置和数量都显示 API 生成 FDXInstrumentDescriptor 从包根。 准确的将来,保持满载 合同身份(MGCZ6 财务报告和审定财务报表 MGCG7 ; 仅根符号,例如 MGC 为: 标记为 future.identityQuality === 'ROOT_ONLY'. 可选过期、交换、提供者符号, 并且当 API 无法校验时, 出处字段则不在此列 。 浏览器 SDK 不推断 或正常的仪器身份.

import {
  FDXFutureInstrumentDetailsIdentityQualityEnum,
  type FDXBrokerPosition,
} from '@finatic/client';

const result = await finatic.v1.listPositions({ accountId: 'account-id' });
const position: FDXBrokerPosition | undefined = result.success?.data[0];

if (
  position?.instrument?.future?.identityQuality ===
  FDXFutureInstrumentDetailsIdentityQualityEnum.Exact
) {
  console.log(position.instrument.finaticInstrumentId, position.instrument.future.contractCode);
}

await finatic.v1.createAccountOrder({
  accountId: 'account-id',
  idempotencyKey: crypto.randomUUID(),
  body: {
    order: {
      symbol: 'MGCZ6',
      finaticInstrumentId: 'fininst_mgcz6',
      instrumentId: 'provider-native-id',
    },
  },
});

后遗症符号唯命令体和现有的平面身份字段仍然得到支持. 当两者 提供身份字段,API验证它们在授权账户范围内同意.

合同能力和订单类型

包根导出 FDXAssetType.EventContract, (中文(简体) ), EventContractCapabilityResponse, (中文(简体) ), AccountOrderSchemaResponse,以及 FinaticAPIErrorResponse 从核准的公众开放API 艺术品 能力轴是独立的:提供者提供和执行证据不 意味着公共写作授权或账户权利。 处理 publicEnabled !== true, (中文(简体) ), accountEntitled !== true,或 closingOnly === true 作为不提交开业令的理由.

import {
  FDXAssetType,
  type AccountOrderSchemaResponse,
} from '@finatic/client';

const response = await finatic.v1.getAccountOrderSchema<AccountOrderSchemaResponse>({
  accountId: 'account-id',
  action: 'place',
});
const capability = response.success?.data.eventContract;

if (
  capability?.publicEnabled === true &&
  capability.accountEntitled === true &&
  capability.closingOnly !== true
) {
  await finatic.v1.createAccountOrder({
    accountId: 'account-id',
    idempotencyKey: crypto.randomUUID(),
    body: { order: { assetType: FDXAssetType.EventContract, symbol: 'EVENT-SYMBOL' } },
  });
}

EVENT_CONTRACT 是公共资产元素值。 供应商自有有效载荷领域,例如: asset_type: 'event_contract' 穿过没有改变。 未知的公开 assetType 值失败 而不是被省略或绘制为公平。 经认证的事件合同写作 公共授权仍需要提供者/账户证据;SDK的这一释放并不要求这些证据.

打电话 FinaticConnect.reset() 在此之前 init 当您需要一个新的会话边界时.

接头

// Backend (@finatic/server-node) — keep FINATIC_API_KEY here
const token = await finatic.v1.getToken();
// 90 seconds. Send token to the browser only.

从未在 Vite 中设置 API 密钥NEXT_PUBLIC_ 用于生产.

从β移动

连接拥有门户机构/自动/同意UX. 这些流动不是公布于 finatic.v1。位置批号不在v1外观上 listPositions不要通过β connectionId 作为 {accountId}。 。 。 .

环境

apiEnvironment 实值 live | sandbox (单位:千美元)X-Finatic-Environment) URL 预设(environment: 'staging' | 'production' | ...)与沙盒 vs活数据相分离.

常见命令

文档

这个README是客户SDK合同. 在写完整集成之前获取其余部分 :

• 快速开始 : https://finatic.dev/docs/快克-起步/快克-起步
• 节点后端读取器 : https://github.com/FinaticORG/FinaticServerSDK-Node/blob/develop/README.md 互联网档案馆的存檔,存档日期2013-12-20
• Python 后端读取器 : https://github.com/FinaticORG/FinaticServerSDK-Python/blob/develop/README.md 互联网档案馆的存檔,存档日期2013-12-21
• 嵌入连接 : https://finatic.dev/docs/quick-start/portal-configulation 页面存档备份,存于互联网档案馆
• 演示应用 : https://github.com/FinaticORG/FinaticDemoApps/blob/develop/README.md 互联网档案馆的存檔,存档日期2014-12-21
• API 参考 : https://finatic.dev/docs/api-参考资料
• 打开API : https://finatic.dev/openapi.json 页面存档备份,存于互联网档案馆
• 代理索引 : https://finatic.dev/llms.txt
• 代理笔记 : https://finatic.dev/AGENTS.md (英语)