@sodax/dapp-kit 2.0.0-rc.17 → 2.0.0-rc.19

package/src/hooks/partner/useFeeClaimWithdraw.ts

@@ -0,0 +1,88 @@
+// packages/dapp-kit/src/hooks/partner/useFeeClaimWithdraw.ts
+import {
+  ChainKeys,
+  type Address,
+  type BridgeParams,
+  type GetWalletProviderType,
+  type HubChainKey,
+  type SpokeChainKey,
+  type TxHashPair,
+} from '@sodax/sdk';
+import { useQueryClient } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+
+/**
+ * Mutation variables for {@link useFeeClaimWithdraw}. Maps a partner fee balance to a
+ * Sonic-sourced bridge: `feeToken` is the wrapped hub-asset address on Sonic
+ * (`PartnerFeeClaimAssetBalance.address`); `dstToken` is the original token address on
+ * `dstChainKey` (`PartnerFeeClaimAssetBalance.originalAddress`, or `feeToken` for same-chain
+ * delivery to a Sonic address).
+ */
+export type UseFeeClaimWithdrawVars = {
+  params: {
+    srcAddress: string;
+    feeToken: Address;
+    amount: bigint;
+    dstChainKey: SpokeChainKey;
+    dstToken: string;
+    recipient: string;
+  };
+  walletProvider: GetWalletProviderType<HubChainKey>;
+};
+
+/**
+ * React hook to withdraw a partner fee token directly to the partner's wallet **without a swap**.
+ *
+ * For fees the partner wants to keep as-is (the desired output equals the fee token, e.g. BTC→BTC),
+ * an auto-swap is impossible — the solver rejects a same-token swap. This bridges the wrapped fee
+ * token from Sonic to its native chain (or transfers it on Sonic when `dstChainKey` is Sonic),
+ * bypassing the solver entirely.
+ *
+ * Bridging from Sonic pulls the token via the partner's hub-wallet router, which requires a prior
+ * allowance to that spender — a different approval than the ProtocolIntents one used by the swap
+ * claim. Use `useBridgeAllowance` / `useBridgeApprove` (with the same mapped bridge params) first.
+ *
+ * Throws on SDK failure so React Query's native error model engages. Returns the `TxHashPair`.
+ */
+export function useFeeClaimWithdraw({
+  mutationOptions,
+}: MutationHookParams<TxHashPair, UseFeeClaimWithdrawVars> = {}): SafeUseMutationResult<
+  TxHashPair,
+  Error,
+  UseFeeClaimWithdrawVars
+> {
+  const { sodax } = useSodaxContext();
+  const queryClient = useQueryClient();
+
+  return useSafeMutation<TxHashPair, Error, UseFeeClaimWithdrawVars>({
+    mutationKey: ['partner', 'feeClaimWithdraw'],
+    ...mutationOptions,
+    mutationFn: async ({ params, walletProvider }) => {
+      const bridgeParams = {
+        params: {
+          srcChainKey: ChainKeys.SONIC_MAINNET,
+          srcAddress: params.srcAddress,
+          srcToken: params.feeToken,
+          amount: params.amount,
+          dstChainKey: params.dstChainKey,
+          dstToken: params.dstToken,
+          recipient: params.recipient,
+        },
+        raw: false,
+        walletProvider,
+      } satisfies BridgeParams<HubChainKey, false>;
+
+      return unwrapResult(await sodax.bridge.bridge(bridgeParams));
+    },
+    onSuccess: async (data, vars, ctx) => {
+      queryClient.invalidateQueries({
+        queryKey: ['partner', 'feeClaim', 'assetsBalances', vars.params.srcAddress],
+      });
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', vars.params.dstChainKey] });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
+    },
+  });
+}

package/src/hooks/partner/useGetIntentDetails.ts

