Skip to content
Documentation
Tutorials
2. Wallet Management

2. Wallet Management

This tutorial covers creating and managing blockchain wallets in the Middleware API. Wallets are required for all blockchain operations including resource registration, access control, and marketplace transactions.

Overview

A wallet is an encrypted container for your blockchain private key. Each wallet has:

  • Address: Your blockchain identity (e.g., 0x1234...)
  • Private Key: Secret key for signing transactions (encrypted)
  • Password: Used to decrypt and use the private key

Why Wallets?

Wallets enable you to:

  • Register resources on the blockchain (hardware, datasets, AI models)
  • Grant and revoke access permissions
  • Execute benchmark tasks
  • Trade on the marketplace
  • Manage roles and identities

Prerequisites

Step 1: Create Your First Wallet

Endpoint 

POST /api/v1/wallet

Request 

curl -X POST https://middleware-daiedge.bisite.usal.es/api/v1/wallet \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "name": "My Primary Wallet",
    "password": "SecureWalletPass123!"
  }'

Request Body

FieldTypeRequiredDescription
namestringYesWallet name (max 80 characters)
passwordstringYesWallet password (min 8 characters)
private_keystringNoExisting private key (64 hex chars)

Response (200 OK) 

{
  "id": "0000019a95f732ce0adb8f69ccc7d362",
  "name": "My Primary Wallet",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7"
}
FieldDescription
idWallet identifier for API operations
nameWallet display name
addressEthereum address (your blockchain identity)

Important Notes

  • If you don’t provide private_key, a new one is generated automatically
  • Save your wallet password - it cannot be recovered
  • The address becomes your blockchain identity (DID)
  • You can create up to 10 wallets per account

Step 2: Import Existing Wallet (Optional)

If you have an existing private key, you can import it.

Request with Private Key 

curl -X POST https://middleware-daiedge.bisite.usal.es/api/v1/wallet \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "name": "Imported Wallet",
    "password": "NewSecurePass456!",
    "private_key": "3c4f8b9e2a1d5f7c6e8b4a9d2f1c5e7b3a6d8f2e4c7b9a1d3f5e8c2b4a7d9f6e1"
  }'

Private Key Format

  • Length: Exactly 64 hexadecimal characters
  • Format: Lowercase hex string (a-f, 0-9)
  • No prefix: Do not include 0x prefix

Validation

The API validates:

  • Private key is 32 bytes (64 hex chars)
  • Password is at least 8 characters
  • Wallet name is under 80 characters
  • User hasn’t exceeded 10 wallet limit

Step 3: List Your Wallets

View all wallets associated with your account.

Endpoint 

GET /api/v1/wallet

Request 

curl -X GET https://middleware-daiedge.bisite.usal.es/api/v1/wallet \
  -H "x-session-id: {SESSION_ID}"

Response (200 OK) 

[
  {
    "id": "0000019a95f732ce0adb8f69ccc7d362",
    "name": "My Primary Wallet",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7"
  },
  {
    "id": "0000019a96d8e4b1fa2c7d9e8b3a5f62",
    "name": "Imported Wallet",
    "address": "0x8Ba1f109551bD432803012645Ac136ddd64DBA72"
  }
]

Step 4: Get Wallet Details

Retrieve information about a specific wallet.

Endpoint 

GET /api/v1/wallet/{id}

Request 

curl -X GET https://middleware-daiedge.bisite.usal.es/api/v1/wallet/0000019a95f732ce0adb8f69ccc7d362 \
  -H "x-session-id: {SESSION_ID}"

Response (200 OK) 

{
  "id": "0000019a95f732ce0adb8f69ccc7d362",
  "name": "My Primary Wallet",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7"
}

Error Responses

CodeErrorCause
404WALLET_NOT_FOUNDWallet doesn’t exist or doesn’t belong to you

Step 5: Rename Wallet

Update the display name of a wallet.

Endpoint 

POST /api/v1/wallet/{id}

Request 

curl -X POST https://middleware-daiedge.bisite.usal.es/api/v1/wallet/0000019a95f732ce0adb8f69ccc7d362 \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "name": "Updated Wallet Name"
  }'

Request Body

FieldTypeRequiredDescription
namestringYesNew wallet name (max 80 characters)

Response (200 OK) 

{
  "id": "0000019a95f732ce0adb8f69ccc7d362",
  "name": "Updated Wallet Name",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7"
}

Step 6: Change Wallet Password

Update the password protecting your wallet.

Endpoint 

POST /api/v1/wallet/{id}/password

Request 

curl -X POST https://middleware-daiedge.bisite.usal.es/api/v1/wallet/0000019a95f732ce0adb8f69ccc7d362/password \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "password": "SecureWalletPass123!",
    "new_password": "EvenMoreSecure789!"
  }'

Request Body

FieldTypeRequiredDescription
passwordstringYesCurrent wallet password
new_passwordstringYesNew password (min 8 characters)

Response (200 OK) 

{}

Success returns an empty response.

Error Responses

CodeErrorCause
404WALLET_NOT_FOUNDWallet doesn’t exist
400WRONG_PASSWORDCurrent password incorrect
400WEAK_PASSWORDNew password too short (< 8 chars)

Step 7: Export Private Key

Export your wallet’s private key for backup or import into other tools.

Endpoint 

POST /api/v1/wallet/{id}/export

Request 

curl -X POST https://middleware-daiedge.bisite.usal.es/api/v1/wallet/0000019a95f732ce0adb8f69ccc7d362/export \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "password": "SecureWalletPass123!"
  }'

Request Body

FieldTypeRequiredDescription
passwordstringYesWallet password to decrypt private key

Response (200 OK) 

{
  "private_key": "3c4f8b9e2a1d5f7c6e8b4a9d2f1c5e7b3a6d8f2e4c7b9a1d3f5e8c2b4a7d9f6e1"
}

Step 8: Delete Wallet

Permanently remove a wallet from your account.

Endpoint 

DELETE /api/v1/wallet/{id}

Request 

curl -X DELETE https://middleware-daiedge.bisite.usal.es/api/v1/wallet/0000019a96d8e4b1fa2c7d9e8b3a5f62 \
  -H "x-session-id: {SESSION_ID}"

Response (200 OK) 

{}

Critical Warning

Deleting a wallet is permanent!

Before deleting:

  • Export your private key if you want to recover it later
  • Verify you don’t have blockchain assets tied to this address
  • Confirm no resources are registered with this identity

You cannot recover a deleted wallet without the private key.

Note: Deleting a wallet only removes it from your Middleware account. The blockchain identity (DID) associated with the wallet’s address continues to exist on the blockchain, along with any registered resources, credentials, or transactions. To manage those on-chain resources, you would need to reimport the wallet using its private key.

Using Wallets in Blockchain Operations

Most blockchain operations require wallet credentials:

# Example: Registering hardware (see Hardware Registration tutorial)
curl -X POST https://middleware-daiedge.bisite.usal.es/api/v1/hardware \
  -H "Content-Type: application/json" \
  -H "x-session-id: $SESSION_ID" \
  -d '{
    "walletId": "0000019a95f732ce0adb8f69ccc7d362",
    "password": "SecureWalletPass123!",
    "did": "did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
    "is_implemented": true,
    "description": "Raspberry Pi 4B with 4GB RAM",
    "family": "rpi4b",
    "hardware_spec": {
        "cost": {
            "value": 0.02,
            "currency": "EUR",
            "unit": "hour"
        },
        "cpus":[
            {
                "id" : "cpu_001",
                "arch": "arm64",
                "model": "cortex-a72",
                "specs": {
                    "rate": { "value": 1500, "unit": "MHz", "kind": "frequency"},
                    "cores": { "value": 4, "unit": "cores"},
                    "computing_power": { "value": 2.0, "unit": "GFLOPS" }
                }
            }
        ],
        "accelerators": [
            {
                "id" : "accel_001",
                "type": "gpu",
                "model": "broadcom-videocore",
                "specs": {
                    "rate": { "value": 500, "unit": "MHz", "kind": "frequency" },
                    "cores": { "value": 1, "unit": "core" },
                    "computing_power": { "value": 12.0, "unit": "GFLOPS"}
                }
            }
        ],
        "memory": {
            "type": "LPDDR4",
            "kind": "UNIFIED",
            "specs": {
                "size": { "value": 4096, "unit": "MB" },
                "rate": { "value": 3200, "unit": "MHz", "kind": "frequency" }
            }
        },
        "storage": {
            "type": "SD",
            "specs": {
                "size": { "value": 32, "unit": "GB" },
                "rate": { "value": 90, "unit": "MB/s", "kind": "read_speed" }
            }
        },
        "power":{
            "min": { "value": 7.0, "unit": "W" },
            "max": { "value": 15.0, "unit": "W"}
        }
    },
    "software_spec": {
        "OS": "Raspberry Pi OS",
        "version": "11 (Bullseye)",
        "engines":[
            {
                "id": "ort_001",
                "name": "Onnx Runtime",
                "family": "ort",
                "version": "1.14.1",
                "computing_backends": [
                    "cpu_001",
                    "accel_001"
                ],
                "supported_applications": [
                    {
                        "type": "BENCHMARKING",
                        "details":{
                            "supported_types": [
                                "TYPE1",
                                "TYPE2",
                                "TYPE3"
                            ]
                        }
                    }
                ]
            },
            {
                "id": "tf_002",
                "name": "TensorFlow Lite",
                "family": "tflite",
                "version": "2.7.0",
                "computing_backends": [
                    "cpu_001"
                ],
                "supported_applications": [
                    {
                        "type": "BENCHMARKING",
                        "details":{
                            "supported_types": [
                                "TYPE1",
                                "TYPE2"
                            ]
                        }
                    }
                ]
            }
        ]
    }
  }'

Standard Pattern

Most blockchain endpoints require:

  • walletId: Your wallet identifier
  • password: Wallet password to decrypt private key
  • did: Your DID (Decentralized Identifier) in format did:ethr:{network}:{address}

Important Note on DID Format: The API requires the full DID format including network identifier:

  • Correct: did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7
  • Incorrect: did:ethr:0x742d... (missing network)
  • Incorrect: 0x742d... (missing DID prefix)

The network identifier is typically development for development environments or your specific network name.

Next Steps

Now that you have a wallet, you can:

Related Topics

1. Authentication and Sessions3. Identity Management