# Whitepaper Harpie monitors your wallet for threats and responds to attacks in real time. ## Abstract Harpie protects your Ethereum wallet from crypto theft. We monitor your wallet for threats and respond to attacks in real-time. We've protected thousands of users from scams, hacks, and even private key theft! There are two major components to Harpie: * **Monitoring:** Harpie monitors your wallet, constantly looking for vulnerabilities or threats. When we see one, we notify you and help you fix it right away. * **Recovery:** Even if you fall victim to a hack or a scam, we'll respond in real-time, saving your assets before they're lost forever. We actively protect over $100M in assets across all Harpie users, and we're partnered with major companies, including OpenSea, Coinbase, and others. ## Introduction > It's a bullish day for Ethereum, and you've decided to rebalance some of your tokens into ETH. You hop on your favorite DEX and go through the exchange process as usual. > > Even though you've given the protocol your tokens, the ETH never lands in your wallet. After a few minutes, you start wondering what's going on. You're about to make a report, but you see a tweet from the protocol that makes your stomach sink: > > "Frontend is compromised. Do not use until further notice!" > > **You've just been robbed, and there was nothing you could have done about it.** Crypto shouldn't feel scary to use, but stories like the above happen every day to every subset of crypto user—from yield farmers, to NFT whales, to everyday hobbyists. Theft is becoming rampant in the crypto space. Crypto users deal with attacks like [website hijackings](https://rekt.news/curve-finance-rekt/), [social engineering scams](https://twitter.com/BoredApeYC/status/1518637579633053701), and [social media misinformation](https://www.cnbc.com/2021/07/21/man-busted-for-twitter-hack-of-biden-obama-musk-in-bitcoin-scam.html) on an almost-daily basis. Harpie protects you from crypto theft. We scan your wallet, notify you of any issues, and fix them for you. We've protected thousands of users from scams, hacks, and even private key theft. ## How it works: summary Harpie works in two steps: monitoring and recovery. We monitor your wallet, constantly looking and fixing any vulnerabilities we find. We're also prepared for the worst: should you fall victim to a scam or hack, we can recover your assets in real-time. If you're worried about your wallet security, Harpie is the complete solution: we both prevent attacks and respond to security emergencies. ### Monitoring Harpie detects your security vulnerabilities and helps you address them immediately. Whenever you interact with an on-chain service, you open yourself to extreme risk. Most on-chain services ask you to open an *approval*, which allows that service to transfer assets out of your wallet at any time. These approvals often have devastating consequences: * If an on-chain service you've used in the past gets hacked, hackers can use an open approval to steal all your crypto * If there's a bug within an on-chain service you've used, hackers can exploit them to drain your assets. * OpenSea approvals allow hackers to trick you into "private selling" all their NFTs to them for 0 ETH We notify you of these vulnerabilities and help you fix them before they become a problem. ### Recovery In case of emergencies, Harpie can respond before hackers get their hands on your crypto. * Our **Transaction Firewall** integrates with any wallet you're using. If we detect that you're accidentally sending money to a scammer, we can prevent that transaction from ever hitting the blockchain! * Our **Vault** is our last line of defense. We're able to see pending transactions on the blockchain. If we see that you've signed and sent your money away to a scammer, we can intervene in real-time, preventing that transfer from ever happening. Both of these emergency recovery options give us a lot of trust: because of that, they're both totally opt-in. They're the most advanced security tools for individual users, so if you truly care about making your wallet security bulletproof, you'll be able to activate these features in your dashboard # What attacks can Harpie prevent? Read more on the various web3 attacks that Harpie is built to protect you against. Below is a list of many (but not all) of the types of attacks that Harpie can prevent. ### Frontend Attacks

$570k was stolen in just a few hours because of the Curve.fi attack

This attack is almost unavoidable. By hijacking a trusted website, attackers can trick users of the site into signing their money away. ### Phishing/Impersonation

This OpenSea phishing link was a single email campaign that caused $1.7 million in damages.

These types of attacks impersonate a trustworthy party. Attackers use this misplaced trust to trick victims into signing malicious smart contracts designed to steal their money. ### Fake Site Scam
These attacks use a clean, well-designed website to trick victims into trusting the site. Afterwards, victims are asked to sign malicious smart contracts or send over their private keys to the attacker as part of a "user onboarding" process. ### Private Key Theft Private key theft is being phased out in favor of smart-contract-based attacks, like the attacks described above. That being said, ownership of a wallet's private key allows an attacker to freely transact with the assets inside. Because private key theft gives an attacker complete control over your wallet and its assets, see [Disclosures & Risks](/welcome-to-the-harpie-docs/tech-and-security/disclosures-and-risks) for edge cases where Harpie would not be able to protect your wallet from private key thieves. ### Accidental Transfer Misspelling one of the 40 characters in an Ethereum address during a transfer can cause a victim to lose access to those assets permanently. Harpie stops accidental transfers from occurring, since your trusted network will not include that misspelled address. ### What types of attacks can Harpie not prevent? No security product is comprehensive, so for the sake of transparency, we've included info on our limitations in [Disclosures & Risks](/welcome-to-the-harpie-docs/tech-and-security/disclosures-and-risks). # Harpie's Anti-Theft Tech For those curious about how Harpie works under-the-hood, here's a quick rundown of how we protect our users from crypto theft. * **Background Check Engine:** We run regular scans of every Ethereum address, and we're able to find if it's involved in hacks, scams, money laundering, or any other illicit activity * **Transaction Firewall:** We pre-screen transactions before they get sent out to the blockchain, which lets us prevent users from signing scam transactions. * **Vault:** As a last line of defense, we're able to transfer vulnerable assets out of user wallets as soon as an attack is detected, using a trustless transfer system. All of these features are opt-in and configurable via the Harpie dashboard. # About the Transaction Firewall ### Introduction The Harpie RPC is an easy way to add two-factor-authentication to your transactions. Harpie RPC seamlessly plugs into your existing wallet, no downloads required. When you sign a transaction that could be dangerous (i.e. asset-bearing transactions, suspicious contract address), Harpie sends you a notification over email to confirm the transaction. The transaction requires an explicit verification over email before it's sent out to the network. ### What is a "dangerous transaction"? Harpie categorizes dangerous transactions as those that **can lose you money**. These generally are `approvals` and `transfers` of tokens and ETH, but also include gasless OpenSea signature scams. Dangerous transactions also include those where you try to interact with potentially bad wallets & smart contracts. These include, but are not limited to: * Bots * Phishing accounts * Honeypot contracts * Wallets linked to cybercrime ### How it works