@@ -0,0 +1,39 @@
+// packages/dapp-kit/src/hooks/partner/useGetIntentDetails.ts
+import type { Hex, Intent } from '@sodax/sdk';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+const ZERO_HASH = '0x0000000000000000000000000000000000000000000000000000000000000000';
+
+export type UseGetIntentDetailsParams = ReadHookParams<Intent, { intentHash: Hex | undefined }>;
+
+/**
+ * React hook to fetch the full {@link Intent} details for a ProtocolIntents intent hash.
+ *
+ * Pair with {@link useGetUserIntent} to display a stuck intent (e.g. its locked `inputAmount`)
+ * before recovering it. Disabled when the hash is missing or the zero hash (no intent). Throws
+ * on `!ok`.
+ */
+export function useGetIntentDetails({
+  params,
+  queryOptions,
+}: UseGetIntentDetailsParams = {}): UseQueryResult<Intent, Error> {
+  const { sodax } = useSodaxContext();
+  const intentHash = params?.intentHash;
+  const hasIntent = !!intentHash && intentHash !== ZERO_HASH;
+
+  return useQuery<Intent, Error>({
+    queryKey: ['partner', 'feeClaim', 'intentDetails', intentHash],
+    queryFn: async () => {
+      if (!intentHash) {
+        throw new Error('intentHash is required');
+      }
+      const result = await sodax.partners.feeClaim.getIntentDetails(intentHash);
+      if (!result.ok) throw result.error;
+      return result.value;
+    },
+    enabled: hasIntent,
+    ...queryOptions,
+  });
+}

package/src/hooks/partner/useGetUserIntent.ts

@@ -0,0 +1,35 @@
+// packages/dapp-kit/src/hooks/partner/useGetUserIntent.ts
+import type { GetUserIntentParams, Hex } from '@sodax/sdk';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseGetUserIntentParams = ReadHookParams<Hex, Partial<GetUserIntentParams>>;
+
+/**
+ * React hook to look up the stored intent hash for a partner's `(user, fromToken, toToken)` pair.
+ *
+ * A non-zero hash means an open auto-swap intent exists for that token pair (e.g. an unfilled
+ * same-token claim) and can be recovered via {@link usePartnerCancelIntent}. Disabled until all
+ * three inputs are present. Throws on `!ok`.
+ */
+export function useGetUserIntent({ params, queryOptions }: UseGetUserIntentParams = {}): UseQueryResult<Hex, Error> {
+  const { sodax } = useSodaxContext();
+  const user = params?.user;
+  const fromToken = params?.fromToken;
+  const toToken = params?.toToken;
+
+  return useQuery<Hex, Error>({
+    queryKey: ['partner', 'feeClaim', 'userIntent', user, fromToken, toToken],
+    queryFn: async () => {
+      if (!user || !fromToken || !toToken) {
+        throw new Error('user, fromToken and toToken are required');
+      }
+      const result = await sodax.partners.feeClaim.getUserIntent({ user, fromToken, toToken });
+      if (!result.ok) throw result.error;
+      return result.value;
+    },
+    enabled: !!user && !!fromToken && !!toToken,
+    ...queryOptions,
+  });
+}

package/src/hooks/partner/usePartnerCancelIntent.ts

@@ -0,0 +1,52 @@
+// packages/dapp-kit/src/hooks/partner/usePartnerCancelIntent.ts
+import type { HubChainKey, PartnerFeeClaimCancelAction, TxReturnType } from '@sodax/sdk';
+import { useQueryClient } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+
+export type UsePartnerCancelIntentVars = Omit<PartnerFeeClaimCancelAction<HubChainKey, false>, 'raw'>;
+
+/**
+ * React hook to cancel a stuck partner fee-claim auto-swap intent and recover the locked tokens.
+ *
+ * Calls `ProtocolIntents.cancelIntent(fromToken, toToken)` — the only authorized cancel path for
+ * partner auto-swap intents (the generic swap-cancel reverts because ProtocolIntents, not the
+ * partner, is the intent creator). The contract cancels the intent and refunds the input amount to
+ * the partner. Use this to recover funds from an unfillable same-token claim.
+ *
+ * Throws on SDK failure so React Query's native error model engages. Returns the transaction hash.
+ */
+export function usePartnerCancelIntent({
+  mutationOptions,
+}: MutationHookParams<TxReturnType<HubChainKey, false>, UsePartnerCancelIntentVars> = {}): SafeUseMutationResult<
+  TxReturnType<HubChainKey, false>,
+  Error,
+  UsePartnerCancelIntentVars
+> {
+  const { sodax } = useSodaxContext();
+  const queryClient = useQueryClient();
+
+  return useSafeMutation<TxReturnType<HubChainKey, false>, Error, UsePartnerCancelIntentVars>({
+    mutationKey: ['partner', 'cancelIntent'],
+    ...mutationOptions,
+    mutationFn: async vars => unwrapResult(await sodax.partners.feeClaim.cancelIntent<false>({ ...vars, raw: false })),
+    onSuccess: async (data, vars, ctx) => {
+      queryClient.invalidateQueries({
+        queryKey: ['partner', 'feeClaim', 'assetsBalances', vars.params.srcAddress],
+      });
+      queryClient.invalidateQueries({
+        queryKey: [
+          'partner',
+          'feeClaim',
+          'userIntent',
+          vars.params.srcAddress,
+          vars.params.fromToken,
+          vars.params.toToken,
+        ],
+      });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
+    },
+  });
+}

