If you would like to make use of the-box's routes & bridging, but would like to provide your own UI, you can make use of the box-hooks library!

Installation

Simply Install the '@decent.xyz/box-hooks' UI package from your favorite package manager.

npm i @decent.xyz/the-box // or pnpm or yarn

Please ensure you have also installed wagmi/core and, if you are using viem, that your wagmi, wagmi/core, and viem versions do not conflict.

Environment Variables

You'll need a Decent API key. Head over to this section to get one. Once you have it, store the API key in your .env file.

# .env file 
DECENT_API_KEY=your-api-key

Using Box Hooks

TLDR, show me a working example!

If you'd like to skip to a working example and see how box-hooks are used, check out our box-examples repository! You can see the deployment of that repository here. Pretty much all the code for using box-hooks is located in this file.

BoxHooksContextProvider

Use this context provider at the top of the component tree, where you'd want to use The Box's hooks. Usually this is done in your _app.tsx.

export default function ExamplePage() {

  return (
    <Layout>
      <BoxHooksContextProvider
        apiKey={process.env.NEXT_PUBLIC_DECENT_API_KEY as string}
      >
        {
          /*
          rest of your app
           */
        }
      </BoxHooksContextProvider>
    </Layout>
  );
}

Note: for the env var you do not have to use the DECENT_API_KEY name. The context provider accepts any API key as an input so feel free to rename it to anything else you would like.

useBoxAction(args: UseBoxActionArgs)

This is the main hook that provides you with:

1. Cost information
2. Transaction data that you can submit from your dapp

UseBoxActionArgs

The argument to useBoxAction has the following type:

type UseBoxActionArgs = {
  sender: string;

  srcToken: string;
  srcChainId: ChainId;
  dstToken: string;
  dstChainId: ChainId;
  slippage: number;

  actionType: ActionType;
  actionConfig: ActionConfig;
  enable?: boolean;
};

Here's a description of each field.

An example of this, this is the same example used in our examples repository.

import { ChainId } from '@decent.xyz/box-hooks';


const args: UseBoxActionArgs = {
  actionType: ActionType.NftMint,
  actionConfig: {
    contractAddress: '0x3007E0eB44222AC69E1D3c93A9e50F9CA73F53a1',
    chainId: ChainId.ARBITRUM,
    cost: {
      isNative: true,
      amount: parseUnits('0.00005', 18),
    },
  },
  srcChainId: ChainId.POLYGON,
  sender: sender!,
  slippage: 1, // 1%
  srcToken: '0x2791bca1f2de4661ed88a30c99a7a9449aa84174', // USDC on Polygon
  dstToken: '0x0000000000000000000000000000000000000000', // ETH
  dstChainId: ChainId.ARBITRUM,
};

Then you can pass these args into the hook to get the action response:

  const { actionResponse, isLoading, error } = useBoxAction(getActionArgs);

isLoading & error can bee used in your UI to handle loading & error cases.

ActionResponse

actionResponse has the following type

export type BoxActionResponse = {
  tx: Transaction;
  tokenPayment?: Payment;
  applicationFee?: Payment;
  bridgeFee?: Payment;
  bridgeId?: BridgeId;
};

You can then submit the transaction using your favorite Ethereum library as follows:

const tx = actionResponse.tx;
const gas = await publicClient.estimateGas({
  account,
  ...tx,
} as unknown as EstimateGasParameters);
const response = await sendTransaction({
  ...tx,
  gas,
});

We recommend viem because it is awesome. You can see all of this in action here.

useUsersBalances

Given a wallet address & a [ChainId](https://docs.decent.xyz/docs/common-types#chainid), this hook will return all the assets for that address. Check out here for a working example, and here for a code sample using it.

import {
  useUsersBalances,
  ChainId,
} from '@decent.xyz/box-hooks';
import { useAccount } from 'wagmi';


const TokenSelectorUsage = () => {
  const { address } = useAccount();
  const chainId = ChainId.ARBITRUM;
  const [srcToken, setSrcToken] = useState<TokenInfo>(ethGasToken);

  const { tokens } = useUsersBalances({
    address: address!,
    chainId,
    enable: Boolean(address),
  });
// etc. 
}

Inputs to useUsersBalances:

address: user's address.

chainId: chain id, available types are here.

enable (optional): set to false to disable the query for automatically running - similar to wagmi's enabled option.

Return Type

An array of [UserTokenInfo](https://docs.decent.xyz/docs/common-types#usertokeninfo)'s.

Here's an example:

  {
    "name": "Ether",
    "symbol": "ETH",
    "decimals": 18,
    "balanceFloat": 0.3438013580730053,
    "balance": "343801358073005350n",
    "address": "0x0000000000000000000000000000000000000000",
    "isNative": true,
    "logo": "https://cryptologos.cc/logos/ethereum-eth-logo.png?v=025",
    "chainId": 42161
  },
  {
    "address": "0xff970a61a04b1ca14834a43f5de4533ebddb5cc8",
    "decimals": 6,
    "name": "USD Coin (Arb1)",
    "symbol": "USDC",
    "totalSupply": {
      "formatted": "0.000678580390713551",
      "value": "678580390713551n"
    },
    "isNative": false,
    "chainId": 42161,
    "logo": "https://static.alchemyapi.io/images/assets/3408.png",
    "balanceFloat": 2881.777809,
    "balance": "2881777809n"
  },

  {
    "address": "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9",
    "decimals": 6,
    "name": "Tether USD",
    "symbol": "USDT",
    "totalSupply": {
      "formatted": "0.000666157066365669",
      "value": "666157066365669n"
    },
    "isNative": false,
    "chainId": 42161,
    "logo": "https://static.alchemyapi.io/images/assets/825.png",
    "balanceFloat": 5.004789,
    "balance": "5004789n"
  }
]