Harpie RPC sits between your wallet and the blockchain, stopping potentially malicious transactions from draining your wallet.

Harpie RPC sits between your wallet and the blockchain. It scans outbound transactions from your wallet, notifying you if you are transacting with thieves, scammers, or other bad actors. We utilize large data models, lists of known criminal addresses, and hand-picked data to ensure that malicious transactions are caught. We have over 1,000,000 malicious addresses and 40,000 benign addresses in our database, with more being added every day. If your transaction gets flagged, you receive a notification over email to confirm the transaction. Now, you'll have a chance to review your transaction and view any **security warnings** that we've identified with the account.

An example email from Harpie RPC

If you approve the transaction, your transaction will be forwarded to Infura nodes to be confirmed on the blockchain. ### What are RPC modes?

After signing up with Harpie RPC, revisit or refresh the page to view your Harpie RPC dashboard.

After signing up with your email on Harpie RPC, you can access your dashboard at any time by revisiting the site and connecting with your wallet. There are 3 modes:
Name
OFFDisable Harpie RPC
NORMALGet notifications for suspicious transactions
STRICTGet notifications for EVERY transaction
On `NORMAL` mode, you should only receive a notification when interacting with dangerous addresses. That means you can interact with dApps like Curve, OpenSea, and Uniswap normally without having to check your email. However, just like your bank, we'll send you an email as soon as we see something suspicious. That way you can double check your transaction and stop a rug. ### Test Harpie RPC 1. First, make sure your wallet address is registered with Harpie 2. Next, switch to the `Harpie RPC` 3. Now, try sending `0.000001 ETH` to `vitalik.eth`. Vitalik's transaction history actually resembles that of a bot, so it gets flagged by our system 4. If everything is set up properly, you should get an email like this:

The email you get after trying to send ETH to Vitalik.eth