package/src/hooks/swapsApi/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Swaps API v2 hooks — typed React Query wrappers over `sodax.api.swaps.*` (the SwapsApiService
+ * HTTP client). One hook per endpoint of the backend Swaps API v2.
+ *
+ * Distinct from the on-chain `swap/` hooks (`useQuote`/`useStatus`/`useSwap`/…), which drive the
+ * `SwapService` path (wallet → hub chain). These hooks call the backend HTTP API instead.
+ */
+
+// Tokens
+export * from './useSwapsApiTokens.js';
+export * from './useSwapsApiTokensByChain.js';
+
+// Quote · deadline
+export * from './useSwapsApiQuote.js';
+export * from './useSwapsApiDeadline.js';
+
+// Allowance · approve · create intent
+export * from './useSwapsApiAllowance.js';
+export * from './useSwapsApiApprove.js';
+export * from './useSwapsApiCreateIntent.js';
+
+// Intent lifecycle: submit · status · cancel · hash · packet · extra-data · lookup
+export * from './useSwapsApiSubmitIntent.js';
+export * from './useSwapsApiStatus.js';
+export * from './isTerminalSwapIntentStatus.js'; // terminal-status predicate (drives the status hook's polling)
+export * from './useSwapsApiCancelIntent.js';
+export * from './useSwapsApiIntentHash.js';
+export * from './useSwapsApiIntentPacket.js';
+export * from './useSwapsApiIntentExtraData.js';
+export * from './useSwapsApiFilledIntent.js';
+export * from './useSwapsApiIntent.js';
+
+// Limit orders · gas · fees
+export * from './useSwapsApiCreateLimitOrder.js';
+export * from './useSwapsApiEstimateGas.js';
+export * from './useSwapsApiPartnerFee.js';
+export * from './useSwapsApiSolverFee.js';
+
+// Submit-tx state machine
+export * from './useSwapsApiSubmitTx.js';
+export * from './useSwapsApiSubmitTxStatus.js';

package/src/hooks/swapsApi/isTerminalSwapIntentStatus.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { isTerminalSwapIntentStatus } from './isTerminalSwapIntentStatus.js';
+
+/**
+ * Guards the polling-stop invariant for `useSwapsApiStatus.refetchInterval`: the hook keeps polling
+ * (1s) until the solver reports a terminal status, then stops. Tested as a pure predicate because
+ * dapp-kit's vitest runs in the `node` environment (no hook rendering) — see nearStorageGate.test.ts.
+ */
+describe('isTerminalSwapIntentStatus', () => {
+  it('is terminal for SOLVED (3) and FAILED (4)', () => {
+    expect(isTerminalSwapIntentStatus(3)).toBe(true);
+    expect(isTerminalSwapIntentStatus(4)).toBe(true);
+  });
+
+  it('is non-terminal for NOT_FOUND (-1), NOT_STARTED_YET (1), and STARTED_NOT_FINISHED (2)', () => {
+    expect(isTerminalSwapIntentStatus(-1)).toBe(false);
+    expect(isTerminalSwapIntentStatus(1)).toBe(false);
+    expect(isTerminalSwapIntentStatus(2)).toBe(false);
+  });
+
+  it('is non-terminal when no status has arrived yet (undefined) — keeps polling', () => {
+    expect(isTerminalSwapIntentStatus(undefined)).toBe(false);
+  });
+});

