React SDK
The target structure for @sdk.markets/react and its hooks.
@sdk.markets/react is the declarative layer on top of @sdk.markets/sdk.
It is built for:
- React
- TanStack Query
- wagmi
- Privy-friendly wallet flows
Provider setup
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { WagmiProvider } from "wagmi";
import { MarketsProvider } from "@sdk.markets/react";
const queryClient = new QueryClient();
export function Providers({ children }: { children: React.ReactNode }) {
return (
<WagmiProvider config={wagmiConfig}>
<QueryClientProvider client={queryClient}>
<MarketsProvider
environment="sandbox"
apiKey={process.env.NEXT_PUBLIC_MARKETS_API_KEY!}
>
{children}
</MarketsProvider>
</QueryClientProvider>
</WagmiProvider>
);
}MarketsProvider should read:
- project API key and environment
- app auth / session context
- wagmi account and wallet-client state
- query client context
Hook categories
Market hooks
useMarket(marketAddress)
useMarkets(addresses)
useMarketPosition(marketAddress, user?)
useMarketEvents(marketAddress)Write hooks
useCreateMarketDirect()
useBuyIn()
useSubmitResolution()
useSubmitAdminVote()
useSubmitDispute()
useFinalizeMarket()
useRedeem()
useRefund()
useVoidMarket()Hosted creation hooks
useValidateDraft()
useGenerateDraft()
useCreateMarket()
useCreateMarketAndWait()
useJob(jobId)Account hooks
useUsdcBalance(user?)
useUsdcAllowance(spender, user?)
useApproveUsdc()
useMarketsWalletState()Privy embedded wallets
The React package should work cleanly with a Privy-backed wagmi setup.
That means hooks need to handle more than just "connected or not":
- missing API key
- missing auth
- authenticated but no embedded wallet yet
- wallet provisioning in progress
- wallet ready
- wrong chain
- write client unavailable
useMarketsWalletState() should normalize those cases so apps do not repeatedly rebuild the same
gating logic.
Cache and invalidation
The React package should export query keys for manual invalidation when needed:
import { marketsKeys } from "@sdk.markets/react";
queryClient.invalidateQueries({
queryKey: marketsKeys.market.detail(marketAddress),
});Mutation hooks should also invalidate the obvious reads automatically after successful writes.
Why a separate package
Keeping @sdk.markets/react separate from @sdk.markets/sdk gives us cleaner boundaries:
- the core SDK stays usable outside React
- React-only dependencies stay out of the core package
- frontend apps get higher-level hooks without losing access to direct client methods