The Safe Apps SDK helps developers to build their dapps into the Safe{Wallet}. It turns a dapp into an HTML iframe component that can be accessed through Safe. This SDK provides extensive developer tooling to make it easy to create, test, and integrate Safe Apps into Safe. This includes a design system, reusable components, and a Safe App SDK that facilitates communication between the Safe App and Safe.
Here are several packages to make it easier to integrate third-party applications (Safe Apps) with Safe. Check the following diagram to see which package is suitable for you:
Package | Version | Description |
| CRA (Create React App) template to bootstrap a Safe App. Use this package to start a new Safe App from scratch using React. | |
A wrapper of safe-apps-sdk with helpful React Hooks. | ||
JavaScript SDK. This is the base package for all integrations. | ||
A generic provider that can be used with common web3 libraries. For example, web3.js or Ethers. | ||
A wrapper around Web3Modal that would automatically connect to the Safe when the app is loaded in the Safe Apps section. | ||
| A wagmi connector for Safe Apps. | |
| Blocknative included Safe App support in @web3-onboard v1.26.0. If you are already using this package, you can check here how to configure it. | |
| web3-react already includes a connector for Safe Apps by default. You can check their docs on how to use it. |
⚠️ Safe Apps aren't owned, controlled, maintained, or audited by Safe. Safe can list or delist apps from Safe{Wallet} at its sole discretion. ⚠️
Getting started
Here are some resources to help you get started with building Safe Apps:
Safe Apps SDK packages
Whether you already have a dapp or are considering creating a new one, you will find it useful to rely on one of our integrations to communicate with Safe{Wallet}. You will find integrations with common packages like Web3Modal, Blocknative onboard.js, and web3-react in these packages.
For those creating a new dapp, using the CRA template. to kickstart the basic structure with all the necessary configuration will speed up the process.
Basic requirements
If you already have a dapp, some mandatory requirements exist to adapt your app to be used as a Safe App. Without this basic configuration, the dapp won't work with the Safe as expected.
If you are using our CRA template to start your Safe App, these basic requirements are already satisfied.
Manifest
It's mandatory that your app exposes a manifest.json file in the root directory with this structure:
{
"name": "YourAppName",
"description": "A description of what your app does",
"iconPath": "myAppIcon.svg"
}
Note: iconPath is the public relative path where Safe will try to load your app icon. For this example, it should be https://yourAppUrl/myAppIcon.svg.
CORS
Safe needs to reach the manifest.json from the app. To allow this, it's required to enable Cross Site Requests by setting the CORS headers to the manifest.json.
The required headers are:
"Access-Control-Allow-Origin": "\*",
"Access-Control-Allow-Methods": "GET",
"Access-Control-Allow-Headers": "X-Requested-With, content-type, Authorization"
React development
It's possible to use the local React development server. For this, you need to set the CORS headers and use the same protocol (HTTP or HTTPS) as the Safe interface you use for testing.
CORS for development
The Safe Apps SDK
For this, use react-app-rewired. To enable the library, update the scripts section in the package.json:
"scripts": {
"start": "react-app-rewired start",
"build": "react-app-rewired build",
"test": "react-app-rewired test"
},Also, create the config-overrides.js file in the project's root to configure the CORS headers. The content of the file should be:
/* config-overrides.js */
module.exports = {
// The function to use to create a webpack dev server configuration when running the development
// server with 'npm run start' or 'yarn start'.
// Example: set the dev server to use a specific certificate in https. devServer: function (configFunction) {
// Return the replacement function for create-react-app to use to generate the Webpack
// Development Server config. "configFunction" is the function that would normally have
// been used to generate the Webpack Development server config - you can use it to create
// a starting configuration to modify instead of creating a config from scratch.
return function (proxy, allowedHost) {
// Create the default config by calling configFunction with the proxy/allowedHost parameters
const config = configFunction(proxy, allowedHost);
config.headers = {
'Access-Control-Allow-Origin': '*',
'Access-Control-Allow-Methods': 'GET',
'Access-Control-Allow-Headers': 'X-Requested-With, content-type, Authorization',
};
// Return your customized Webpack Development Server config. return config
}
},
}
We also offer a middleware(opens in a new tab) in our React template for using frameworks like Express, Next.js, etc.
We also offer a middleware(opens in a new tab) in our React template for using frameworks like Express, Next.js, etc.
SSL
To enable SSL with react-scripts, it's necessary to set the HTTPS environment variable to true. This can be done in the package.json file by adjusting the scripts section to:
"scripts": { "start": "HTTPS=true react-app-rewired start",},If the SSL certificate provided by react-scripts isn't valid, it's required to mark it as trusted in your browser. To do this, open the Safe App in a separate tab (not in the Safe interface) and accept the certificate or ignore the warning.
UI Kit
Safe offers a react components package if you are creating your Safe App from scratch. This helps with a near-native look while enabling developers to use their branding in the Safe Apps.
Example app
This tutorial will build a Safe App that enables migrating all the assets from Safe to any other wallet in a single transaction. You will also learn about smart contract wallets, multi-signature transaction flow, and batched transactions.
Releasing your Safe App
Here are some details about the release process for Safe Apps.
Get your Safe Apps into the hands of users
Once you finish developing and testing your Safe App, your users can test it by opening the link to the hosted Safe App and adding it as a Custom App. This guide(opens in a new tab) explains how to add custom apps.
Get your Safe App listed in Safe{Wallet}
ℹ️
Due to limited resources, the Safe team can't ensure prompt app review. Please fill in this Google Form before submission.
If you would like your Safe App to appear in the Safe, it must meet the following criteria:
Smart contracts must be audited
Security is the top priority for Safe. Please provide an external audit result document if the Safe App includes smart contracts. If a third party created the smart contracts, ensure they are audited.
Your Safe App must include a manifest
There must be a manifest.json at the root directory containing the following data:
"name": "Name of your Safe App"
Your Safe App's name needs to have 50 characters maximum.
"iconPath": "your_logo.svg"
A relative file path to your App's logo. The icon must be a square SVG image of at least 128 by 128 pixels.
"description": "This is the Safe app description."
Few sentences describing your application, a maximum of 200 characters
You can find an example manifest file on GitHub. You can also find an example Safe App on IPFS here.
Remember that CORS needs to be configured correctly on the manifest.json so we can fetch the information as mentioned here.
The app auto connects to the Safe
When a user opens the app, it should automatically select the Safe as a wallet. Ensure to check the case if the user previously opened the app outside of the Safe with another wallet.
The Safe team has reviewed the Safe App
The requirement doesn't apply for battle-tested applications hosted on the same domain as the main dapp.
While we won't be able to do a proper audit for your Safe App, we still would like to look at the source code to raise issues or suggest improvements. Whether your Safe App is open or closed source, please send us either a link to the public repository or an invitation to the private repository.
We also would like to make a rough functional review of the App, so please provide us with a high-level test plan/feature list that allows our QA team to ensure everything works as intended in production. Video walk-throughs are also welcome.
Help us decode your Safe App transactions
We want to display interactions with Safe Apps as human-readable as possible. To do this, we need the ABI of the contracts your Safe App interacts with. The ideal way to do this would be to verify your contracts via Sourcify, which we can leverage to decode transactions interacting with those contracts.
Alternatively, you can provide us with the ABIs as JSON files or the links to the verified contracts on Etherscan so we can implement transaction decoding for your Safe App interactions.
Official launch and beyond
After we have reviewed and integrated your Safe App, the App will first be available in the staging environment of the Safe for you to do a final review. We would then approach you to coordinate the launch and a joint announcement.
At any point after the launch, if you or your users encounter issues with the Safe App or want to release an update to an existing Safe App, please contact us via Discord
While developing your Safe App, you can use our production interface to test it. Some testnets like Sepolia are also available.
Once your app is live, even if you run it locally, you can import it to the Safe application as a custom app. To do so, you should select the "Apps" tab:
Use the Add custom app button and add your app using a link:
