> ## 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.

# Recuperacao de Ativos

> Recupere ativos enviados para o endereco correto na blockchain errada

<Note>
  Em resumo<br />
  A API de Recuperacao de Ativos da Yiksi Pay permite que voce recupere ativos que foram acidentalmente enviados para o endereco correto na blockchain errada. Ela suporta moeda nativa e ativos personalizados (ERC-20 e padroes compativeis) em todas as redes suportadas.
</Note>

## O que e Recuperacao de Ativos?

A recuperacao de ativos permite que voce recupere fundos que foram enviados para o endereco de carteira correto, mas na rede blockchain errada. Isso comumente acontece quando:

* Usuarios enviam ativos no Ethereum mas queriam enviar no Polygon
* Ativos sao enviados na BNB Smart Chain em vez do Arbitrum
* Qualquer confusao de enderecos entre cadeias onde o mesmo endereco existe em multiplas redes compativeis com EVM

<Info>
  Como blockchains compativeis com EVM compartilham o mesmo formato de endereco, o mesmo endereco pode receber ativos em multiplas redes. A recuperacao de ativos permite que voce acesse esses fundos programaticamente.
</Info>

## Pre-requisitos

Antes de usar a API de Recuperacao de Ativos, certifique-se de ter:

<Steps>
  <Step title="Chave API">
    Obtenha sua chave API no [Painel da Yiksi Pay](https://dashboard.yiksipay.com). Navegue ate **Configuracoes → Chaves API** para gerar uma.
  </Step>

  <Step title="Carteira Criada">
    Crie uma carteira atraves da [API Criar Carteira](/pt/api-reference/wallets/create-wallet) ou do painel. Voce precisara do `walletId` para operacoes de recuperacao.
  </Step>

  <Step title="ID da Blockchain">
    Obtenha o `blockchainId` para a rede onde os ativos estao presos. Voce pode encontra-lo no painel ou atraves da [API Obter Blockchains](/pt/api-reference/miscellaneous/get-blockchains).
  </Step>

  <Step title="Saldo de Moeda Nativa">
    Certifique-se de que o endereco remetente tenha moeda nativa suficiente (ETH, BNB, MATIC, etc.) na blockchain de recuperacao para cobrir as taxas de gas.
  </Step>
</Steps>

## Como Funciona

A API de Recuperacao de Ativos transfere ativos de um endereco remetente (onde os ativos estao presos) para um endereco destinatario na mesma blockchain:

<CardGroup cols={2}>
  <Card title="Recuperacao de Moeda Nativa" icon="coins">
    Recupere moeda nativa como ETH, BNB, MATIC ou AVAX enviada para a rede errada.
  </Card>

  <Card title="Recuperacao de Ativos Personalizados" icon="file-contract">
    Recupere ativos ERC-20 e compativeis especificando o endereco do contrato.
  </Card>

  <Card title="Estimativa de Taxas" icon="calculator">
    Calcule as taxas de rede antes da execucao para garantir saldo suficiente.
  </Card>

  <Card title="Suporte a RPC Personalizado" icon="server">
    Recupere ativos em blockchains nao suportadas fornecendo seu proprio endpoint RPC.
  </Card>
</CardGroup>

## Blockchains Suportadas

A recuperacao de ativos esta disponivel em **todas as blockchains** suportadas pela Yiksi Pay, incluindo redes compativeis com EVM, Tron e Solana. Consulte [Integracoes](/pt/essentials/integrations) para a lista completa de redes suportadas e links de faucets.

<Note>
  Para redes EVM nao diretamente suportadas, voce pode fornecer uma URL RPC personalizada e opcionalmente habilitar o modo Layer 2 para redes baseadas em rollup.
</Note>

<Tip>
  Comece com testnets durante o desenvolvimento para evitar gastar fundos reais.
</Tip>

***

## Recuperar Ativos

Inicie uma operacao de recuperacao de ativos para transferir ativos presos para um endereco destinatario.

### Parametros da Requisicao

| Parametro          | Tipo          | Obrigatorio | Descricao                                                                                                                                 |
| ------------------ | ------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `senderAddress`    | string        | Sim         | O endereco Yiksi Pay onde os ativos estao atualmente presos.                                                                              |
| `recipientAddress` | string        | Sim         | O endereco de destino para onde os ativos recuperados serao enviados.                                                                     |
| `amount`           | string        | Sim         | A quantidade a recuperar. Use a quantidade total ou uma porcao.                                                                           |
| `blockchainId`     | string (UUID) | Sim         | O UUID da blockchain onde a recuperacao ocorrera. Obtenha-o via [API Obter Blockchains](/pt/api-reference/miscellaneous/get-blockchains). |
| `tokenAddress`     | string        | Nao         | Endereco do contrato para recuperacao de ativos personalizados. Omita para moeda nativa.                                                  |
| `rpcUrl`           | string        | Nao         | Endpoint RPC personalizado para blockchains nao suportadas.                                                                               |
| `isL2`             | boolean       | Nao         | Defina como `true` se a URL RPC apontar para uma rede Layer 2.                                                                            |

### Recuperacao de Moeda Nativa

Recupere moeda nativa (ETH, BNB, MATIC, etc.) da rede errada:

<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: SUA_CHAVE_API' \
    --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': 'SUA_CHAVE_API'
      },
      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': 'SUA_CHAVE_API'
      },
      json={
          'senderAddress': '0x1234567890abcdef1234567890abcdef12345678',
          'recipientAddress': '0xabcdef1234567890abcdef1234567890abcdef12',
          'amount': '0.5',
          'blockchainId': 'polygon-mainnet'
      }
  )

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