package/src/hooks/swapsApi/isTerminalSwapIntentStatus.ts

@@ -0,0 +1,11 @@
+import type { SwapIntentStatusCodeV2 } from '@sodax/sdk';
+
+/**
+ * Terminal solver intent states: once reached, the intent is resolved and polling stops.
+ * `3` = SOLVED, `4` = FAILED (per `SwapIntentStatusCodeV2`); `-1` / `1` / `2` are non-terminal.
+ *
+ * Kept in its own pure module (no React/context imports) so it is unit-testable in dapp-kit's
+ * `node` test environment — importing the hook itself pulls in `useSodaxContext`.
+ */
+export const isTerminalSwapIntentStatus = (status: SwapIntentStatusCodeV2 | undefined): boolean =>
+  status === 3 || status === 4;

package/src/hooks/swapsApi/useSwapsApiAllowance.ts

@@ -0,0 +1,40 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import type { AllowanceCheckResponseV2, CreateIntentParamsV2, RequestOverrideConfig } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseSwapsApiAllowanceParams = ReadHookParams<
+  AllowanceCheckResponseV2 | undefined,
+  {
+    body: CreateIntentParamsV2 | undefined;
+    apiConfig?: RequestOverrideConfig;
+  }
+>;
+
+/**
+ * React hook to check whether the source-token allowance is already sufficient for an intent via
+ * the swaps API — `sodax.api.swaps.checkAllowance`. Returns `{ valid }`.
+ *
+ * @example
+ * const { data: allowance } = useSwapsApiAllowance({ params: { body: createIntentParams } });
+ */
+export const useSwapsApiAllowance = ({
+  params,
+  queryOptions,
+}: UseSwapsApiAllowanceParams = {}): UseQueryResult<AllowanceCheckResponseV2 | undefined, Error> => {
+  const { sodax } = useSodaxContext();
+  const body = params?.body;
+  const apiConfig = params?.apiConfig;
+
+  return useQuery({
+    queryKey: ['swapsApi', 'allowance', body?.srcChainKey, body?.inputToken, body?.inputAmount, body?.srcAddress],
+    queryFn: async (): Promise<AllowanceCheckResponseV2 | undefined> => {
+      if (!body) return undefined;
+      return unwrapResult(await sodax.api.swaps.checkAllowance(body, apiConfig));
+    },
+    enabled: !!body,
+    retry: 3,
+    ...queryOptions,
+  });
+};

package/src/hooks/swapsApi/useSwapsApiApprove.ts

@@ -0,0 +1,42 @@
+import type { ApproveResponseV2, CreateIntentParamsV2, RequestOverrideConfig } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+
+/**
+ * Mutation variables for {@link useSwapsApiApprove}. The per-request `apiConfig` override belongs
+ * here rather than at the hook level — different calls in the same component can target different
+ * endpoints without re-rendering.
+ */
+export type UseSwapsApiApproveVars = {
+  body: CreateIntentParamsV2;
+  apiConfig?: RequestOverrideConfig;
+};
+
+/**
+ * React hook to build an unsigned token-approval transaction for the source token via the swaps
+ * API — `sodax.api.swaps.approve`. Returns `{ tx }` (chain-specific unsigned tx) to sign and
+ * broadcast yourself; it does not change state, so no queries are invalidated.
+ *
+ * @example
+ * const { mutateAsync: approve } = useSwapsApiApprove();
+ * const { tx } = await approve({ body: createIntentParams });
+ */
+export const useSwapsApiApprove = ({
+  mutationOptions,
+}: MutationHookParams<ApproveResponseV2, UseSwapsApiApproveVars> = {}): SafeUseMutationResult<
+  ApproveResponseV2,
+  Error,
+  UseSwapsApiApproveVars
+> => {
+  const { sodax } = useSodaxContext();
+
+  return useSafeMutation<ApproveResponseV2, Error, UseSwapsApiApproveVars>({
+    mutationKey: ['swapsApi', 'approve'],
+    retry: 3,
+    ...mutationOptions,
+    mutationFn: async ({ body, apiConfig }): Promise<ApproveResponseV2> =>
+      unwrapResult(await sodax.api.swaps.approve(body, apiConfig)),
+  });
+};

