# @agg-build/hooks 中文文档

规范地址：https://npmcn.com/package/%40agg-build/hooks/

版本：4\.37\.0
npm 元数据更新时间：2026-11-05T18:57:15.501Z
中文译文更新时间：2026-11-06T07:02:24.329Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agg-build/hooks
原文对照：https://npmcn.com/package/%40agg-build/hooks/?lang=original
项目主页：https://docs.agg.market/
源码仓库：https://github.com/Snag-Solutions/Agg

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.1 MB，55 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：viem ^2\.0\.0，react ^18\.0\.0 \|\| ^19\.0\.0，wagmi ^3\.0\.0 \|\| ^2\.0\.0，@agg-build/sdk ^4\.37\.0，@solana/web3\.js ^1\.95\.0，@solana/wallet-adapter-react ^0\.15\.0
- 首次发布：2026-04-27T19:41:56.077Z
- 最新版本发布：2026-11-05T18:57:15.329Z
- 近 30 天下载量：4233（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：60（近 12 个月 60 个）

## 中文简介

AGG预测市场聚合器的反应钩和提供者. 用 TanStack 查询、 共享会话状态、 直播 WebSocket 数据来包装 @ agg- building/ sdk .

## 安装

```sh
npm install @agg-build/hooks
```

也可以使用：`pnpm add @agg-build/hooks`、`yarn add @agg-build/hooks`、`bun add @agg-build/hooks`

## README

# @ agg- building/ hooks (韩语)