### How to use Harpie RPC Harpie is currently in *Early Access* as of writing this article. However, you can still sign up for Early Access by DM'ing [the official Harpie Twitter](https://twitter.com/harpieio) with this info: * Your wallet address (that you'd like to get whitelisted for) * Why you're excited to use Harpie RPC You will receive a response from the official Harpie account once you've been verified! # About the Harpie Vault Harpie identifies malicious transactions by having users set up a "trusted network" of protocols and peers. If your wallet sends a transfer to someone outside this trusted network, we stop that transaction from happening. We are able to eliminate these malicious transfers even after they're transmitted on-chain with an advanced strategy called [frontrunning](https://consensys.github.io/smart-contract-best-practices/attacks/frontrunning/). When a malicious transfer or approval is detected, we move your funds to a noncustodial vault before the transaction can confirm. By paying a higher gas fee, we have the ability to move your funds to the vault before the hacker can move your funds to their own wallet. Learn more about the "trusted network" concept: [What is a Trusted Network?](/welcome-to-the-harpie-docs/help/faq/what-is-a-trusted-network)
## Security: summary Harpie has rigorous security measures in place to ensure the safety of your assets. Our smart contracts have public code and public audits in place, so anyone can verify as well. Harpie works by transferring your assets out of your wallet and into a noncustodial vault before an attacker's transaction can execute. Because of this, we've made sure that our transfer mechanism is airtight. #### Transferer Contract When you sign up for Harpie, you'll give the [Transferer](/welcome-to-the-harpie-docs/tech-and-security/contracts/transferer) contract permission to transfer your tokens to our noncustodial vault. It cannot transfer your tokens anywhere else. When we detect an attack on your wallet, we use this `Transferer` contract to move your assets away from your compromised wallet. This smart contract can only move your assets to one location: our noncustodial `Vault` contract. #### Vault Contract The [Noncustodial Vault](/welcome-to-the-harpie-docs/tech-and-security/contracts/noncustodial-vault) contract is where you can withdraw your assets that have been transferred by our frontrunner. Only you can withdraw your assets from the `Vault;` there is no admin key that allows us to withdraw your assets on your behalf. #### Conclusion Because the `Transferer` contract can only move assets to the `Vault`, and since there is no ability for an admin to withdraw users' assets from the `Vault`, we feel that our system can responsibly handle the trust that comes with giving a contract access to transfer tokens. You can learn more about our contracts and the security programmed within them in [Contracts](/welcome-to-the-harpie-docs/tech-and-security/contracts). ## Frequently asked questions > Can I mint new NFTs even with a Harpie plan? Yes, you can. We only stop transactions when your protected tokens are at risk (i.e. `approvals` and `transfers`) Since the minting of an NFT is not a risky operation, we allow them to run through our filter. > What if I want to use a new protocol or project? Will I have to manually add it to my trusted network? We offer a curated list of the most popular & secure protocols, so you likely won't need to add any additional protocols. If you're using an all-new protocol, you're able to add them to your trusted network as a custom address. That being said, we recommend a strong amount of caution when adding custom addresses to your trusted network. > How does Harpie deal with mempool-obfuscating technology, like private mempools, Flashbots, etc.? Mempool-obfuscating technologies do not substantially affect our operations. An overwhelming majority of consumer-targeted attacks ask victims to sign the transaction that sends their assets over to an attacker. Since these transactions are self-signed, and our users are unlikely to use mempool obfuscators for their daily transactions, we find that mempool obfuscation is not a large concern for our usecase. Read more [FAQ](/welcome-to-the-harpie-docs/help/faq). # Security We've built Harpie's security with a great amount of care. Three core principles have guided our design: 1. Avoid custodianship of assets 2. Immutability > mutability 3. Avoid single points of failure ### Avoiding custodianship Harpie avoids custodianship by never allowing ourselves to withdraw users' stored tokens from our Vault. Users must explicitly designate a wallet address that's able to withdraw their stored assets. This layer of security makes sure that the most vulnerable side of smart contracts--token transfers--are airtight. [Read more](https://harpie.gitbook.io/welcome-to-the-harpie-docs/tech-and-security/contracts/noncustodial-vault). ### Immutability A large issue in smart contract security is the usage of mutable (changeable) variables. Harpie's contracts have immutable code and immutable address parameters (with the exception being the `feeController`). This ensures that users know exactly where their assets are being sent at all times. ### Avoiding single points of failure Because Harpie is not a decentralized protocol, we utilize admin addresses to handle essential functions, like calling frontrunning functions and reducing user fees. We've designed the system to have multiple admin roles, with each of these admin roles designed to be controlled by different parties and check-and-balance one another. Emergency roles exist to further augment this set of checks-and-balances. By doing so, we reduce the possibility and nullify the damages of any admin address hijacking. # Contracts A detailed breakdown of the Harpie smart contract architecture.
The Vault system operates on a two-contract system: The [Transferer](/welcome-to-the-harpie-docs/tech-and-security/contracts/transferer) contract has the ability to move your tokens to our noncustodial Vault. It cannot transfer your tokens anywhere else. The [Noncustodial Vault](/welcome-to-the-harpie-docs/tech-and-security/contracts/noncustodial-vault) contract allows you to withdraw tokens that we've transferred. Only you can withdraw your assets out of the noncustodial vault: neither Harpie nor any other entity has the ability to withdraw assets on your behalf. These contracts were designed to be easily-readable and easily-analyzed for any potential customer. # Deployments
ContractMainnet Address
Transferer0x7273d1671fCd37Ef5b949Ebf88234AA9c3E43957
Vault0x9cdE019F455b9a3C33d95912eDcEaBBe0cad3444
# Transferer The `Transferer` contract has the ability to move your tokens to our noncustodial `Vault`. It cannot transfer your tokens anywhere else. Below is a function-by-function explanation of the code. ### Roles ```solidity address immutable private vaultAddress; // set during construction address immutable private transferEOASetter; // set during construction mapping(address => bool) private _transferEOAs; ``` There are three roles (one dynamic, two immutable and set during construction) in this contract: * `vaultAddress` is the address of the associated [Noncustodial Vault](/welcome-to-the-harpie-docs/tech-and-security/contracts/noncustodial-vault) * `transferEOAs` are addresses that can call our [#transfer-functions](#transfer-functions "mention"). These addresses are controlled by our automated detection algorithm * `transferEOASetter` is an address owned by Harpie that can set `_transferEOAs` ### Transfer Functions ```solidity function transferERC721( address _ownerAddress, address _erc721Address, uint256 _erc721Id, uint128 _fee ) public returns (bool) function transferERC20( address _ownerAddress, address _erc20Address, uint128 _fee ) public returns (bool) function batchTransferERC721(ERC721Details[] memory _details) public returns (bool) function batchTransferERC20(ERC20Details[] memory _details) public returns (bool) ``` These functions transfer user assets into the `Vault` when we detect a malicious transaction. They're hardcoded to transfer tokens to the `vaultAddress` role, and cannot submit user tokens anywhere else. They are only callable by the `transferEOA` role. * The `transfer` functions transfer a single user's assets (ERC20/ERC721) to the Vault. * The `batchTransfer` functions are able to transfer multiple users' assets. We use these in case of large-scale attacks. ### Permission Functions ```solidity function addTransferEOA(address _newTransferEOA) public function removeTransferEOA(address _eoaToBeRemoved) public function removeAbilityToSetNewTransferEOAs() public ``` These functions are only callable by the role `transferEOASetter`. * `addTransferEEOA` and `removeTransferEOA` add and remove `transferEOAs`, the wallets that are able to call the [#transfer-functions](#transfer-functions "mention") * `removeAbilityToSetNewTransferEOAs` is a permanent operation that prevents the addition of any new `transferEOAs`. After calling this flag, Harpie is no longer able to add new wallets to the `transferEOA` role, but will still able to remove them. # Noncustodial Vault The `Vault` contract receives tokens from `Transferer` and allows users to withdraw those tokens at a later time. To withdraw those tokens, users will need to pay a fee in ETH. Below is a function-by-function explanation of the code. ### Roles #### User Roles ```solidity mapping(address => address) private _recipientAddress; ``` Each user on Harpie will have a registered `recipientAddress` that is able to withdraw their tokens transferred in by `Transferer`. #### Contract-wide Roles ```solidity address private immutable transferer; // set during construction address payable private feeController; address private immutable serverSigner; // set during construction address private immutable emergencyFeeRemover; // set during construction ``` There are four contract-wide roles (one dynamic, three immutable and set during construction) in this contract: * `transferer` is the address of the associated [Transferer](/welcome-to-the-harpie-docs/tech-and-security/contracts/transferer) * `feeController` is an address controlled by Harpie that's able to withdraw payments users have deposited and reduce individual users' fees * `serverSigner` is an address that we use to validate requests by users to change their `recipientAddress` * `emergencyFeeRemover` is an address of a multi-signature wallet that activates our [#emergency-functions](#emergency-functions "mention"), and this multi-sig has majority control by custodians outside the Harpie team ### Withdrawal Functions ```solidity function withdrawERC721( address _originalAddress, address _erc721Address, uint256 _id ) payable external function withdrawERC20( address _originalAddress, address _erc20Address ) payable external ``` These functions are only callable by a users' `recipientAddress`, and allow the `recipientAddress` to withdraw their tokens. * Caller must pay a fee in ETH to withdraw, currently set to 0 ### Recipient Address Functions ```solidity function setupRecipientAddress(address _recipient) external function changeRecipientAddress( bytes memory _signature, address _newRecipientAddress, uint256 expiry ) external ``` * `setupRecipientAddress` can only be called once by a user to set up their initial `recipientAddress` * `changeRecipientAddress` can be called by a user to change their `recipientAddress` * This requires a signature from our `serverSigner` for additional verification ### Log Functions ```solidity function logIncomingERC20( address _originalAddress, address _erc20Address, uint256 _amount, uint128 _fee ) external function logIncomingERC721( address _originalAddress, address _erc721Address, uint256 _id, uint128 _fee ) external ``` These functions store the value and fee for each user's stored tokens. * These functions are only callable from the `Transferer` contract, which run from functions only callable by `transferEOAs` ### FeeController Functions ```solidity function reduceERC20Fee( address _originalAddress, address _erc20Address, uint128 _reduceBy ) external returns (uint128) function reduceERC721Fee( address _originalAddress, address _erc721Address, uint256 _id, uint128 _reduceBy ) external returns (uint128) function withdrawPayments(uint256 _amount) external function changeFeeControllerRequest(address payable _newFeeController) external function changeFeeController() external ``` These functions are only callable by the role `feeController`. * The `feeController` can only reduce fees, never increase them * They can withdraw any fees stored in the contract, but never withdraw any tokens * `changeFeeController` has a timelock period of 14 days, which is begun by calling `changeFeeControllerRequest` ### Emergency Functions ```solidity function toggleEmergencyFlag(bool _newSetting) external function withdrawERC721WithoutFees( address _originalAddress, address _erc721Address, uint256 _id ) external function withdrawERC20WithoutFees( address _originalAddress, address _erc20Address ) external ``` These emergency functions allow users to freely withdraw their crypto irrespective of any fees. These are put in place to avoid the possibility of maliciously-set withdrawal fees created by an outside attacker. * `toggleEmergencyFlag` is only callable by `emergencyFeeRemover` * Once the flag is turned on, any user can withdraw their allocated balance without fees # Audit Harpie has been audited by Sherlock, and will be undertaking more contract audits in the future: {% embed url="" %} # Disclosures & Risks The risks you should be aware of when using Harpie. For the best interest & safety of our users, we've provided a list of edge cases and risks that the team is aware of. Working together with the Harpie community and the larger security community, we hope to address and eliminate many of these concerns as time moves forward. ### Edge cases The following are situations where we wouldn't be able to intervene on behalf of a user at the current moment: * An attack that occurs through a private mempool/Flashbots RPC * see our [FAQ](/welcome-to-the-harpie-docs/help/faq) * Although we don't see these types of attacks as large threats, we are building tools at the wallet-level to circumvent this vulnerability * A relevant edge case related to the above is the case of a pre-signed transaction being transmitted by a hacker through Flashbots RPC. At this point, this remains the most difficult vulnerability to handle. * At this point, Harpie is building up a detection algorithm that we can integrate with wallets to prevent this type of attack across the industry. That being said, this form of attack is extremely rare, and likely will not become a common attack vector for some time. * Protocol-level attacks (such as the [Beanstalk attack](https://rekt.news/beanstalk-rekt/)) where an attacker steals tokens that users have deposited into that protocol * At this point, Harpie does not prevent these large-scale attacks, but we, along with the security community as a whole, are working to stop these threats. * If you *personally* use a private mempool or Flashbots RPC to send day-to-day transactions through your wallet * At this point, Harpie cannot serve users using private mempools or Flashbots Protect RPC. * If an address you've added to your trusted network or approved turns out to be a malicious actor * To solve this, we curate lists of the most commonly-used protocols, so many users won't have to create their own trusted networks. * Specifically for private key theft: * Private keys are ultimately the deepest form of access into a wallet: Harpie is able to stop naive private key thieves, but advanced private key thieves may be able to change your recipient address * To solve this, we're developing 2-factor authentication features to our `changeRecipientAddress` function, so you can use a second factor to prevent this type of attack * If your transaction is included at the end of block formation. Our response time is a fraction of a second, but there is a small probability we may not be quick enough to be included in the same block as yours * To solve this, we're constantly working on improving our time-to-block, including using special gateways, maxing out our server efficiency, and optimizing our data-processing algorithms. ### Risks Exercise caution when interacting with a smart contract or blockchain application. Even after extensive auditing, smart contracts always have a vulnerability risk. Before interacting with a dApp or smart contract, make sure to do research on its trustworthiness. Check if a dApp has been publically audited or been a [part of a security breach](https://rekt.news/) before using it. ### Why would I use Harpie if there's ways around it? Harpie is by no means a comprehensive security product, and there are edge cases like the above that can cause it to fail. That being said, we cover almost all of the theft that occurs today, and we're poised to cover even more as we move forward. Our philosophy is to catch the 99.9% of theft that exists today, and to start the arms race for the last 0.1%. The cracks of Harpie only begin to show when we talk about the most sophisticated of thieves able to exploit those vulnerabilities—those well-versed in MEV and low-level Ethereum nuances. These types of attackers, while scary, are an overwhelming minority: a [2020 report by the United States FBI ](https://www.ic3.gov/Media/PDF/AnnualReport/2020_IC3Report.pdf)shows that almost all cybercrime stems from high-volume, low-finesse social engineering attacks like phishing and confidence fraud. Although the release of Harpie marks the start of the crypto consumer security arms race, we find that we're poised to make a solid stand. We plan to integrate our detection algorithms in as many places as we can, and through that, remove the possibility of mempool obfuscation. We also don't stand alone: we're invested in and connected with the best of the Ethereum security community. While there has never been a security product with a 0% failure rate, we think we're close to it, and we're poised to get exponentially closer to 0 as we move forward. We think that the question for a long time won't be "how will Harpie deal with attackers?" but rather "how will attackers respond to Harpie?" # Getting Started Everything you need to know to start using Harpie. At this time, we only support Desktop browsers. # Get Protected Learn how to get started with Harpie # Protecting a token or NFT Protecting an asset on Harpie in 60 seconds. ## Getting Started Protecting a token or NFT on Harpie ensures that your assets are protected from scams, hacks and theft. First, make sure that you have created an account. If you have not already, visit to get started. ### Enter your dashboard On [https://harpie.io ](https://harpie.io)click "Enter App" to be redirected to your dashboard. If you haven't connected a wallet or created an account, you will be prompted to do so at this time. Make sure that you are on the correct network! A wallet address will have a unique dashboard for each network. ### Choose the asset to protect On your dashboard, you will see all of your connected wallet's assets. If you do not see all of your assets, click "**Import assets"** or "**Refresh** **list"** to add it to our database.