package/src/hooks/swapsApi/useSwapsApiCancelIntent.ts

@@ -0,0 +1,41 @@
+import type { CancelIntentRequestV2, CancelIntentResponseV2, RequestOverrideConfig } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+
+/**
+ * Mutation variables for {@link useSwapsApiCancelIntent}. The per-request `apiConfig` override
+ * belongs here rather than at the hook level.
+ */
+export type UseSwapsApiCancelIntentVars = {
+  body: CancelIntentRequestV2;
+  apiConfig?: RequestOverrideConfig;
+};
+
+/**
+ * React hook to build an unsigned cancel-intent transaction via the swaps API —
+ * `sodax.api.swaps.cancelIntent`. The `intent` carries `bigint` numerics. Returns `{ tx }` to sign
+ * and broadcast yourself; it does not change state, so no queries are invalidated.
+ *
+ * @example
+ * const { mutateAsync: cancelIntent } = useSwapsApiCancelIntent();
+ * const { tx } = await cancelIntent({ body: { srcChainKey: 'sonic', intent } });
+ */
+export const useSwapsApiCancelIntent = ({
+  mutationOptions,
+}: MutationHookParams<CancelIntentResponseV2, UseSwapsApiCancelIntentVars> = {}): SafeUseMutationResult<
+  CancelIntentResponseV2,
+  Error,
+  UseSwapsApiCancelIntentVars
+> => {
+  const { sodax } = useSodaxContext();
+
+  return useSafeMutation<CancelIntentResponseV2, Error, UseSwapsApiCancelIntentVars>({
+    mutationKey: ['swapsApi', 'cancelIntent'],
+    retry: 3,
+    ...mutationOptions,
+    mutationFn: async ({ body, apiConfig }): Promise<CancelIntentResponseV2> =>
+      unwrapResult(await sodax.api.swaps.cancelIntent(body, apiConfig)),
+  });
+};

package/src/hooks/swapsApi/useSwapsApiCreateIntent.ts

@@ -0,0 +1,41 @@
+import type { CreateIntentParamsV2, CreateIntentResponseV2, RequestOverrideConfig } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+
+/**
+ * Mutation variables for {@link useSwapsApiCreateIntent}. The per-request `apiConfig` override
+ * belongs here rather than at the hook level.
+ */
+export type UseSwapsApiCreateIntentVars = {
+  body: CreateIntentParamsV2;
+  apiConfig?: RequestOverrideConfig;
+};
+
+/**
+ * React hook to build an unsigned create-intent transaction via the swaps API —
+ * `sodax.api.swaps.createIntent`. Returns `{ tx, intent, relayData }` to sign and broadcast
+ * yourself; it does not change state, so no queries are invalidated.
+ *
+ * @example
+ * const { mutateAsync: createIntent } = useSwapsApiCreateIntent();
+ * const { tx, intent, relayData } = await createIntent({ body: createIntentParams });
+ */
+export const useSwapsApiCreateIntent = ({
+  mutationOptions,
+}: MutationHookParams<CreateIntentResponseV2, UseSwapsApiCreateIntentVars> = {}): SafeUseMutationResult<
+  CreateIntentResponseV2,
+  Error,
+  UseSwapsApiCreateIntentVars
+> => {
+  const { sodax } = useSodaxContext();
+
+  return useSafeMutation<CreateIntentResponseV2, Error, UseSwapsApiCreateIntentVars>({
+    mutationKey: ['swapsApi', 'createIntent'],
+    retry: 3,
+    ...mutationOptions,
+    mutationFn: async ({ body, apiConfig }): Promise<CreateIntentResponseV2> =>
+      unwrapResult(await sodax.api.swaps.createIntent(body, apiConfig)),
+  });
+};