### Recuperacao de Ativos Personalizados

Recupere ativos ERC-20 ou compativeis especificando o endereco do contrato:

<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: SUA_CHAVE_API' \
    --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': 'SUA_CHAVE_API'
      },
      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': 'SUA_CHAVE_API'
      },
      json={
          'senderAddress': '0x1234567890abcdef1234567890abcdef12345678',
          'recipientAddress': '0xabcdef1234567890abcdef1234567890abcdef12',
          'amount': '100',
          'blockchainId': 'polygon-mainnet',
          'tokenAddress': '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359'
      }
  )

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

### Recuperacao com RPC Personalizado

Recupere ativos em blockchains nao suportadas fornecendo seu proprio endpoint RPC:

<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: SUA_CHAVE_API' \
    --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': 'SUA_CHAVE_API'
      },
      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': 'SUA_CHAVE_API'
      },
      json={
          'senderAddress': '0x1234567890abcdef1234567890abcdef12345678',
          'recipientAddress': '0xabcdef1234567890abcdef1234567890abcdef12',
          'amount': '0.5',
          'blockchainId': 'custom',
          'rpcUrl': 'https://rpc.custom-network.io',
          'isL2': True
      }
  )

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

### Resposta de Sucesso

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

***

## Estimativa de Taxa de Rede

Antes de executar uma recuperacao, estime as taxas de rede para garantir saldo suficiente.

### Requisicao de Estimativa de Taxa

<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: SUA_CHAVE_API' \
    --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': 'SUA_CHAVE_API'
      },
      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': 'SUA_CHAVE_API'
      },
      json={
          'senderAddress': '0x1234567890abcdef1234567890abcdef12345678',
          'recipientAddress': '0xabcdef1234567890abcdef1234567890abcdef12',
          'amount': '0.5',
          'blockchainId': 'polygon-mainnet'
      }
  )

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

### Parametros de Resposta de Taxa

| Parametro            | Descricao                                        |
| -------------------- | ------------------------------------------------ |
| `networkFee`         | Taxa de gas estimada em unidades de moeda nativa |
| `networkFeeInUSD`    | Taxa de gas convertida para USD                  |
| `nativeBalance`      | Saldo atual de moeda nativa do remetente         |
| `nativeBalanceInUSD` | Saldo nativo convertido para USD                 |

<Warning>
  Sempre estime as taxas antes de executar operacoes de recuperacao. O endereco remetente deve ter moeda nativa suficiente para cobrir as taxas de gas na blockchain de recuperacao.
</Warning>

***

## Webhooks

