@sodax/dapp-kit 2.0.0-rc.2 → 2.0.0-rc.20

package/src/hooks/shared/useNearStorageCheck.ts

@@ -0,0 +1,45 @@
+import { ChainKeys, type SpokeChainKey } from '@sodax/sdk';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { useSodaxContext } from './useSodaxContext.js';
+import type { ReadHookParams } from './types.js';
+
+export type UseNearStorageCheckParams = ReadHookParams<
+  boolean,
+  {
+    token: string | undefined;
+    accountId: string | undefined;
+    chainId: SpokeChainKey | undefined;
+  }
+>;
+
+/**
+ * Whether `accountId` is NEP-141 storage-registered for `token` on NEAR — the receive-side
+ * prerequisite for any leg that delivers a token to the user on NEAR (swap output on NEAR, bridge
+ * into NEAR, money-market borrow/withdraw to NEAR). NEAR's analogue of a Stellar trustline.
+ *
+ * Returns `true` (no gate) when `chainId` is not NEAR, mirroring how the Stellar trustline check
+ * short-circuits off-chain. Native NEAR is not a NEP-141 token, so the SDK reports it as registered.
+ *
+ * Pair with {@link useRegisterNearStorage} to perform the one-time `storage_deposit` when this
+ * resolves to `false`.
+ */
+export function useNearStorageCheck({
+  params,
+  queryOptions,
+}: UseNearStorageCheckParams = {}): UseQueryResult<boolean, Error> {
+  const { sodax } = useSodaxContext();
+  const token = params?.token;
+  const accountId = params?.accountId;
+  const chainId = params?.chainId;
+
+  return useQuery<boolean, Error>({
+    queryKey: ['shared', 'nearStorageCheck', chainId, token, accountId],
+    queryFn: async () => {
+      if (chainId !== ChainKeys.NEAR_MAINNET) return true;
+      if (!token || !accountId) return false;
+      return sodax.spoke.near.isStorageRegistered(token, accountId);
+    },
+    enabled: !!token && !!accountId,
+    ...queryOptions,
+  });
+}

package/src/hooks/shared/useNearStorageGate.ts

@@ -0,0 +1,60 @@
+import type { GetWalletProviderType, INearWalletProvider, Result, SpokeChainKey } from '@sodax/sdk';
+import { resolveNearStorageGate } from '../../utils/nearStorageGate.js';
+import { useNearStorageCheck } from './useNearStorageCheck.js';
+import { useRegisterNearStorage } from './useRegisterNearStorage.js';
+
+interface UseNearStorageGateParams {
+  /** Destination chain the token is delivered on. */
+  dstChainKey: SpokeChainKey;
+  /** Destination token address the recipient must be registered for. */
+  token: string | undefined;
+  /** Recipient NEAR account id. */
+  accountId: string | undefined;
+  /** Destination wallet provider; only consumed when it is the NEAR provider. */
+  walletProvider: GetWalletProviderType<SpokeChainKey> | undefined;
+}
+
+interface NearStorageGate {
+  /** Destination is NEAR. */
+  isNear: boolean;
+  /** Destination is NEAR and the recipient is not yet storage-registered for `token`. */
+  needsRegistration: boolean;
+  /** The downstream action must stay disabled while the gate is unresolved or unmet. */
+  blocksAction: boolean;
+  /** The registration-status query is actively fetching. */
+  isChecking: boolean;
+  /** A `storage_deposit` tx is in flight. */
+  isRegistering: boolean;
+  /** Submit the `storage_deposit`; resolves to the SDK `Result` or `undefined` if inputs are missing. */
+  registerStorage: () => Promise<Result<string> | undefined>;
+}
+
+/**
+ * NEP-141 storage-registration gate for flows that deliver a token to a user on NEAR.
+ */
+export function useNearStorageGate({
+  dstChainKey,
+  token,
+  accountId,
+  walletProvider,
+}: UseNearStorageGateParams): NearStorageGate {
+  const nearWalletProvider = walletProvider?.chainType === 'NEAR' ? (walletProvider as INearWalletProvider) : undefined;
+
+  const storageCheck = useNearStorageCheck({ params: { token, accountId, chainId: dstChainKey } });
+  const { mutateAsyncSafe: register, isPending: isRegistering } = useRegisterNearStorage();
+  const { isNear, needsRegistration, blocksAction } = resolveNearStorageGate(dstChainKey, storageCheck);
+
+  const registerStorage = async (): Promise<Result<string> | undefined> => {
+    if (!nearWalletProvider || !token || !accountId) return undefined;
+    return register({ token, accountId, walletProvider: nearWalletProvider });
+  };
+
+  return {
+    isNear,
+    needsRegistration,
+    blocksAction,
+    isChecking: storageCheck.isLoading,
+    isRegistering,
+    registerStorage,
+  };
+}