package/src/hooks/swapsApi/useSwapsApiCreateLimitOrder.ts

@@ -0,0 +1,41 @@
+import type { CreateLimitOrderParamsV2, CreateLimitOrderResponseV2, RequestOverrideConfig } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+
+/**
+ * Mutation variables for {@link useSwapsApiCreateLimitOrder}. The per-request `apiConfig` override
+ * belongs here rather than at the hook level.
+ */
+export type UseSwapsApiCreateLimitOrderVars = {
+  body: CreateLimitOrderParamsV2;
+  apiConfig?: RequestOverrideConfig;
+};
+
+/**
+ * React hook to build an unsigned create-limit-order-intent transaction via the swaps API —
+ * `sodax.api.swaps.createLimitOrderIntent` (same as create-intent but `deadline` is optional).
+ * Returns `{ tx, intent, relayData }`; it does not change state, so no queries are invalidated.
+ *
+ * @example
+ * const { mutateAsync: createLimitOrder } = useSwapsApiCreateLimitOrder();
+ * const { tx, intent, relayData } = await createLimitOrder({ body: createLimitOrderParams });
+ */
+export const useSwapsApiCreateLimitOrder = ({
+  mutationOptions,
+}: MutationHookParams<CreateLimitOrderResponseV2, UseSwapsApiCreateLimitOrderVars> = {}): SafeUseMutationResult<
+  CreateLimitOrderResponseV2,
+  Error,
+  UseSwapsApiCreateLimitOrderVars
+> => {
+  const { sodax } = useSodaxContext();
+
+  return useSafeMutation<CreateLimitOrderResponseV2, Error, UseSwapsApiCreateLimitOrderVars>({
+    mutationKey: ['swapsApi', 'createLimitOrder'],
+    retry: 3,
+    ...mutationOptions,
+    mutationFn: async ({ body, apiConfig }): Promise<CreateLimitOrderResponseV2> =>
+      unwrapResult(await sodax.api.swaps.createLimitOrderIntent(body, apiConfig)),
+  });
+};

package/src/hooks/swapsApi/useSwapsApiDeadline.ts

@@ -0,0 +1,36 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import type { DeadlineQueryV2, DeadlineResponseV2, RequestOverrideConfig } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseSwapsApiDeadlineParams = ReadHookParams<
+  DeadlineResponseV2,
+  {
+    query?: DeadlineQueryV2;
+    apiConfig?: RequestOverrideConfig;
+  }
+>;
+
+/**
+ * React hook to compute a swap deadline (hub timestamp + `offsetSeconds`, default 300s) via the
+ * swaps API — `sodax.api.swaps.getDeadline`.
+ *
+ * @example
+ * const { data: deadline } = useSwapsApiDeadline({ params: { query: { offsetSeconds: 600 } } });
+ */
+export const useSwapsApiDeadline = ({
+  params,
+  queryOptions,
+}: UseSwapsApiDeadlineParams = {}): UseQueryResult<DeadlineResponseV2, Error> => {
+  const { sodax } = useSodaxContext();
+  const query = params?.query;
+  const apiConfig = params?.apiConfig;
+
+  return useQuery<DeadlineResponseV2, Error>({
+    queryKey: ['swapsApi', 'deadline', query?.offsetSeconds ?? null],
+    queryFn: async (): Promise<DeadlineResponseV2> => unwrapResult(await sodax.api.swaps.getDeadline(query, apiConfig)),
+    retry: 3,
+    ...queryOptions,
+  });
+};

package/src/hooks/swapsApi/useSwapsApiEstimateGas.ts