Your dashboard's Protected Assets, where you can protect and import assets

Click **"Protect"** on the token or NFT you'd like to protect. At this time, we only support ERC721s. Do you want ERC1155 support? Request it [here.](https://discord.gg/WfBtxZfp85) ### Approve Harpie's smart contract A popup should appear on your Metamask. You will be asked to give Harpie permission to access your assets. Clicking **"Confirm"** on this transaction will allow us to move your protected asset out of your wallet in the event of an attack. Harpie's smart contracts have been audited and are completely non-custodial.

Example protection contract with Harpie

### Review and verify your Trusted Network Verify that your asset's status now says **"Protected"**. Check that your Trusted Network includes only the apps and friends you trust. # Setting a withdrawal address Learn how to set a withdrawal address so that you can withdraw recovered assets. ## Getting Started In order to withdraw your funds after our frontrunner intervenes, you must set a withdrawal address. This withdrawal address has the ability to retrieve the funds that are being held in the vault. Setting a withdrawal address will cost gas. First, make sure that you have created an account. If you have not already, visit to get started. ### Identify a wallet address you own and trust You can only withdraw recovered tokens from Harpie using a wallet *you own*. A withdrawal address can be a smart contract compatible multisig or a newly created Metamask wallet or anything in between. Verify that you can access the wallet associated with the withdrawal address and that you have sufficient backups for it (i.e. seed phrase or private key backed up). As a rule of thumb: **use a withdrawal address that is different from your connected wallet.**[ Read more about best practices](/welcome-to-the-harpie-docs/help/faq/what-is-a-withdrawal-address). ### Initializing your withdrawal address There are two places to initialize a withdrawal address: 1. On the **dashboard** (look for "Complete Setup") 2. When [**withdrawing an asset**](https://harpie.gitbook.io/welcome-to-the-harpie-docs/guides/getting-started/faq/what-is-a-withdrawal-address) for the first time ### Initializing in "Complete Setup" On h[ttps://harpie.io](https://harpie.io), click **"Enter App"** and connect with your wallet. Follow the instructions and paste a wallet address that you own and trust.

