> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yiksipay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Asset Recovery

> Recover assets sent to the correct address on the wrong blockchain

<Note>
  In a nutshell<br />
  The Yiksi Pay Asset Recovery API allows you to retrieve assets that were accidentally sent to the correct address on the wrong blockchain. It supports native currency and custom assets (ERC-20 and compatible standards) across all supported networks.
</Note>

## What is Asset Recovery?

Asset recovery enables you to retrieve funds that were sent to the correct wallet address but on the wrong blockchain network. This commonly happens when:

* Users send assets on Ethereum but meant to send on Polygon
* Assets are sent on BNB Smart Chain instead of Arbitrum
* Any cross-chain address confusion where the same address exists on multiple EVM-compatible networks

<Info>
  Since EVM-compatible blockchains share the same address format, the same address can receive assets on multiple networks. Asset recovery allows you to access these funds programmatically.
</Info>

## Prerequisites

Before using the Asset Recovery API, ensure you have:

<Steps>
  <Step title="API Key">
    Get your API key from the [Yiksi Pay Dashboard](https://dashboard.yiksipay.com). Navigate to **Developers** to generate one.
  </Step>

  <Step title="Wallet Created">
    Create a wallet via the [Create Wallet API](/en/api-reference/wallets/create-wallet) or dashboard. You'll need the `walletId` for recovery operations.
  </Step>

  <Step title="Blockchain ID">
    Get the `blockchainId` for the network where assets are stuck. You can find this in the dashboard or via the [Get Blockchains API](/en/api-reference/miscellaneous/get-blockchains).
  </Step>

  <Step title="Native Currency Balance">
    Ensure the sender address has enough native currency (ETH, BNB, MATIC, etc.) on the recovery blockchain to cover gas fees.
  </Step>
</Steps>

## How It Works

The Asset Recovery API transfers assets from a sender address (where assets are stuck) to a recipient address on the same blockchain:

<CardGroup cols={2}>
  <Card title="Native Currency Recovery" icon="coins">
    Recover native currency like ETH, BNB, MATIC, or AVAX sent to the wrong network.
  </Card>

  <Card title="Custom Asset Recovery" icon="file-contract">
    Recover ERC-20 and compatible assets by specifying the contract address.
  </Card>

  <Card title="Fee Estimation" icon="calculator">
    Calculate network fees before execution to ensure sufficient balance.
  </Card>

  <Card title="Custom RPC Support" icon="server">
    Recover assets on unsupported blockchains by providing your own RPC endpoint.
  </Card>
</CardGroup>

## Supported Blockchains

Asset recovery is available on **all blockchains** supported by Yiksi Pay, including EVM-compatible networks, Tron, and Solana. See [Integrations](/en/essentials/integrations) for the complete list of supported networks and faucet links.

<Note>
  For EVM networks not directly supported, you can provide a custom RPC URL and optionally enable Layer 2 mode for rollup-based networks.
</Note>

<Tip>
  Start with testnets during development to avoid spending real funds.
</Tip>

***

## Recover Assets

Initiate an asset recovery operation to transfer stuck assets to a recipient address.

### Request Parameters

| Parameter          | Type          | Required | Description                                                                                                                              |
| ------------------ | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `senderAddress`    | string        | Yes      | The Yiksi Pay address where assets are currently stuck.                                                                                  |
| `recipientAddress` | string        | Yes      | The destination address where recovered assets will be sent.                                                                             |
| `amount`           | string        | Yes      | The amount to recover. Use the full amount or a portion.                                                                                 |
| `blockchainId`     | string (UUID) | Yes      | The blockchain UUID where recovery will occur. Get this from the [Get Blockchains API](/en/api-reference/miscellaneous/get-blockchains). |
| `tokenAddress`     | string        | No       | Contract address for custom asset recovery. Omit for native currency.                                                                    |
| `rpcUrl`           | string        | No       | Custom RPC endpoint for unsupported blockchains.                                                                                         |
| `isL2`             | boolean       | No       | Set to `true` if the RPC URL points to a Layer 2 network.                                                                                |

### Native Currency Recovery

Recover native currency (ETH, BNB, MATIC, etc.) from the wrong network:

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.yiksipay.com/v1/wallets/{walletId}/salvage \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: YOUR_API_KEY' \
    --data '{
      "senderAddress": "0x1234567890abcdef1234567890abcdef12345678",
      "recipientAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
      "amount": "0.5",
      "blockchainId": "b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.yiksipay.com/v1/wallets/{walletId}/salvage',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
      },
      body: JSON.stringify({
        senderAddress: '0x1234567890abcdef1234567890abcdef12345678',
        recipientAddress: '0xabcdef1234567890abcdef1234567890abcdef12',
        amount: '0.5',
        blockchainId: 'b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa'
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.yiksipay.com/v1/wallets/{walletId}/salvage',
      headers={
          'Content-Type': 'application/json',
          'x-api-key': 'YOUR_API_KEY'
      },
      json={
          'senderAddress': '0x1234567890abcdef1234567890abcdef12345678',
          'recipientAddress': '0xabcdef1234567890abcdef1234567890abcdef12',
          'amount': '0.5',
          'blockchainId': 'polygon-mainnet'
      }
  )

  print(response.json())
  ```
</CodeGroup>

### Custom Asset Recovery

Recover ERC-20 or compatible assets by specifying the contract address:

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.yiksipay.com/v1/wallets/{walletId}/salvage \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: YOUR_API_KEY' \
    --data '{
      "senderAddress": "0x1234567890abcdef1234567890abcdef12345678",
      "recipientAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
      "amount": "100",
      "blockchainId": "b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa",
      "tokenAddress": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.yiksipay.com/v1/wallets/{walletId}/salvage',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
      },
      body: JSON.stringify({
        senderAddress: '0x1234567890abcdef1234567890abcdef12345678',
        recipientAddress: '0xabcdef1234567890abcdef1234567890abcdef12',
        amount: '100',
        blockchainId: 'b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa',
        tokenAddress: '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359'
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.yiksipay.com/v1/wallets/{walletId}/salvage',
      headers={
          'Content-Type': 'application/json',
          'x-api-key': 'YOUR_API_KEY'
      },
      json={
          'senderAddress': '0x1234567890abcdef1234567890abcdef12345678',
          'recipientAddress': '0xabcdef1234567890abcdef1234567890abcdef12',
          'amount': '100',
          'blockchainId': 'polygon-mainnet',
          'tokenAddress': '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359'
      }
  )

  print(response.json())
  ```
</CodeGroup>

### Custom RPC Recovery

Recover assets on unsupported blockchains by providing your own RPC endpoint:

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.yiksipay.com/v1/wallets/{walletId}/salvage \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: YOUR_API_KEY' \
    --data '{
      "senderAddress": "0x1234567890abcdef1234567890abcdef12345678",
      "recipientAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
      "amount": "0.5",
      "blockchainId": "b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa",
      "rpcUrl": "https://rpc.custom-network.io",
      "isL2": true
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.yiksipay.com/v1/wallets/{walletId}/salvage',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
      },
      body: JSON.stringify({
        senderAddress: '0x1234567890abcdef1234567890abcdef12345678',
        recipientAddress: '0xabcdef1234567890abcdef1234567890abcdef12',
        amount: '0.5',
        blockchainId: 'b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa',
        rpcUrl: 'https://rpc.custom-network.io',
        isL2: true
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.yiksipay.com/v1/wallets/{walletId}/salvage',
      headers={
          'Content-Type': 'application/json',
          'x-api-key': 'YOUR_API_KEY'
      },
      json={
          'senderAddress': '0x1234567890abcdef1234567890abcdef12345678',
          'recipientAddress': '0xabcdef1234567890abcdef1234567890abcdef12',
          'amount': '0.5',
          'blockchainId': 'custom',
          'rpcUrl': 'https://rpc.custom-network.io',
          'isL2': True
      }
  )

  print(response.json())
  ```
</CodeGroup>

### Success Response

```json theme={null}
{
  "message": "Salvage asset initiated successfully",
  "statusCode": 200
}
```

***

## Network Fee Estimation

Before executing a recovery, estimate the network fees to ensure sufficient balance.

### Fee Estimation Request

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.yiksipay.com/v1/wallets/{walletId}/salvage/network-fee \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: YOUR_API_KEY' \
    --data '{
      "senderAddress": "0x1234567890abcdef1234567890abcdef12345678",
      "recipientAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
      "amount": "0.5",
      "blockchainId": "b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.yiksipay.com/v1/wallets/{walletId}/salvage/network-fee',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
      },
      body: JSON.stringify({
        senderAddress: '0x1234567890abcdef1234567890abcdef12345678',
        recipientAddress: '0xabcdef1234567890abcdef1234567890abcdef12',
        amount: '0.5',
        blockchainId: 'b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa'
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.yiksipay.com/v1/wallets/{walletId}/salvage/network-fee',
      headers={
          'Content-Type': 'application/json',
          'x-api-key': 'YOUR_API_KEY'
      },
      json={
          'senderAddress': '0x1234567890abcdef1234567890abcdef12345678',
          'recipientAddress': '0xabcdef1234567890abcdef1234567890abcdef12',
          'amount': '0.5',
          'blockchainId': 'polygon-mainnet'
      }
  )

  print(response.json())
  ```
</CodeGroup>

### Fee Response Parameters

| Parameter            | Description                                |
| -------------------- | ------------------------------------------ |
| `networkFee`         | Estimated gas fee in native currency units |
| `networkFeeInUSD`    | Gas fee converted to USD                   |
| `nativeBalance`      | Current native currency balance of sender  |
| `nativeBalanceInUSD` | Native balance converted to USD            |

<Warning>
  Always estimate fees before executing recovery operations. The sender address must have sufficient native currency to cover gas fees on the recovery blockchain.
</Warning>

***

## Webhooks

Subscribe to webhook events to receive real-time notifications about recovery operations.

### Recovery Events

| Event               | Description                                                                                           |
| ------------------- | ----------------------------------------------------------------------------------------------------- |
| `salvage.success`   | Triggered when a recovery operation completes successfully.                                           |
| `salvage.failed`    | Triggered when a recovery operation fails due to insufficient funds, network issues, or other errors. |
| `salvage.cancelled` | Triggered when a recovery operation is cancelled before completion.                                   |

### Webhook Payload

```json theme={null}
{
  "event": "salvage.success",
  "data": {
    "id": "txn_abc123",
    "type": "SALVAGE",
    "status": "SUCCESS",
    "amount": "0.5",
    "senderAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "recipientAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
    "blockchain": "polygon-mainnet",
    "txHash": "0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba",
    "networkFee": "0.001",
    "createdAt": "2025-01-12T10:30:00Z"
  }
}
```

<Note>
  Configure webhooks in the [Yiksi Pay Dashboard](https://dashboard.yiksipay.com/developers) under **Developers → Webhooks**. See the [Webhooks documentation](/en/essentials/webhooks) for setup instructions.
</Note>

***

## Common Use Cases

<AccordionGroup>
  <Accordion title="User sent USDC on wrong network">
    A user meant to send USDC on Ethereum but accidentally sent it on Polygon. Since the address is the same, the funds arrived on Polygon. Use asset recovery with the USDC contract address on Polygon to retrieve the funds.
  </Accordion>

  <Accordion title="ETH sent to Arbitrum instead of Ethereum">
    A user bridged ETH to Arbitrum but sent it to a Yiksi Pay address. The same address exists on Arbitrum due to EVM compatibility. Recover the ETH from Arbitrum using native currency recovery.
  </Accordion>

  <Accordion title="Custom asset on Layer 2">
    A user sent a custom ERC-20 asset on an L2 network like Optimism. Provide the asset contract address and use the recovery API to retrieve it.
  </Accordion>

  <Accordion title="Assets on unsupported network">
    Assets are stuck on a blockchain not directly supported by Yiksi Pay. Provide your own RPC endpoint and set `isL2: true` if it's a rollup to recover the funds.
  </Accordion>
</AccordionGroup>

***

## Error Handling

<AccordionGroup>
  <Accordion title="Insufficient Native Balance">
    ```json theme={null}
    {
      "error": "Insufficient native balance for gas",
      "code": "INSUFFICIENT_GAS",
      "details": {
        "required": "0.01",
        "available": "0.001",
        "currency": "MATIC"
      }
    }
    ```

    **Solution:** Fund the sender address with enough native currency to cover gas fees before retrying.
  </Accordion>

  <Accordion title="Invalid Sender Address">
    ```json theme={null}
    {
      "error": "Sender address not found in wallet",
      "code": "INVALID_SENDER"
    }
    ```

    **Solution:** Ensure the sender address belongs to your Yiksi Pay wallet and is a valid child address.
  </Accordion>

  <Accordion title="Asset Not Found">
    ```json theme={null}
    {
      "error": "No balance found for specified asset",
      "code": "ASSET_NOT_FOUND",
      "details": {
        "tokenAddress": "0x...",
        "blockchain": "polygon-mainnet"
      }
    }
    ```

    **Solution:** Verify the contract address and blockchain. Use a block explorer to confirm the asset exists at the sender address.
  </Accordion>

  <Accordion title="RPC Connection Failed">
    ```json theme={null}
    {
      "error": "Failed to connect to custom RPC",
      "code": "RPC_ERROR"
    }
    ```

    **Solution:** Verify your RPC URL is correct and accessible. Ensure it supports the required JSON-RPC methods.
  </Accordion>
</AccordionGroup>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Always Estimate Fees First" icon="calculator">
    Use the network fee endpoint before recovery to ensure sufficient gas balance and display accurate costs.
  </Card>

  <Card title="Verify Addresses" icon="magnifying-glass">
    Double-check sender and recipient addresses using a block explorer before initiating recovery.
  </Card>

  <Card title="Use Webhooks" icon="bell">
    Configure webhooks to receive real-time status updates instead of polling the API.
  </Card>

  <Card title="Test on Testnet" icon="flask">
    Test your recovery integration on testnet before using it in production.
  </Card>
</CardGroup>

***

## API Reference

| Endpoint                                                                    | Description                        |
| --------------------------------------------------------------------------- | ---------------------------------- |
| [Salvage](/en/api-reference/asset-recovery/salvage)                         | Initiate asset recovery operation  |
| [Salvage Network Fee](/en/api-reference/asset-recovery/salvage-network-fee) | Estimate network fees for recovery |

<br /> Happy recovering!