@@ -0,0 +1,40 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import type { GasEstimateRequestV2, GasEstimateResponseV2, RequestOverrideConfig } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseSwapsApiEstimateGasParams = ReadHookParams<
+  GasEstimateResponseV2 | undefined,
+  {
+    body: GasEstimateRequestV2 | undefined;
+    apiConfig?: RequestOverrideConfig;
+  }
+>;
+
+/**
+ * React hook to estimate gas for a raw transaction on a spoke chain via the swaps API —
+ * `sodax.api.swaps.estimateGas`. Returns `{ gas }` (chain-specific shape).
+ *
+ * @example
+ * const { data } = useSwapsApiEstimateGas({ params: { body: { chainKey: 'sonic', tx } } });
+ */
+export const useSwapsApiEstimateGas = ({
+  params,
+  queryOptions,
+}: UseSwapsApiEstimateGasParams = {}): UseQueryResult<GasEstimateResponseV2 | undefined, Error> => {
+  const { sodax } = useSodaxContext();
+  const body = params?.body;
+  const apiConfig = params?.apiConfig;
+
+  return useQuery({
+    queryKey: ['swapsApi', 'estimateGas', body?.chainKey, body?.tx],
+    queryFn: async (): Promise<GasEstimateResponseV2 | undefined> => {
+      if (!body) return undefined;
+      return unwrapResult(await sodax.api.swaps.estimateGas(body, apiConfig));
+    },
+    enabled: !!body,
+    retry: 3,
+    ...queryOptions,
+  });
+};

package/src/hooks/swapsApi/useSwapsApiFilledIntent.ts

@@ -0,0 +1,41 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import type { IntentStateV2, RequestOverrideConfig } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseSwapsApiFilledIntentParams = ReadHookParams<
+  IntentStateV2 | undefined,
+  {
+    txHash: string | undefined;
+    apiConfig?: RequestOverrideConfig;
+  }
+>;
+
+/**
+ * React hook to get the on-chain fill state for an intent by its hub-chain tx hash via the swaps
+ * API — `sodax.api.swaps.getFilledIntent`. Returns
+ * `{ exists, remainingInput, receivedOutput, pendingPayment }`.
+ *
+ * @example
+ * const { data: fill } = useSwapsApiFilledIntent({ params: { txHash: '0x123...' } });
+ */
+export const useSwapsApiFilledIntent = ({
+  params,
+  queryOptions,
+}: UseSwapsApiFilledIntentParams = {}): UseQueryResult<IntentStateV2 | undefined, Error> => {
+  const { sodax } = useSodaxContext();
+  const txHash = params?.txHash;
+  const apiConfig = params?.apiConfig;
+
+  return useQuery({
+    queryKey: ['swapsApi', 'filledIntent', txHash],
+    queryFn: async (): Promise<IntentStateV2 | undefined> => {
+      if (!txHash) return undefined;
+      return unwrapResult(await sodax.api.swaps.getFilledIntent(txHash, apiConfig));
+    },
+    enabled: !!txHash && txHash.length > 0,
+    retry: 3,
+    ...queryOptions,
+  });
+};

package/src/hooks/swapsApi/useSwapsApiIntent.ts

@@ -0,0 +1,40 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import type { GetIntentResponseV2, RequestOverrideConfig } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseSwapsApiIntentParams = ReadHookParams<
+  GetIntentResponseV2 | undefined,
+  {
+    txHash: string | undefined;
+    apiConfig?: RequestOverrideConfig;
+  }
+>;
+
+/**
+ * React hook to look up an Intent struct by its hub-chain creation tx hash via the swaps API —
+ * `sodax.api.swaps.getIntent`. The decoded intent's bigint fields are returned as decimal strings.
+ *
+ * @example
+ * const { data: intent } = useSwapsApiIntent({ params: { txHash: '0x123...' } });
+ */
+export const useSwapsApiIntent = ({
+  params,
+  queryOptions,
+}: UseSwapsApiIntentParams = {}): UseQueryResult<GetIntentResponseV2 | undefined, Error> => {
+  const { sodax } = useSodaxContext();
+  const txHash = params?.txHash;
+  const apiConfig = params?.apiConfig;
+
+  return useQuery({
+    queryKey: ['swapsApi', 'intent', txHash],
+    queryFn: async (): Promise<GetIntentResponseV2 | undefined> => {
+      if (!txHash) return undefined;
+      return unwrapResult(await sodax.api.swaps.getIntent(txHash, apiConfig));
+    },
+    enabled: !!txHash && txHash.length > 0,
+    retry: 3,
+    ...queryOptions,
+  });
+};