Inscreva-se em eventos de webhook para receber notificacoes em tempo real sobre operacoes de recuperacao.

### Eventos de Recuperacao

| Evento              | Descricao                                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `salvage.success`   | Acionado quando uma operacao de recuperacao e concluida com sucesso.                                                |
| `salvage.failed`    | Acionado quando uma operacao de recuperacao falha devido a fundos insuficientes, problemas de rede ou outros erros. |
| `salvage.cancelled` | Acionado quando uma operacao de recuperacao e cancelada antes da conclusao.                                         |

### Payload do Webhook

```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 no [Painel da Yiksi Pay](https://dashboard.yiksipay.com/developers) em **Developers → Webhooks**. Consulte a [documentacao de Webhooks](/pt/essentials/webhooks) para instrucoes de configuracao.
</Note>

***

## Casos de Uso Comuns

<AccordionGroup>
  <Accordion title="Usuario enviou USDC na rede errada">
    Um usuario queria enviar USDC no Ethereum mas acidentalmente enviou no Polygon. Como o endereco e o mesmo, os fundos chegaram no Polygon. Use a recuperacao de ativos com o endereco do contrato USDC no Polygon para recuperar os fundos.
  </Accordion>

  <Accordion title="ETH enviado para Arbitrum em vez de Ethereum">
    Um usuario fez bridge de ETH para Arbitrum mas enviou para um endereco Yiksi Pay. O mesmo endereco existe no Arbitrum devido a compatibilidade EVM. Recupere o ETH do Arbitrum usando a recuperacao de moeda nativa.
  </Accordion>

  <Accordion title="Ativo personalizado em Layer 2">
    Um usuario enviou um ativo ERC-20 personalizado em uma rede L2 como Optimism. Forneca o endereco do contrato do ativo e use a API de recuperacao para recupera-lo.
  </Accordion>

  <Accordion title="Ativos em rede nao suportada">
    Ativos estao presos em uma blockchain nao suportada diretamente pela Yiksi Pay. Forneca seu proprio endpoint RPC e defina `isL2: true` se for um rollup para recuperar os fundos.
  </Accordion>
</AccordionGroup>

***

## Tratamento de Erros

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

    **Solucao:** Financie o endereco remetente com moeda nativa suficiente para cobrir as taxas de gas antes de tentar novamente.
  </Accordion>

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

    **Solucao:** Certifique-se de que o endereco remetente pertence a sua carteira Yiksi Pay e e um endereco filho valido.
  </Accordion>

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

    **Solucao:** Verifique o endereco do contrato e a blockchain. Use um explorador de blocos para confirmar que o ativo existe no endereco remetente.
  </Accordion>

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

    **Solucao:** Verifique se sua URL RPC esta correta e acessivel. Certifique-se de que ela suporta os metodos JSON-RPC necessarios.
  </Accordion>
</AccordionGroup>

***

## Melhores Praticas

<CardGroup cols={2}>
  <Card title="Sempre Estime Taxas Primeiro" icon="calculator">
    Use o endpoint de taxa de rede antes da recuperacao para garantir saldo de gas suficiente e exibir custos precisos.
  </Card>

  <Card title="Verifique Enderecos" icon="magnifying-glass">
    Verifique os enderecos remetente e destinatario usando um explorador de blocos antes de iniciar a recuperacao.
  </Card>

  <Card title="Use Webhooks" icon="bell">
    Configure webhooks para receber atualizacoes de status em tempo real em vez de consultar a API.
  </Card>

  <Card title="Teste na Testnet" icon="flask">
    Teste sua integracao de recuperacao na testnet antes de usa-la em producao.
  </Card>
</CardGroup>

***

## Referencia da API

| Endpoint                                                                    | Descricao                                 |
| --------------------------------------------------------------------------- | ----------------------------------------- |
| [Salvage](/pt/api-reference/asset-recovery/salvage)                         | Iniciar operacao de recuperacao de ativos |
| [Salvage Network Fee](/pt/api-reference/asset-recovery/salvage-network-fee) | Estimar taxas de rede para recuperacao    |

<br /> Boa recuperacao!