Enter a valid address and accept the transaction

### Initializing when withdrawing a recovered asset If you've already protected an asset and Harpie recovered it from a theft attempt, you will see it on your dashboard here:

An example of what you will see on your dashboard when Harpie recovers your assets

Clicking **"Withdraw"** on any asset in this screen will prompt you to setup a withdrawal address. Follow the instructions in the modal to finish your setup and withdraw your recovered assets. ### Accept the transaction After entering a valid address, accept the transaction that appears on your wallet provider. # My NFTs are stuck in the Harpie Vault, how do I recover them? A step-by-step guide on how to recover your NFTs and other tokens from the Harpie Vault. The Harpie Vault is where your NFTs end up if you've protected them through Harpie Advanced Security. > Not a user of Advanced Security? Check [Get Protected](/welcome-to-the-harpie-docs/help/getting-started/get-protected) to find out how to protect your NFTs and tokens from scams and private key attacks.

The Harpie Vault, securely storing my FaucetToken and a Turkeys Megaverse NFT

In order to withdraw your NFT, you must: 1. Have created a set a **withdrawal address** to withdraw your NFTs to. Check [Setting a withdrawal address](/welcome-to-the-harpie-docs/help/getting-started/get-protected/setting-a-withdrawal-address) if you have not done this already. 2. Be connected to Harpie **with your withdrawal address.** Not sure if you're connected to Harpie with your withdrawal address? Follow the steps below: > Consider that I protected my Turkeys Megaverse NFT on my trading wallet `0x32D4...db78`. I also set my withdrawal address to `0xabc...123` so that if my trading wallet ever were to get hacked, I could recover my NFT using wallet `0xabc...123`.\ > \ > One day, my Turkeys Megaverse NFT gets transfered to the Harpie Vault.\ > \ > First, I must go to my trading wallet's (`0x32D4...db78`) dashboard. The easiest way to do this is connecting to Harpie and clicking "Go to dashboard"\ > ![](/files/B3PygjsJc9IwzCzkLxDP)![](/files/Vxn3NVuwJwDpAaw4Cujk)\ > \ > Next, I should be automatically redirected to my dashboard. Click **Advanced Security.** Your NFT should popup in the vault at the top of the page. Hold on, you can't withdraw just yet. We will have to switch to our withdrawal wallet (`0xabc...123`).\ > ![](/files/sFsqbke0GJd931zvVzcO) > > \ > To switch to our withdrawal wallet, we'll have to open our wallet. We'll use MetaMask's browser extension as an example:\ > \ > 1\. Open your wallet provider and click the option to switch your wallet\ > ![](/files/VN18bZGDd7h747gCcnf6)\ > \ > 2\. Find your withdrawal wallet. Switch to it now.\ > ![](/files/wyfObm2Zz417M4naPJMh)\ > \ > 3\. You may not be connected to Harpie with your withdrawal wallet. Connect to Harpie with this wallet now. In MetaMask, you can do this by clicking the "globe" icon and clicking "Connect". Make sure you're on before doing this.\ > ![](/files/4eFrnsbT046LGprzJpaU)\ > \ > Finally, you should be able to withdraw your NFT. Click **Withdraw** and accept the transaction to move your NFT from the Harpie Vault into your withdrawal wallet.\ > ![](/files/hrYlNejYzy6pwah3BlXD) # My Vault is saying I only have 1 NFT recovered, but there should be more A step by step guide on manually recovering your NFT from Etherscan. Due to a myriad of factors, whether it be congestion of the Ethereum network or an issue with our third-party data providers, the Harpie Vault might only show 1 NFT recovered in the vault. Rest assured, all of your NFTs are safely in the vault. Read on for a step-by-step guide on how to recover your NFTs using Etherscan.

