API Reference

🤖 Configuration Options

Configure Map3 Supercharge SDK with the required fields or customize it to make it your own.

const supercharge = initMap3Supercharge({
  anonKey: '<YOUR_MAP3_ANON_KEY>',
  userId: '<YOUR_END_USER_ID>' // a user identifier (like an UUID)
});

Required Fields

anonKey

Generated via the console. Anon keys are public and can be safely used and exposed in a browser environment. They encode your organization ID and a role (anon). Anon key allows read access, but not write. They are required.

userId

A unique identifier for the active user. An email, uuid, or any other unique identifier is required.

const supercharge = initMap3Supercharge({
  userId: '[email protected]'
});

📘

The above configuration is only using the two required fields anonKey and generateDepositAddress. To see all the required and optional fields review the Config Interface

Getting your Anon Key

  1. Go to https://console.map3.xyz
  2. Create your account
  3. Set up an organization
  4. Visit https://console.map3.xyz/tokens

callbacks

handleAuthorizeTransaction (optional)

An optional callback that gets called before the user is allowed to submit a transaction via their wallet.

// checkIfAuthorizedToTransact is implemented by your system

const supercharge = initMap3Supercharge({
  options: {
    callbacks: {
      handleAuthorizeTransaction: async (fromAddress, networkCode, amount) => {
        // perform some async check on your backend
        const isAuthorizedToTransact = await checkIfAuthorizedToTransact(
          fromAddress,
          networkCode,
          amount
        );

        return isAuthorizedToTransact;
      },
    },
  },
});

handleOrderFeeCalculation (optional)

You may charge your users fixed fees and/or variable fees. You may also want to provide them a message. We'll send you the asset symbol, networkCode, and amount selected. And you must respond with fixedFee|| variableFee|| message

const supercharge = initMap3Supercharge({
  options: {
    callbacks: {
      handleOrderFeeCalculation: (
        asset: string,
        networkCode: string,
        amount: string
      ) => {
        const { fixedFee, message, variableFee } = doFeeCalculation(
          asset,
          networkCode,
          amount
        );
        
        return {
					fixedFee: fixedFee, 
					message: message,
					variableFee: variableFee
        }
      },
    },
  },
});

onAddressRequested (optional)

This function returns the deposit address for the user's wallet for the asset and network they've selected. Map3 Supercharge SDK does not generate wallet addresses on behalf of your users.

// fetchDepositAddressForUser is implemented by your system

const activeUserId = 'active-user-id';

const supercharge = initMap3Supercharge({
  options: {
    callbacks: {
      onAddressRequested: async (asset, networkCode) => {
        const address = await fetchDepositAddressForUser(
          asset,
          networkCode,
          activeUserId
        );

        return { address };
      },
    },
  },
});

onClose (optional)

onExpire (optional)

onFailure (optional)

onSuccess (optional)

onOrderCreated (optional)

Called once your end-user has confirmed intention to deposit via one of our merchant integrations.

const supercharge = initMap3Supercharge({
  options: {
    callbacks: {
      onOrderCreated: async (orderId: string, type: string) => {
        saveOrderInDb(orderId, type);
      },
    },
  },
});

selection

address (optional)

The address of the ERC-20 token for the user to deposit. Must be used with networkCode or defaults to undefined.

const supercharge = initMap3Supercharge({
  options: {
    selection: {
      address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
      networkCode: 'ethereum',
    },
  },
});

amount (optional)

The amount of crypto in minor units you require the user to deposit.

const supercharge = initMap3Supercharge({
  options: {
    selection: {
      amount: '10050000000', // 100.5 BTC
      networkCode: 'bitcoin',
    },
  },
});

❗️

networkCode is required

When using amount, you must specify at least a networkCode, otherwise we will fallback to amount as undefined. You can also specify networkCode and address (if depositing an ERC-20 asset).

assetId (optional)

If you know the Map3 assetId (e.g fe2bf2f8-3ddc-4ccc-8f34-8fdd9be03884 USDC on Polygon) you can pass in the assetId and skip directly to payment method selection. If you have more questions about the Map3 assetId please review Metadata Documentation.

const supercharge = initMap3Supercharge({
  options: {
    selection: {
      assetId: 'fe2bf2f8-3ddc-4ccc-8f34-8fdd9be03884',
    },
  },
});

fiat (optional)

Fiat currency of your user's preference. Default value is USD.

networkCode (optional)

If the user wants to deposit the native token (e.g Ether on Ethereum) you can pass in a networkCode to skip asset and network selection and jump directly to payment method selection.

const supercharge = initMap3Supercharge({
  options: {
    selection: {
      networkCode: 'ethereum',
    },
  },
});

networkCode and address (optional)

You may not know the Map3 assetId but still want to skip directly to payment method selection. You can do this by passing in a networkCode and address. The following example will preselect USDC on Polygon.

const supercharge = initMap3Supercharge({
  options: {
    selection: {
      address: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174',
      networkCode: 'polygon',
    },
  },
});

paymentMethod(optional)

Pass in binance-pay or show-address payment methods to auto-select that method for your user.

style

appName (optional)

colors (optional)

Change the primary and accent colors.

const supercharge = initMap3Supercharge({
  options: {
    style: {
      colors: {
        accent: '#dfff86',
        primary: '#0e1523',
      },
    },
  },
});

embed (optional)

Instead of the SDK opening in a modal (default) you can choose to embed it directly inside an element in your app.

const supercharge = initMap3Supercharge({
  options: {
    style: {
      embed: {
        height: '500px',
        id: 'supercharge-goes-here',
        width: '320px',
      },
    },
  },
});

theme (optional)

light or dark mode is supported. light by default.

Config Interface

interface Map3InitConfig {
  anonKey: string;
  options?: {
    callbacks?: {
      handleAuthorizeTransaction?: (
        fromAddress: string,
        networkCode: string,
        amount: string
      ) => Promise<Boolean>;
      handleOrderFeeCalculation?: (
        asset: string,
        networkCode: string,
        amount: string
      ) => Promise<{
        fixedFee?: number;
        message?: string;
        variableFee?: number;
      }>;
      onAddressRequested?: (
        asset: string,
        networkCode: string
      ) =>
        | Promise<{ address: string; memo?: string }>
        | { address: string; memo?: string };
      onClose?: () => void;
      onExpire?: () => void;
      onFailure?: (
        error: string,
        networkCode: string,
        address?: string
      ) => void;
      onOrderCreated?: (orderId: string, type: string) => void;
      onSuccess?: (
        txHash: string,
        networkCode: string,
        address?: string
      ) => void;
    };
    selection?: {
      address?: string;
      amount?: string;
      assetId?: string;
      expiration?: string | number;
      fiat?: string;
      networkCode?: string;
      paymentMethod?: 'binance-pay';
      rate?: number;
      shortcutAmounts?: number[];
    };
    style?: {
      appName?: string;
      colors?: {
        accent?: string;
        primary?: string;
      };
      embed?: {
        height?: string;
        id?: string;
        width?: string;
      };
      locale?: 'en' | 'es';
      theme?: 'dark' | 'light';
    };
  };
  userId: string;
}