package/src/hooks/shared/useRegisterNearStorage.ts

@@ -0,0 +1,46 @@
+import { ChainKeys, type INearWalletProvider } from '@sodax/sdk';
+import { useQueryClient } from '@tanstack/react-query';
+import { useSodaxContext } from './useSodaxContext.js';
+import type { MutationHookParams } from './types.js';
+import { useSafeMutation, type SafeUseMutationResult } from './useSafeMutation.js';
+
+export type UseRegisterNearStorageVars = {
+  token: string;
+  accountId: string;
+  walletProvider: INearWalletProvider;
+  /** Storage bond override; defaults to the SDK's `NEAR_STORAGE_DEPOSIT` (0.00125 NEAR). */
+  deposit?: bigint;
+};
+
+/**
+ * Submit a NEP-141 `storage_deposit` so `accountId` can receive `token` on NEAR. NEAR's analogue of
+ * requesting a Stellar trustline; pair with {@link useNearStorageCheck} and call this when the check
+ * resolves to `false`. The recipient's NEAR wallet signs the registration tx.
+ *
+ * Pure mutation: pass `{ token, accountId, walletProvider }` to `mutate(...)`. The hook itself only
+ * takes the structural `mutationOptions` slot. `registerStorage` throws natively (no `Result<T>`),
+ * so this hook is registered as `nativeThrow` in the mutation contract. On success it invalidates
+ * the matching {@link useNearStorageCheck} query.
+ */
+export function useRegisterNearStorage({
+  mutationOptions,
+}: MutationHookParams<string, UseRegisterNearStorageVars> = {}): SafeUseMutationResult<
+  string,
+  Error,
+  UseRegisterNearStorageVars
+> {
+  const { sodax } = useSodaxContext();
+  const queryClient = useQueryClient();
+  return useSafeMutation<string, Error, UseRegisterNearStorageVars>({
+    mutationKey: ['shared', 'registerNearStorage'],
+    ...mutationOptions,
+    mutationFn: async ({ token, accountId, walletProvider, deposit }) =>
+      sodax.spoke.near.registerStorage({ token, accountId, walletProvider, deposit, raw: false }),
+    onSuccess: async (data, vars, ctx) => {
+      queryClient.invalidateQueries({
+        queryKey: ['shared', 'nearStorageCheck', ChainKeys.NEAR_MAINNET, vars.token, vars.accountId],
+      });
+      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,
+  });
+};

package/src/hooks/swapsApi/useSwapsApiIntentExtraData.ts

@@ -0,0 +1,41 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import type { IntentExtraDataRequestV2, IntentExtraDataResponseV2, 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 UseSwapsApiIntentExtraDataParams = ReadHookParams<
+  IntentExtraDataResponseV2 | undefined,
+  {
+    body: IntentExtraDataRequestV2 | undefined;
+    apiConfig?: RequestOverrideConfig;
+  }
+>;
+
+/**
+ * React hook to recover the relay extra data needed by `/swaps/intents/submit` via the swaps API —
+ * `sodax.api.swaps.getIntentSubmitTxExtraData`. Provide EITHER `txHash` OR `intent` in the body
+ * (whose `bigint` numerics are serialized by the SDK). Returns `{ address, payload }`.
+ *
+ * @example
+ * const { data } = useSwapsApiIntentExtraData({ params: { body: { txHash: '0x123...' } } });
+ */
+export const useSwapsApiIntentExtraData = ({
+  params,
+  queryOptions,
+}: UseSwapsApiIntentExtraDataParams = {}): UseQueryResult<IntentExtraDataResponseV2 | undefined, Error> => {
+  const { sodax } = useSodaxContext();
+  const body = params?.body;
+  const apiConfig = params?.apiConfig;
+
+  return useQuery({
+    queryKey: ['swapsApi', 'intentExtraData', body?.txHash ?? body?.intent?.intentId?.toString()],
+    queryFn: async (): Promise<IntentExtraDataResponseV2 | undefined> => {
+      if (!body || (!body.txHash && !body.intent)) return undefined;
+      return unwrapResult(await sodax.api.swaps.getIntentSubmitTxExtraData(body, apiConfig));
+    },
+    enabled: !!body && (!!body.txHash || !!body.intent),
+    retry: 3,
+    ...queryOptions,
+  });
+};