There should be more than 1 NFT in my vault, what gives?

### Why Etherscan? is the #1 block explorer and analytics platform for Ethereum. It's an extremely powerful tool to search wallet addresses, check past transactions, and view detailed breakdowns of the Ethereum blockchain. Etherscan is also useful because it allows you to directly interact with smart contracts as if you were on a Web3 app's website. Today, we're going to be using this feature to withdraw your NFTs directly from the Harpie Vault smart contract. ### Before we start You'll need 3 pieces of information before we withdraw your NFTs: 1. The address of the wallet that was holding the NFTs before it was sent to the Harpie Vault (this is your `_originalAddress`, more on that later) 2. The contract address of your NFT 3. The IDs of your NFTs in the vault (this is the "420" in an NFT like "PudgyPenguins#420") If you're not sure about your NFTs contract address or NFT IDs, search for your wallet on and click "NFT Transfers". Look for outgoing transfers to **Harpie: Vault**.

In this example, your NFT IDs are 2740 and 7756. Clicking on Stoner Cats will give you the NFTs contract address.

### Withdrawing your NFTs Now that we have all of the necessary information, let's withdraw your NFTs using Etherscan's smart contract tool. 1. Go to the **Harpie: Vault** smart contract page on Etherscan (). This is where you will be able to interact with the Harpie Vault. Make sure the nametag says Harpie: Vault.

Look for the Harpie: Vault nametag and Source Code tag.

2. Click the "Connect to Web3" button and connect using your **Withdrawal Address**, NOT the wallet that originally owned the NFT. Not sure what your withdrawal address is? Read [Setting a withdrawal address](/welcome-to-the-harpie-docs/help/getting-started/get-protected/setting-a-withdrawal-address).
3. Scroll down to `withdrawERC721` and fill out the fields with this information:
fieldvaluevalue
payableAmount(ether)
00
_originalAddress
The address of the wallet that originally held the NFTs before they were transferred outThe address of your wallet that originally had the NFTs before it was transferred out
_erc721Address
The contract address of your NFTThe smart contract address of the NFT
_id
The ID of the NFT you'd like to withdraw

NOTE: You must enter ONE ID at a time!

The ID of the NFT you'd like to withdraw

NOTE: You must enter ONE ID at a time!

Scroll down to "12: withdrawERC721"

4. Now that you've filled out the fields, click the blue **Write** button. You will get a prompt to accept a transaction in your wallet. After approving it, you should see your NFT in your wallet within 60 seconds.

An example of what this form may look like after you completely fill it out.