反应钩和提供者 [恶作剧](https://docs.agg.market/) 预测市场聚合物. 环绕 [`@agg-build/sdk`](https://www.npmjs.com/package/@agg-build/sdk) 有反应上下文, 共享授权/会话 状态, TanStack 查询 – 正在获取数据, 并运行 WebSocket 流 .

## 这是什么

`@agg-build/hooks` 是反应绑定层。 它拥有 `AggClient` 在提供者内部, 保存认证 平衡状态,在您的组件树上同步, 并暴露钩子 每个AGG表面 - 市场、订单、图表、活交易、执行、管理钱包、存款、搜索和UI 相会. 数据钩子由 [TanStack 查询](https://tanstack.com/query)和活数据钩 由SDK的车厢支撑 `AggWebSocket`。 。 。 .

## 何时使用此软件包

-   你正在制造一个反应应用程序 想要钩子 而不是直接给SDK打电话.
-   您想要一个单一的提供者来管理会话、 UI 配置、 平衡和 WebSocket 生命周期 .
-   你计划让AGG与 [`@agg-build/ui`](https://www.npmjs.com/package/@agg-build/ui) 或 模块认证 UI 中 [`@agg-build/auth`](https://www.npmjs.com/package/@agg-build/auth) - 都要求这样 软件包.

如果您没有使用 React, 请使用 [`@agg-build/sdk`](https://www.npmjs.com/package/@agg-build/sdk) 直接说.

## 安装

```bash
npm install @agg-build/sdk @agg-build/hooks
```

## 快开始

```tsx
import { AggProvider, QueryClient, QueryClientProvider } from "@agg-build/hooks";
import { createAggClient } from "@agg-build/sdk";

const client = createAggClient({
  baseUrl: "https://api.agg.market",
  appId: "your-app-id",
  wsUrl: "wss://ws.agg.market",
  // Optional: orderbookUrl: "wss://ob.agg.market", orderbookLatency: "realtime",
  // With orderbookUrl set, orderbook isLive follows that socket. Trades stay on wsUrl.
});
const queryClient = new QueryClient();

export function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <AggProvider
        client={client}
        config={{
          general: { locale: "en-US", theme: "dark" },
          features: { enableAnimations: true, enableLiveUpdates: true },
        }}
      >
        <YourApp />
      </AggProvider>
    </QueryClientProvider>
  );
}
```

`AggProvider` 将SDK,UI配置,平衡,和WebSocket上下文组成一个. 狦 更喜欢自己编剧,个人的供货商`AggSdkProvider`, (中文(简体) ), `AggUiProvider`, (中文(简体) ), `AggBalanceProvider`)也输出.

`AggProvider` 使用 TanStack 查询共享请求和活数据缓存, 所以 `QueryClientProvider` 须取祖相. 软件包再出口 `QueryClient` 财务报告和审定财务报表 `QueryClientProvider` 仅供钩子消费者使用.

### 用钱包签名

`useAggAuth` 是连接您自己的钱包 UI 的下等钩 。 通过 a `signMessage` 回调 从 wagmi (Ethereum) 或 Solana 钱包适配器 :

```tsx
import { useAggAuth } from "@agg-build/hooks";
import { useAccount, useSignMessage } from "wagmi";

function SignIn() {
  const { address, chainId } = useAccount();
  const { signMessageAsync } = useSignMessage();
  const { signIn, signOut, isAuthenticated, user, isLoading, error } = useAggAuth({
    signMessage: (message) => signMessageAsync({ message }),
    address,
    chainId,
  });

  if (isAuthenticated) {
    return (
      <div>
        <p>Signed in as {user?.id}</p>
        <button onClick={() => signOut()}>Sign out</button>
      </div>
    );
  }

  return (
    <button disabled={isLoading} onClick={() => signIn("Sign in to AGG")}>
      Sign in with Ethereum
    </button>
  );
}
```

对索拉纳来说,通过一个 `signMessage` 并返回一个已编码的基数 签名 :

```tsx
import bs58 from "bs58";
import { useWallet } from "@solana/wallet-adapter-react";
import { useAggAuth } from "@agg-build/hooks";

function SolanaSignIn() {
  const { publicKey, signMessage } = useWallet();
  const { signIn, isLoading } = useAggAuth({
    address: publicKey?.toBase58(),
    chain: "solana",
    chainId: "mainnet",
    signMessage: async (message) => {
      const bytes = await signMessage!(new TextEncoder().encode(message));
      return bs58.encode(bytes);
    },
  });

  return (
    <button disabled={isLoading} onClick={() => signIn("Sign in to AGG")}>
      Sign in with Solana
    </button>
  );
}
```

与SIWE、SIWS、Google、苹果、Twitter/X和电子邮件的全包连接/签名用户界面 魔法链接支持, 使用 [`@agg-build/auth`](https://www.npmjs.com/package/@agg-build/auth)。 。 。 .

### 提供市场数据

```tsx
import { useVenueEvents, useMarketOrderbook } from "@agg-build/hooks";

function MarketList() {
  const { data, isLoading, fetchNextPage, hasNextPage } = useVenueEvents({
    limit: 20,
  });

  if (isLoading) return <p>Loading…</p>;

  return (
    <>
      {data?.pages
        .flatMap((page) => page.data)
        .map((event) => (
          <article key={event.id}>{event.title}</article>
        ))}
      {hasNextPage ? <button onClick={() => fetchNextPage()}>Load more</button> : null}
    </>
  );
}

function LiveOrderbook({ venueMarketIds }: { venueMarketIds: string[] }) {
  const { book, isLoading } = useMarketOrderbook({ venueMarketIds });
  if (isLoading) return null;
  return <pre>{JSON.stringify(book, null, 2)}</pre>;
}
```

### 连接外部伙伴用户ID

在您的后端生成签名的断言 `signExternalId()` 从 `@agg-build/sdk/server`,则 调用 `useExternalId()` 在前端 :

```tsx
import { useEffect, useRef } from "react";
import { useExternalId } from "@agg-build/hooks";

function LinkPartnerAccount({
  assertion,
}: {
  assertion: { externalId: string; timestamp: number; hmac: string } | null;
}) {
  const { linkExternalId } = useExternalId();
  const lastLinked = useRef<string | null>(null);

  useEffect(() => {
    if (!assertion) return;
    const key = `${assertion.externalId}:${assertion.timestamp}`;
    if (lastLinked.current === key) return;
    lastLinked.current = key;
    void linkExternalId(assertion).catch(() => {
      lastLinked.current = null;
    });
  }, [assertion, linkExternalId]);

  return null;
}
```

## 主钩

### 核心

| 钩子 | 说明 |
| --- | --- |
| `useAggClient()` | 访问基础 `AggClient` 实例 |
| `useAggAuth(options)` | SIWE/SIWS 登录的钱包签名助手 |
| `useAggAuthContext()` | 完全认证上下文( 是认证的, 用户, 签名 In, 签名 Out, ...) |
| `useAggAuthState()` | 只读认证状态 |
| `useLinkAccount()` | 将额外的认证提供者链接到经常账户 |
| `useExternalId()` | 链接后端签名的伙伴用户ID |
| `useGeoBlock()` | 限制区域的反应地理块状态 |

### 市场数据

| 钩子 | 说明 |
| --- | --- |
| `useVenueEvents(options?)` | 以光标为基础的无限图示事件 |
| `useVenueEvent({ eventId })` | 通过 ID 获取单个事件 |
| `useEnrichedVenueEvent(options)` | 活动+有完整市场数据的丰富会场市场 |
| `useVenueMarkets(options?)` | 带有过滤器的市场(无限平面) |
| `useCategories(options?)` | 市场类别(无限平面) |
| `useSearch(options?)` | 跨事件类型搜索 |

### 订单和路由

| 钩子 | 说明 |
| --- | --- |
| `useMarketOrderbook(options)` | 带有实时 WS 更新的目录 |
| `useOrderBook(options)` | 将多个会场订购簿分到一个结果 |
| `useOrderbookQuote(options)` | 计算一个大小/ 侧边命令书的引用 |
| `useSmartRoute(options)` | 通过 MILP 解析器对不同地点进行优化的路由 |

### 图表

| 钩子 | 说明 |
| --- | --- |
| `useMarketChart(options)` | 具有实时WS更新的历史蜡烛 |
| `useLiveCandles(options)` | 合并 REST 历史 + 直播 `CandleBuilder` 产出 |
| `useLiveCandleOverlay(options)` | 用活页显示图表渲染的缩放蜡烛 |

### 实时数据

| 钩子 | 说明 |
| --- | --- |
| `useLiveMarket(canonicalMarketId)` | 订阅一个市场的活订书+交易 |
| `useLiveTrades(canonicalMarketId)` | 仅涉及近期贸易(最大50个,最新第一) |
| `useLiveOutcomePrices(venueMarkets)` | 所有结果的衍生显示价格 |
| `useVenueMarketMidpoints(options)` | 可见市场的中点 |
| `useViewportMidpoints(options)` | 为可见取景口分批的中点 |
| `useVisibleIds(options)` | 滚动容器中当前可见的跟踪标识 |

### 网络安全套

| 钩子 | 说明 |
| --- | --- |
| `useAggWebSocket()` | 访问原始 `AggWebSocket` 实例 |
| `useOnOrderSubmitted(callback)` | 订阅命令提交事件 |
| `useOnBalanceUpdate(callback)` | 订阅以平衡更新事件 |
| `useOnRedeemEvent(callback)` | 订阅以赎回事件 |
| `useEventOrderbookData(venueMarkets, selectedMarketId)` | WS 订阅活动市场订单 |

### 余额

| 钩子 | 说明 |
| --- | --- |
| `useAggBalance()` | 余额背景(总额、细目、地点) |
| `useAggBalanceContext()` | 完全平衡的上下文与反切 |
| `useAggBalanceState()` | 只读平衡状态 |
| `useManagedBalances()` | 查询统一管理的钱包余额 |

### 命令和职位

| 钩子 | 说明 |
| --- | --- |
| `useOrders(options?)` | 列出交易执行者订单( 抵消页标) |
| `useExecutionOrders(options?)` | 列出执行命令( cursor pagination) |
| `useExecutionPositions(options?)` | 列出执行位置( cursor pagination) |
| `useUserHoldings(options)` | 获取特定地点持有量 |
| `usePositions(options?)` | 按匹配市场分类的查询用户位置 |
| `useUserActivity(options?)` | 统一活动饲料(贸易、矿藏、桥梁) |
| `useLeaderboard(options?)` | 由 P&L 或音量( cursor pagination) 组成的交易领导板 |

### 管理下的执行

| 钩子 | 说明 |
| --- | --- |
| `useExecuteManaged(options?)` | 填入引号 `useSmartRoute` - 见下注 |
| `useValidateManaged(options?)` | 核证前余额/桥梁,不引用 |
| `useWithdrawManaged(options?)` | 从管理的钱包中撤回 |
| `useSyncBalances(options?)` | 触发链上平衡同步 |
| `useExecutionProgress(options)` | 跟踪各阶段的执行情况(待) 提交) |
| `useRedeem()` | 已解决市场的索赔胜诉 |
| `useRedeemEligibleCount()` | 有资格赎回的职位数 |

引用和填充,取引自 `useSmartRoute` 并通过它的 `quoteId` 改为 `useExecuteManaged`。 。 。 .

```tsx
const buyRoute = useSmartRoute({
  venueMarketOutcomeId,
  tradeSide: "buy",
  maxSpend: 50,
});

const sellRoute = useSmartRoute({
  venueMarketOutcomeId,
  tradeSide: "sell",
  sellShares: 10,
});
```

> **在v4中被删除.** `useQuoteManaged` 被删除——包裹 `client.quoteManaged()`,其终点`POST /execution/quote`没有 在API上存在,所以这个电话只返回了404.

### 矿藏(子路径)

从 `@agg-build/hooks/deposit` 将钱包重的钩子从主包中取出:

| 钩子 | 说明 |
| --- | --- |
| `useDepositFlow(options?)` | 端到端存款流量( 选择令牌 ) – 发送 – 确认 ) |
| `useWalletTokenBalance(params)` | 读取连接钱包的 ERC-20/ SPL 余额 |
| `useWalletSendToken(params)` | 使用连接的钱包执行传输 |
| `useWalletTransactionStatus()` | 交易链上交易状态 |
| `useDepositAddresses(options?)` | 管理钱包存款地址 |
| `useSyncBalances(options?)` | 重新接触主条目的同地进口 |
| `normalizeWalletError(error)` | 将钱包- 图书馆错误转换为友好形状 |

### 倾斜

| 钩子 | 说明 |
| --- | --- |
| `useRampQuotes()` | 查询/关闭引用 |
| `useRampSession()` | 创建坡道部件会话 |

### 用户界面配置和公用事业

| 钩子 | 说明 |
| --- | --- |
| `useSdkUiConfig()` | 读取 SDK 级 UI 配置 |
| `useAggUiConfig()` | 读取全部 AGG 用户界面配置 |
| `useAggLabels()` 编号 : `useLabels()` | 访问 UI 标签字符串 |
| `useEventTradingContext()` | 事件/市场/结果选择 |
| `useDebouncedValue(value, ms)` | 通过延迟跳出一个值 |
| `useAppConfig()` | 伙伴应用配置( 地标等) |

## 供应商

| 提供者 | 目的 |
| --- | --- |
| `AggProvider` | 一站式提供者: SDK + UI 配置 + 平衡 + WebSocket |
| `AggSdkProvider` | 只有 SDK + 认证状态 |
| `AggUiProvider` | UI 配置( 标签、 主题、 特征旗、 搜索状态) |
| `AggBalanceProvider` | 结余情况(共计,细目) |
| `EventListStateProvider` | 共享事件列表的页形/ 过滤状态 |

### 用户界面配置

`AggProvider` 接受分区配置对象 :

-   `enableLogs` 编号 : `enableWebsocketsLogs` ——开启调试日志
-   `general` —— 说 `locale`, (中文(简体) ), `theme` (单位:千美元)`"light" | "dark"`, (中文(简体) ), `rootClassName`, (中文(简体) ), `labels`
-   `features` ——UI行为标志包括: `enableAnimations`, (中文(简体) ), `enableLiveUpdates`, (中文(简体) ), `enableVenueEventDiscoveryFilters`,以及 `enableEventDiscoveryUrlPersistence`
-   `market` —— 说 `arbitrageThreshold`, (中文(简体) ), `maxMidpointIdsPerRequest` 用于代理/安全CDN中点批量
-   `chart` —— 说 `defaultChartTimeRange`, (中文(简体) ), `selectedChartTimeRange`
-   `search` ——供应商拥有的搜索状态+对主机-应用程序路由/分析的回调

`locale`, (中文(简体) ), `theme`,以及 `selectedChartTimeRange` 自动坚持 `localStorage`。 。 。 .

## 查询密钥

对于直接反应查询缓存访问(例如. `queryClient.invalidateQueries()`:

```typescript
import { executionKeys } from "@agg-build/hooks";

queryClient.invalidateQueries({ queryKey: executionKeys.balances() });
queryClient.invalidateQueries({ queryKey: executionKeys.positions() });
queryClient.invalidateQueries({ queryKey: executionKeys.orders() });
```

`executionKeys` 是唯一公开出口的关键构建者——市场数据查询得到管理 内部由 WebSocket 提供者提供.

## 行为说明

-   `useOrderbookQuote` 弹出 `size` 在查询前更改 300 ms .
-   `useDepositAddresses` 在管理钱包时每3秒投票一次 (单位:千美元)`ready === false`),然后切换到60 sstale时间.
-   `useLiveCandles` 将 REST 历史蜡烛与直播合并 `CandleBuilder` 输出; 碰撞 现场版本获胜.
-   对于二进制市场,第一个结果得到中点,第二个得到 `1 − midpoint`。 。 。 .
-   `CandleBuilder` 批号 `onChange` 以 ~16 ms 调用(浏览器中的 RAF, 另设置 Timeout) .
-   执行突变`useExecuteManaged`, (中文(简体) ), `useWithdrawManaged`, (中文(简体) ), `useSyncBalances`(中文(简体) ) 自动验证相关的平衡/位置/顺序查询.

## 入境点

| 条目 | 目的 |
| --- | --- |
| `@agg-build/hooks` | 所有供应商和钩子 |
| `@agg-build/hooks/deposit` | 钱包重的储物钩(可树状亚道) |

## 同伴依赖关系

要求 :

-   `@agg-build/sdk`
-   `react` ^18.0.0或^19.0

可选( 只需要基于钱包的签名/ 存款) :

-   `wagmi` ^ 2.0.0 (SIWE + ERC-20 矿床)
-   `viem` ^ 2.0.0 (与 `wagmi`(中文(简体) )
-   `@solana/wallet-adapter-react` ^0.15.0 (SIWS + SPL 矿床)
-   `@solana/web3.js` ^ 1.95.0 (韩语)

## 链接

-   文 件 - 存档副本 [https://docs.agg.market/ 互联网档案馆的存檔,存档日期2013-12-02](https://docs.agg.market/)
-   Demo app - 软件 [https://agg.market/ (中文(简体) )](https://agg.market/)
-   香草SDK - - 。 [`@agg-build/sdk`](https://www.npmjs.com/package/@agg-build/sdk)
-   贸易UI - [`@agg-build/ui`](https://www.npmjs.com/package/@agg-build/ui)
-   连接/ 登录 UX —— [`@agg-build/auth`](https://www.npmjs.com/package/@agg-build/auth)

## 许可证

麻省理工学院

## 常见问题

### @agg-build/hooks 是什么？

AGG预测市场聚合器的反应钩和提供者\. 用 TanStack 查询、 共享会话状态、 直播 WebSocket 数据来包装 @ agg- building/ sdk \.

### 如何安装 @agg-build/hooks？

在项目目录运行 npm install @agg-build/hooks，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）、@agg-build/sdk（^4\.37\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @agg-build/hooks 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @agg-build/hooks 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @agg-build/hooks 可以商用吗？

@agg-build/hooks 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @agg-build/hooks 的下载量有多少？

根据 npm 官方下载统计，@agg-build/hooks 在 2026/10/05 – 2026/11/03 这 30 天内被下载 4,233 次，日均约 141 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agg-build/hooks 还在维护吗？

最新版本 4\.37\.0 发布于 2026/11/06（今天）；至今共发布 60 个版本，其中过去 12 个月发布了 60 个；首次发布于 2026/04/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。