Recovering a wallet with APIs

Assumption that user is signed in with Wallaby. For more information about signing in, check out

Sequence Diagrams

Code Sample

Relevant APIs

Wallet Recovery - Step 1: Initiate wallet recovery

post

Authorizations

api-key-authjwt-access-token

Body

externalUserIdstringRequired

User reference UUID

Example: 6e464058-67c1-4273-a6a4-8aae522e34be

clientAuthPubKeystringRequiredExample: e3421d7f9d6888ea83bef6b28ce0a2ab6eb6fe8a8fbfa3743240992590816b08f9a62edcc63296d056c552054d583fec36d23ef11dffb24c95aaf4a47d50dccc

Responses

application/json

objectOptional

post

HTTPcURLJavaScriptPython

POST /api/v1/wallets/recover/init HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 207

{
  "externalUserId": "6e464058-67c1-4273-a6a4-8aae522e34be",
  "clientAuthPubKey": "e3421d7f9d6888ea83bef6b28ce0a2ab6eb6fe8a8fbfa3743240992590816b08f9a62edcc63296d056c552054d583fec36d23ef11dffb24c95aaf4a47d50dccc"
}

200Success

{
  "signatureMessage": "6e46405867c14273a6a48aae522e34be",
  "wallabyAuthPubKey": "4ecb720b1392468c75803d6252ac987c113206955070b96df1208c1c480338168e1407cec4b5af2f91d12af9b725cbd85af994b29c6364971a7ef8d955be83dc"
}

Wallet Recovery - Step 2 and final: Recover the lost wallet and its assets

post

Authorizations

api-key-authjwt-access-token

Body

externalUserIdstringRequired

User ID from the Republic

Example: 6e464058-67c1-4273-a6a4-8aae522e34be

clientAuthPubKeystringRequiredExample: e3421d7f9d6888ea83bef6b28ce0a2ab6eb6fe8a8fbfa3743240992590816b08f9a62edcc63296d056c552054d583fec36d23ef11dffb24c95aaf4a47d50dccc

messagestringRequired

Message retrieved from the backend

Example: 717ea458b62a430cb37ced7c22ebec97

signaturestringRequired

Signature generated after signing the provided data field

Example: 0xb44e88ff3c67de6e6548a6caf006bf6e1cb841119d0b9ea1b7e9b2d36a5e0ed42fd9f5e543243d1d73dc4b7800cc2026f74961f4edc769699678a316abb34e661c

encryptedSeedall ofRequired

Encrypted seed phrase with its corresponding wallabyAuthPubKey

Example: {"iv":"02aeac54cb45283b427bd1a5028552c1","ephemPublicKey":"044acf39ed83c304f19f41ea66615d7a6c0068d5fc48ee181f2fb1091...","ciphertext":"5fbbcc1a44ee19f7499dbc39cfc4ce96","mac":"96490b293763f49a371d3a2040a2d2cb57f246ee88958009fe3c7ef2a38264a1"}

Responses

application/json

objectOptional

post

HTTPcURLJavaScriptPython

POST /api/v1/wallets/recover HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 658

{
  "externalUserId": "6e464058-67c1-4273-a6a4-8aae522e34be",
  "clientAuthPubKey": "e3421d7f9d6888ea83bef6b28ce0a2ab6eb6fe8a8fbfa3743240992590816b08f9a62edcc63296d056c552054d583fec36d23ef11dffb24c95aaf4a47d50dccc",
  "message": "717ea458b62a430cb37ced7c22ebec97",
  "signature": "0xb44e88ff3c67de6e6548a6caf006bf6e1cb841119d0b9ea1b7e9b2d36a5e0ed42fd9f5e543243d1d73dc4b7800cc2026f74961f4edc769699678a316abb34e661c",
  "encryptedSeed": {
    "iv": "02aeac54cb45283b427bd1a5028552c1",
    "ephemPublicKey": "044acf39ed83c304f19f41ea66615d7a6c0068d5fc48ee181f2fb1091...",
    "ciphertext": "5fbbcc1a44ee19f7499dbc39cfc4ce96",
    "mac": "96490b293763f49a371d3a2040a2d2cb57f246ee88958009fe3c7ef2a38264a1"
  }
}

200

The wallet has been recovered successfully

{
  "user": {
    "userId": "a4dedb83-4d59-41ca-84b5-4b24a98878d8",
    "externalUserId": "de86cbd2-aef6-45b1-9f9e-f75013a13381"
  },
  "wallet": {
    "id": "text",
    "userId": "text",
    "merchantId": "text",
    "revisionId": "text",
    "revisionName": "text",
    "evmAddress": "text",
    "btcAddress": "text",
    "algoAddress": "text",
    "assetsCount": 1,
    "merchant": {
      "name": "Republic",
      "nameSlugify": "republic",
      "verified": true,
      "contactEmail": "[email protected]",
      "contactPhoneNumber": "text",
      "usersCount": 1,
      "assetsCount": 1,
      "tokensCount": 1,
      "coinsCount": 1,
      "walletsCount": 1,
      "status": "active",
      "createdAt": "2025-04-24T06:50:07.297Z",
      "updatedAt": "2025-04-24T06:50:07.297Z",
      "createdAssets": [
        []
      ]
    }
  }
}