5. Repeat this process for every NFT ID you'd like to withdraw. # FAQ # Is Harpie audited? Yes! Harpie's contracts have been audited by the awesome team over at [Sherlock](https://app.sherlock.xyz/), with more on the way. You can read our audits here: [Audit](/welcome-to-the-harpie-docs/tech-and-security/contracts/audit) # What is Harpie? Crypto shouldn't feel scary to use, but people lose crypto every day. No one in the space—from yield farmers, to NFT whales, to everyday hobbyists—is protected from scams, thefts and hacks. Theft is becoming rampant in the crypto space. Crypto users deal with attacks like [website hijackings](https://rekt.news/curve-finance-rekt/), [social engineering scams](https://twitter.com/BoredApeYC/status/1518637579633053701), and [social media misinformation](https://www.cnbc.com/2021/07/21/man-busted-for-twitter-hack-of-biden-obama-musk-in-bitcoin-scam.html) on an almost-daily basis. Harpie is the first service that protects you from crypto theft. If you're ever caught sending tokens to an unauthorized party, we stop that transfer in transit. We protect you from a huge variety of attack vectors: social engineering, website hacks, accidental transfers, and private key theft, to name a few. On top of that, Harpie is completely non-custodial. This means that at no point does Harpie nor its members have access to your funds. There is no risk of Harpie ever taking control of your wallet or assets. Harpie's smart contracts have been thoroughly audited. # What is a Trusted Network? To get started with Harpie you must create a "trusted network" of apps and friends. You will only be able to send tokens to and approve addresses within this trusted network: any of those transactions outside your network, we'll frontrun the transaction so that it will not execute. ### Your trusted network is a set of addresses you're comfortable sending assets to You're able to freely send assets to and approve the contracts of anyone inside your trusted network. We won't allow your wallet to approve or transfer assets to anyone outside this network. It's important that your trusted network consists only of contracts and individuals that you trust completely. ### We provide presets so you don't have to worry about who to trust We provide preset lists of the most popular and trusted protocols. You likely won't need to do much more than select a few presets to create your desired trusted network. ### You're able to add custom addresses to your trusted network, but proceed with caution! Our presets are quite large, but there might be a new DeFi protocol that you want to use, or a friend you'd like to send some USDC to. We allow you to freely add and remove custom addresses. Be careful adding an address into your trusted network. As a general rule, *addresses not in our preset apps list is a potential attack vector*. There's a few questions we ask you to answer before adding a new dApp or friend to your trusted network: > Ask these questions before adding an address to your trusted network: > > 1. Am I 100% sure that this address is *actually* the address of the service I'm trying to use? > 2. Am I 100% sure that this address hasn't been mentioned on a social media website as a scam? > 3. Am I 100% sure that this address belongs to an entity I trust? > 4. If there's a person pushing you to add this address to your trusted network, are you 100% sure about the trustworthiness of this person? Are you 100% sure that this person is who they say they are? The above are tough questions. Overall, we do not recommend that you add custom addresses to your trusted network. If you are ever unsure about the legitimacy of an address, please feel free to ask a question in Discord or open a ticket so that one of our security specialists can investigate the issue. ### **What next?** Be sure to check [**Getting Started**](/welcome-to-the-harpie-docs/help/getting-started) for guides and walkthroughs on everything you need to start using Harpie. # What happens when I "Protect" something? In order to have Harpie keep watch over your wallet, you have to "protect" each of your tokens. ### Protecting an asset allows us to move it in the event of an attack Your trusted network tells Harpie what traffic we should be watching for on your wallet. However, what your trusted network *does not do* is allow us to actually intervene in the event of an attack. By protecting your assets, you give Harpie permission to move your tokens and NFTs to a safe location the second we detect malicious activity on your wallet. This is done through the `approve` function. If you've used a DeFi protocol or an NFT marketplace like OpenSea or Compound, you've most likely used the `approve` function before. ### What exactly happens during an attack? When a thief sends a transaction to steal your money, Harpie eliminates that transaction before it can affect your balance. We essentially "skip the line" and transfer your assets out of your wallet before a thief can. Our systems use an advanced strategy called [frontrunning](https://consensys.github.io/smart-contract-best-practices/attacks/frontrunning/). By paying a higher gas fee, Harpie can beat out attackers by taking advantage of a blockchain's consensus mechanism. ### But wait... How can I trust Harpie? You may be asking yourself: > *How can I trust Harpie with the ability to move my tokens? Isn't it a security risk?* `Approval` is a huge security risk, and thus, we have done as much as we can to ensure that you feel comfortable with taking the risk. When Harpie moves your tokens on your behalf, we are only able to move it to the [Noncustodial Vault](/welcome-to-the-harpie-docs/tech-and-security/contracts/noncustodial-vault). When your tokens are inside the Vault, no one else (not even Harpie) can withdraw your stored tokens. This is guaranteed by code, and this code is completely transparent and has multiple public audits that you can find at [Audit](/welcome-to-the-harpie-docs/tech-and-security/contracts/audit). This means that, even though we have the power to move your tokens to the Vault on your behalf, we never have the power to access or withdraw them. # What is a Withdrawal Address? In order to withdraw your funds after our frontrunner intervenes, you must set a withdrawal address. This withdrawal address has the ability to retrieve the funds that are being held in the vault. ### A withdrawal address is the only address able to cash-out recovered assets from the vault If we successfully prevent an attack, we move your protected assets to our [Noncustodial Vault](/welcome-to-the-harpie-docs/tech-and-security/contracts/noncustodial-vault). The withdrawal address is the only address able to withdraw your assets from the Vault. When your tokens are inside the Vault, no one else (not even Harpie) can withdraw your stored tokens. ### What address should I use? As a rule of thumb: **use a withdrawal address that is different from your connected wallet.** Your withdrawal address can be any wallet you own, but we suggest that you create a new wallet, write down the private key or seed phrase of that wallet, and store it in a safe place. You can change your withdrawal address any time, and you can even change it after your funds are sent to the Vault. ### Why a different address? The withdrawal address is an important feature designed to keep you and your assets secure. `Approve` is a standard function built into almost all tokens and NFTs. It allows anyone to withdraw the approved asset at any time. Harpie looks out for `approve` transactions and moves your protected assets out of your wallet any time that an `approval` originates outside of your trusted network. That said, the `approval` will still go through, since `approval`s can happen without needing a balance in the wallet. Moving your assets back into your compromised wallet will allow a thief to regain access to them. A withdrawal address with a different address gives you the power to move your tokens to a fresh and safe wallet if your original wallet gets compromised, minimizing your risk when recovering assets from the vault. # Harpie For Enterprise Products * Harpie's [Background Check API](/welcome-to-the-harpie-docs/harpie-for-enterprise/harpie-for-enterprise/background-check-api) returns security analyses of transactions and addresses, along with security recommendations based on the data provided. # Background Check API ### Introduction Harpie's Background Check API screens any Ethereum address, letting you know if it's been involved in hacking, phishing, and other cybercrime. Our results are human-readable and actionable, giving you and your users peace-of-mind while using the blockchain. Additionally, our background checks let you know if a contract is associated with a protocol: we have a database of over 800,000 smart contracts, along with their deployer and contract name (ex. `Curvefi: 3pool`).

An example background check

### How it works We've developed a big-data engine with help from some of Ethereum's most famous data engineers. Using on-chain data, police reports, and other data, we've indexed over 1.8 million malicious addresses and 800,000 verified smart contracts. ### Getting Started To find your API key, log in to to your dashboard at . You can try out some of our API methods using a rate limited API key (10 requests/minute): Test Key: 74778fa4-88a8-4e35-922a-02bd82005edd ### Main Methods
Validate AddressGet a background check on any address: see if it's involved in theft or associated with a protocol./pages/JliNw0T7k0zDsc3Lrltb
Validate TransactionSee if a transaction will end up sending assets to a malicious address./pages/f1lgMfhGo1oaOMn8UF0r
### Other Methods
Get Contract NameLook up a contract's name./pages/aH3ShZcpgEp7A9CcgHXU
# Methods # Validate Address This method runs a background check on any Ethereum address, returning a human-readable analysis. ## validateAddress `POST` `https://api.harpie.io/v2/validateAddress` Get insights on the safety of an address. Addresses with no relevant data default to a recommended action of "ALLOW." #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | -------------------------------------------------- | | address\* | String | The address you want to query. | | apiKey\* | String | Your API key. You can find this in your dashboard. | {% tabs %} {% tab title="200: OK A summary on address security" %} ```typescript { name: string, // The name of the address. // Returns contract name if the address is associated with protocol isMaliciousAddress: boolean, isAssociatedWithProtocol: boolean, tags: { THEFT: boolean, CYBERCRIME: boolean, SANCTIONED: boolean, MIXER: boolean, BOT: boolean, WASH_TRADER: boolean, NO_DATA: boolean, }, summary: string, } ``` {% endtab %} {% endtabs %} #### Testing You can test this query on a visual interface at . **Example query:** ```typescript fetch("https://api.harpie.io/v2/validateAddress", { method: "POST", headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: JSON.stringify({ apiKey: "{YOUR API KEY HERE}", address: "0x55456cbd1f11298b80a53c896f4b1dc9bc16c731" }) }) ``` #### Example response: ```json { "summary": "This is a known malicious address. We recommend blocking any transactions sent there.", "name": "Malicious Address", "isMaliciousAddress": true, "isAssociatedWithProtocol": false, "tags": { "THEFT": true, "CYBERCRIME": false, "NO_DATA": false, "SANCTIONED": false, "MIXER": false, "BOT": false, "WASH_TRADER": false } } ``` # Validate Transaction This method analyzes a transaction, checking to see if it will end up sending assets to a malicious address. ## validateTransaction `POST` `https://api.harpie.io/v2/validateTransaction` Get insights on the safety of a transaction. Addresses with no relevant data default to a recommended action of "ALLOW." #### Request Body | Name | Type | Description | | ---------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | apiKey\* | String | Your API key. You can find this in your dashboard. | | from\* | String |

The address that the transaction is originating from.
This is the .from parameter of an Ethereum transaction.

| | to\* | String |

The address that the transaction is being sent to.

This is the .to parameter of an Ethereum transaction.

| | data\* | String |

The data being passed along with the transaction.

This is the .data parameter of an Ethereum transaction. If no data exists, use "0x" by default.

| | value\* | Number |

The value being sent along with the transaction.

This is the .value parameter of an Ethereum transaction

| {% tabs %} {% tab title="200: OK A summary on transaction security" %} ```typescript { summary: string, isDangerousOperation: boolean, // Returns `true` if the operation is a transfer or approval recommendedAction: "ALLOW" | "BLOCK", addressDetails: { name: string, isMaliciousAddress: boolean, isAssociatedWithProtocol: boolean, tags: { THEFT: boolean, CYBERCRIME: boolean, SANCTIONED: boolean, BOT: boolean, WASH_TRADER: boolean, MIXER: boolean, NO_DATA: boolean, } } } ``` {% endtab %} {% endtabs %} **Example query:** ```typescript fetch("https://api.harpie.io/v2/validateTransaction", { method: "POST", headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: JSON.stringify({ apiKey: "{YOUR API KEY HERE}", to: "0xEea6cEDf9c8a4bD197Ced6F11B254138B388a5f5", value: 0, from: "0x84F3Cfa1Ecbf333A3e91C0DAF7415ea0F1bcB701", data: "0xa9059cbb00000000000000000000000055456cbd1f11298b80a53c896f4b1dc9bc16c731000000000000000000000000000000000000000000000000000de0b6b3a7640000" }) }) ``` #### Example response: {% code overflow="wrap" %} ```json { "summary": "This transaction calls a token approval, which sends assets to a known malicious address. We recommend BLOCKING this transaction.", "isDangerousOperation": true, "recommendedAction": "BLOCK", "addressDetails": { "name": "Malicious Address", "isMaliciousAddress": true, "isAssociatedWithProtocol": false, "tags": { "THEFT": true, "CYBERCRIME": false, "NO_DATA": false, "SANCTIONED": false, "MIXER": false, "BOT": false, "WASH_TRADER": false } } } ``` {% endcode %} # Get Contract Name This API call returns the name of a contract if that contract exists within Harpie's database. ## getContractName `POST` `https://api.harpie.io/v2/getContractName` Get insight into who owns a specific contract. Returns "NO\_DATA" if the contract is not a known contract in Harpie's database. #### Request Body | Name | Type | Description | | ---------------------------------------- | ------ | -------------------------------------------------- | | apiKey\* | String | Your API key. You can find this in your dashboard. | | address | String | The address that is being analyzed | {% tabs %} {% tab title="200: OK A description of the protocol the contract is associated with." %} ```typescript { contractOwner: String // Returns protocol name or "NO_DATA" } ``` {% endtab %} {% endtabs %} **Example Requests** ```typescript fetch("https://api.harpie.io/v2/getcontractname", { method: "POST", headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: JSON.stringify({ apiKey: "{YOUR API KEY HERE}", address: "0x6c3f90f043a72fa612cbac8115ee7e52bde6e490" }) }) ``` #### Example Responses ```typescript { contractOwner: "Curvefi: threepool" } ```