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

# Storage Operations

The peaq network allows you to store on-chain data using a simple **`key: value`** structure.

## add\_item(item\_type, item)

Adds a new key-value pair to the on-chain storage. If the item is not already a string, it will be automatically JSON-serialized before storage.

| Parameter      | Type     | EVM      | Substrate | Description                                                                   |
| -------------- | -------- | -------- | --------- | ----------------------------------------------------------------------------- |
| **item\_type** | `string` | Required | Required  | Key used to categorize or identify the item. Max 64 bytes.                    |
| **item**       | `object` | Required | Required  | Value to store. Automatically JSON-serialized if not a string. Max 256 bytes. |

### Add Item Code Examples

<CodeGroup>
  ```python EVM Unsigned Tx theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  import os
  from dotenv import load_dotenv
  from peaq_sdk import Sdk
  from peaq_sdk.types import ChainType

  load_dotenv()

  HTTPS_PEAQ_URL = os.getenv("HTTPS_PEAQ_URL")

  sdk = Sdk.create_instance(
      base_url=HTTPS_PEAQ_URL,
      chain_type=ChainType.EVM
  )

  item_type='my_key'
  item='my_value'

  response = sdk.storage.add_item(item_type=item_type, item=item)
  ```

  ```python EVM Unsigned Tx Response theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  {
    "message": "Constructed add_item tx object for peaq storage with item type my_key and item my_value. You must sign and send it externally.",
    "tx": {
      "to": "0x0000000000000000000000000000000000000801",
      "data": "0x257c3c0300000000000000000..."
    }
  }
  ```

  ```python EVM Write Tx theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  import os
  from dotenv import load_dotenv
  from peaq_sdk import Sdk
  from peaq_sdk.types import ChainType

  load_dotenv()

  HTTPS_PEAQ_URL = os.getenv("HTTPS_PEAQ_URL")
  EVM_PRIVATE_KEY = os.getenv("EVM_PRIVATE_KEY")

  sdk = Sdk.create_instance(
      base_url=HTTPS_PEAQ_URL,
      chain_type=ChainType.EVM,
      seed=EVM_PRIVATE_KEY
  )

  item_type='my_key'
  item='my_value'

  response = sdk.storage.add_item(item_type=item_type, item=item)
  ```

  ```python EVM Write Response theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  {
    "message": "Successfully added the storage item type my_key with item my_value for the address 0x9Eeab1aCcb1A701aEfAB00F3b8a275a39646641C.",
    "receipt": {
      "transactionHash": "0x48e40a9e450c24f5d7abd055e368c1c8a80748737f4d7e8e1c29e38a160f0cea",
      "transactionIndex": 0,
      "blockHash": "0xa696c8c3620aa5cad713faa9745fb0b105d37c555e1365881bdf3ffabcd502d9",
      "from": "0x9Eeab1aCcb1A701aEfAB00F3b8a275a39646641C",
      "to": "0x0000000000000000000000000000000000000801",
      "blockNumber": 5846526,
      "cumulativeGasUsed": 43014,
      "gasUsed": 43014,
      "contractAddress": null,
      "logs": [
        {
          "address": "0x0000000000000000000000000000000000000801",
          "topics": [
            "0x6fbdb10fd11f8487a821a58c35e587dcc19748004073777f2a8d87bc5c25535e"
          ],
          "data": "0x0000000000000000000000009eeab1accb1a701aefab00f...",
          "blockHash": "0xa696c8c3620aa5cad713faa9745fb0b105d37c555e1365881bdf3ffabcd502d9",
          "blockNumber": 5846526,
          "transactionHash": "0x48e40a9e450c24f5d7abd055e368c1c8a80748737f4d7e8e1c29e38a160f0cea",
          "transactionIndex": 0,
          "logIndex": 0,
          "transactionLogIndex": "0x0",
          "removed": false
        }
      ],
      "logsBloom": "0x00000000000000000000000000000...",
      "status": 1,
      "effectiveGasPrice": 102000000000,
      "type": 2
    }
  }
  ```

  ```python Substrate Unsigned Call theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  import os
  from dotenv import load_dotenv
  from peaq_sdk import Sdk
  from peaq_sdk.types import ChainType

  load_dotenv()

  WSS_PEAQ_URL = os.getenv("WSS_PEAQ_URL")

  sdk = Sdk.create_instance(
      base_url=WSS_PEAQ_URL,
      chain_type=ChainType.SUBSTRATE
  )

  item_type='my_key'
  item='my_value'

  response = sdk.storage.add_item(item_type=item_type, item=item)
  ```

  ```python Substrate Unsigned Call Response theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  {
    "message": "Constructed add_item call object for peaq storage with item type my_key and item my_value. You must sign and send it externally.",
    "call": {
      "call_module": "PeaqStorage",
      "call_function": "add_item",
      "call_args": {
        "item_type": "my_key",
        "item": "my_value"
      }
    }
  }
  ```

  ```python Substrate Write Call theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  import os
  from dotenv import load_dotenv
  from peaq_sdk import Sdk
  from peaq_sdk.types import ChainType

  load_dotenv()

  WSS_PEAQ_URL = os.getenv("WSS_PEAQ_URL")
  SUBSTRATE_SEED = os.getenv("SUBSTRATE_SEED")

  sdk = Sdk.create_instance(
      base_url=WSS_PEAQ_URL,
      chain_type=ChainType.SUBSTRATE,
      seed=SUBSTRATE_SEED
  )

  item_type='my_key'
  item='my_value'

  response = sdk.storage.add_item(item_type=item_type, item=item)
  ```

  ```python Substrate Write Response theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  {
    "message": "Successfully added the storage item type my_key with item my_value for the address 5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg.",
    "receipt": {
      "extrinsic_hash": "0xc6f0a03731031b93b8da6fe45548f5373e4f36edbe0fad95934077e5eb1d504c",
      "block_hash": "0xf25b847bc9e8c2f4b36ef91c9ab8798a3aa2195c48fa1597f7a9156391620ac7",
      "finalized": false,
      "call": {
        "module": "PeaqStorage",
        "function": "add_item",
        "args": {
          "item_type": "my_key",
          "item": "my_value"
        }
      },
      "events": [...]
    }
  }
  ```
</CodeGroup>

## get\_item(item\_type, address)

Retrieves a stored item by its key for the specified address. Returns the decoded value as a string.

**Cross-chain storage querying:**

* **Substrate**: Uses the existing Substrate API connection directly to query storage
* **EVM**: Automatically uses the SDK's `base_url` to create a temporary Substrate connection.

| Parameter      | Type     | EVM        | Substrate  | Description                                      |
| -------------- | -------- | ---------- | ---------- | ------------------------------------------------ |
| **item\_type** | `string` | Required   | Required   | Key used to search for the stored item.          |
| **address**    | `string` | Required\* | Required\* | Address of the wallet that owns the stored item. |

\* The address is required when no seed is set.

### Get Item Code Examples

<CodeGroup>
  ```python EVM No Key Read theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  import os
  from dotenv import load_dotenv
  from peaq_sdk import Sdk
  from peaq_sdk.types import ChainType

  load_dotenv()

  HTTPS_PEAQ_URL = os.getenv("HTTPS_PEAQ_URL")
  EVM_ADDRESS = os.getenv("EVM_ADDRESS")

  sdk = Sdk.create_instance(
      base_url=HTTPS_PEAQ_URL,
      chain_type=ChainType.EVM
  )

  item_type='my_key'

  response = sdk.storage.get_item(item_type=item_type, address=EVM_ADDRESS)
  ```

  ```python EVM No Key Response theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  {'my_key': 'my_value'}
  ```

  ```python EVM Key Read theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  import os
  from dotenv import load_dotenv
  from peaq_sdk import Sdk
  from peaq_sdk.types import ChainType

  load_dotenv()

  HTTPS_PEAQ_URL = os.getenv("HTTPS_PEAQ_URL")
  EVM_PRIVATE_KEY = os.getenv("EVM_PRIVATE_KEY")

  sdk = Sdk.create_instance(
      base_url=HTTPS_PEAQ_URL,
      chain_type=ChainType.EVM,
      seed=EVM_PRIVATE_KEY
  )

  item_type='my_key'

  response = sdk.storage.get_item(item_type=item_type)
  ```

  ```python EVM Key Response theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  {'my_key': 'my_value'}
  ```

  ```python Substrate No Key Read theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  import os
  from dotenv import load_dotenv
  from peaq_sdk import Sdk
  from peaq_sdk.types import ChainType

  load_dotenv()

  WSS_PEAQ_URL = os.getenv("WSS_PEAQ_URL")
  SUBSTRATE_ADDRESS = os.getenv("SUBSTRATE_ADDRESS")

  sdk = Sdk.create_instance(
      base_url=WSS_PEAQ_URL,
      chain_type=ChainType.SUBSTRATE
  )

  item_type='my_key'

  response = sdk.storage.get_item(item_type=item_type, address=SUBSTRATE_ADDRESS)
  ```

  ```python Substrate No Key Response theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  {'my_key': 'my_value'}
  ```

  ```python Substrate Key Read theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  import os
  from dotenv import load_dotenv
  from peaq_sdk import Sdk
  from peaq_sdk.types import ChainType

  load_dotenv()

  WSS_PEAQ_URL = os.getenv("WSS_PEAQ_URL")
  SUBSTRATE_SEED = os.getenv("SUBSTRATE_SEED")

  sdk = Sdk.create_instance(
      base_url=WSS_PEAQ_URL,
      chain_type=ChainType.SUBSTRATE,
      seed=SUBSTRATE_SEED
  )

  item_type='my_key'

  response = sdk.storage.get_item(item_type=item_type)
  ```

  ```python Substrate Key Response theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  {'my_key': 'my_value'}
  ```
</CodeGroup>

## update\_item(item\_type, item)

Updates an existing item in on-chain storage by replacing its value with a new one. The item will be automatically JSON-serialized if it's not already a string.

| Parameter      | Type     | EVM      | Substrate | Description                                                        |
| -------------- | -------- | -------- | --------- | ------------------------------------------------------------------ |
| **item\_type** | `string` | Required | Required  | Key of the existing item to update.                                |
| **item**       | `object` | Required | Required  | New value to store. Automatically JSON-serialized if not a string. |

### Update Item Code Examples

<CodeGroup>
  ```python EVM Unsigned Tx theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  import os
  from dotenv import load_dotenv
  from peaq_sdk import Sdk
  from peaq_sdk.types import ChainType

  load_dotenv()

  HTTPS_PEAQ_URL = os.getenv("HTTPS_PEAQ_URL")

  sdk = Sdk.create_instance(
      base_url=HTTPS_PEAQ_URL,
      chain_type=ChainType.EVM
  )

  item_type='my_key'
  item='my_new_value'

  response = sdk.storage.update_item(item_type=item_type, item=item)
  ```

  ```python EVM Unsigned Tx Response theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  {
    "message": "Constructed update_item tx object for peaq storage with item type my_key and item my_new_value. You must sign and send it externally.",
    "tx": {
      "to": "0x0000000000000000000000000000000000000801",
      "data": "0x1cd4bf09000000000..."
    }
  }
  ```

  ```python EVM Write Tx theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  import os
  from dotenv import load_dotenv
  from peaq_sdk import Sdk
  from peaq_sdk.types import ChainType

  load_dotenv()

  HTTPS_PEAQ_URL = os.getenv("HTTPS_PEAQ_URL")
  EVM_PRIVATE_KEY = os.getenv("EVM_PRIVATE_KEY")

  sdk = Sdk.create_instance(
      base_url=HTTPS_PEAQ_URL,
      chain_type=ChainType.EVM,
      seed=EVM_PRIVATE_KEY
  )

  item_type='my_key'
  item='my_new_value'

  response = sdk.storage.update_item(item_type=item_type, item=item)
  ```

  ```python EVM Write Response theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  {
    "message": "Successfully updated the storage item type my_key with item my_new_value for the address 0x9Eeab1aCcb1A701aEfAB00F3b8a275a39646641C.",
    "receipt": {
      "transactionHash": "0xf477fa1b5255fd623b5a25757d42cd82ede5b287e20fe170d407d85f9a0ea412",
      "transactionIndex": 0,
      "blockHash": "0x33bd10eead5f94b2dd330625c93b17038b8a35c32dda5ef9f730bfd01bd39504",
      "from": "0x9Eeab1aCcb1A701aEfAB00F3b8a275a39646641C",
      "to": "0x0000000000000000000000000000000000000801",
      "blockNumber": 5846617,
      "cumulativeGasUsed": 32060,
      "gasUsed": 32060,
      "contractAddress": null,
      "logs": [
        {
          "address": "0x0000000000000000000000000000000000000801",
          "topics": [
            "0x73cf4bb2cd2563692444e276f8a1db29257d4f8caabbd3443cf369e461df95ba"
          ],
          "data": "0x0000000000000000000000009eeab1accb1a701aefab00f3b...",
          "blockHash": "0x33bd10eead5f94b2dd330625c93b17038b8a35c32dda5ef9f730bfd01bd39504",
          "blockNumber": 5846617,
          "transactionHash": "0xf477fa1b5255fd623b5a25757d42cd82ede5b287e20fe170d407d85f9a0ea412",
          "transactionIndex": 0,
          "logIndex": 0,
          "transactionLogIndex": "0x0",
          "removed": false
        }
      ],
      "logsBloom": "0x000000000000000000000000000000000000000000000000000...",
      "status": 1,
      "effectiveGasPrice": 102000000000,
      "type": 2
    }
  }

  ```

  ```python Substrate Unsigned Call theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  import os
  from dotenv import load_dotenv
  from peaq_sdk import Sdk
  from peaq_sdk.types import ChainType

  load_dotenv()

  WSS_PEAQ_URL = os.getenv("WSS_PEAQ_URL")

  sdk = Sdk.create_instance(
      base_url=WSS_PEAQ_URL,
      chain_type=ChainType.SUBSTRATE
  )

  item_type='my_key'
  item='my_new_value'

  response = sdk.storage.update_item(item_type=item_type, item=item)
  ```

  ```python Substrate Unsigned Call Response theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  {
    "message": "Constructed update_item call object for peaq storage with item type my_key and item my_new_value. You must sign and send it externally.",
    "call": {
      "call_module": "PeaqStorage",
      "call_function": "update_item",
      "call_args": {
        "item_type": "my_key",
        "item": "my_new_value"
      }
    }
  }
  ```

  ```python Substrate Write Call theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  import os
  from dotenv import load_dotenv
  from peaq_sdk import Sdk
  from peaq_sdk.types import ChainType

  load_dotenv()

  WSS_PEAQ_URL = os.getenv("WSS_PEAQ_URL")
  SUBSTRATE_SEED = os.getenv("SUBSTRATE_SEED")

  sdk = Sdk.create_instance(
      base_url=WSS_PEAQ_URL,
      chain_type=ChainType.SUBSTRATE,
      seed=SUBSTRATE_SEED
  )

  item_type='my_key'
  item='my_new_value'

  response = sdk.storage.update_item(item_type=item_type, item=item)
  ```

  ```python Substrate Write Response theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  {
    "message": "Successfully updated the storage item type my_key with item my_new_value for the address 5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg.",
    "receipt": {
      "extrinsic_hash": "0xd6a2930a6de697cc0c5d31b41fd53bd1e7e80aa95ac4f2feb59539a7ef02310c",
      "block_hash": "0x61394cf43727841ed98c5487a2c46101e7b432bd830dc76f7c40b5bd1dcc20c0",
      "finalized": false,
      "extrinsic_index": 2,
      "call": {
        "module": "PeaqStorage",
        "function": "update_item",
        "args": {
          "item_type": "my_key",
          "item": "my_new_value"
        }
      },
      "events": [...],
      "is_success": true,
      "total_fee": 1954699326844373
    }
  }
  ```
</CodeGroup>

## remove\_item(item\_type)

Removes an existing key-value pair from on-chain storage.

| Parameter      | Type     | EVM      | Substrate | Description                                  |
| -------------- | -------- | -------- | --------- | -------------------------------------------- |
| **item\_type** | `string` | Required | Required  | The key representing the pair to be removed. |

### Remove Item Code Examples

<CodeGroup>
  ```python EVM Unsigned Tx theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  import os
  from dotenv import load_dotenv
  from peaq_sdk import Sdk
  from peaq_sdk.types import ChainType

  load_dotenv()

  HTTPS_PEAQ_URL = os.getenv("HTTPS_PEAQ_URL")

  sdk = Sdk.create_instance(
      base_url=HTTPS_PEAQ_URL,
      chain_type=ChainType.EVM
  )

  item_type='my_key'

  response = sdk.storage.remove_item(item_type=item_type)
  ```

  ```python EVM Unsigned Tx Response theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  {
    "message": "Constructed remove_item tx object for peaq storage with item type my_key. You must sign and send it externally.",
    "tx": {
      "to": "0x0000000000000000000000000000000000000801",
      "data": "0x2c2decc1000000000000000000000000000000000..."
    }
  }
  ```

  ```python EVM Write Tx theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  import os
  from dotenv import load_dotenv
  from peaq_sdk import Sdk
  from peaq_sdk.types import ChainType

  load_dotenv()

  HTTPS_PEAQ_URL = os.getenv("HTTPS_PEAQ_URL")
  EVM_PRIVATE_KEY = os.getenv("EVM_PRIVATE_KEY")

  sdk = Sdk.create_instance(
      base_url=HTTPS_PEAQ_URL,
      chain_type=ChainType.EVM,
      seed=EVM_PRIVATE_KEY
  )

  item_type='my_key'

  response = sdk.storage.remove_item(item_type=item_type)
  ```

  ```python EVM Write Response theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  {
    "message": "Successfully removed the storage item type my_key for the address 0x9Eeab1aCcb1A701aEfAB00F3b8a275a39646641C.",
    "receipt": {
      "transactionHash": "0xe5c923db4b45567c6673bfc33e87ff24676bac44656e869c06aea507e49dace0",
      "transactionIndex": 0,
      "blockHash": "0x2abc1e8dad4ad39689a4a338a2d8a60ea71e541ddcec39872f27cedc8f221816",
      "from": "0x9Eeab1aCcb1A701aEfAB00F3b8a275a39646641C",
      "to": "0x0000000000000000000000000000000000000801",
      "blockNumber": 5846657,
      "cumulativeGasUsed": 42572,
      "gasUsed": 42572,
      "contractAddress": null,
      "logs": [
        {
          "address": "0x0000000000000000000000000000000000000801",
          "topics": [
            "0x9a7468a61900ddc322ec242b1778095d326b907aca7e792ae8a9b862903a0fa8"
          ],
          "data": "0x0000000000000000000000009eeab1accb1a701aefab00f3b8a275a39646641c00000000000000000000000000000000000...",
          "blockHash": "0x2abc1e8dad4ad39689a4a338a2d8a60ea71e541ddcec39872f27cedc8f221816",
          "blockNumber": 5846657,
          "transactionHash": "0xe5c923db4b45567c6673bfc33e87ff24676bac44656e869c06aea507e49dace0",
          "transactionIndex": 0,
          "logIndex": 0,
          "transactionLogIndex": "0x0",
          "removed": false
        }
      ],
      "logsBloom": "0x0000000000000000000000000000000000000000000000...",
      "status": 1,
      "effectiveGasPrice": 102000000000,
      "type": 2
    }
  }
  ```

  ```python Substrate Unsigned Call theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  import os
  from dotenv import load_dotenv
  from peaq_sdk import Sdk
  from peaq_sdk.types import ChainType

  load_dotenv()

  WSS_PEAQ_URL = os.getenv("WSS_PEAQ_URL")

  sdk = Sdk.create_instance(
      base_url=WSS_PEAQ_URL,
      chain_type=ChainType.SUBSTRATE
  )

  item_type='my_key'

  response = sdk.storage.remove_item(item_type=item_type)
  ```

  ```python Substrate Unsigned Call Response theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  {
    "message": "Constructed remove_item call object for peaq storage with item type my_key. You must sign and send it externally.",
    "call": {
      "call_module": "PeaqStorage",
      "call_function": "remove_item",
      "call_args": {
        "item_type": "my_key"
      }
    }
  }
  ```

  ```python Substrate Write Call theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  import os
  from dotenv import load_dotenv
  from peaq_sdk import Sdk
  from peaq_sdk.types import ChainType

  load_dotenv()

  WSS_PEAQ_URL = os.getenv("WSS_PEAQ_URL")
  SUBSTRATE_SEED = os.getenv("SUBSTRATE_SEED")

  sdk = Sdk.create_instance(
      base_url=WSS_PEAQ_URL,
      chain_type=ChainType.SUBSTRATE,
      seed=SUBSTRATE_SEED
  )

  item_type='my_key'

  response = sdk.storage.remove_item(item_type=item_type)
  ```

  ```python Substrate Write Response theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  {
    "message": "Successfully removed the storage item type my_key for the address 5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg.",
    "receipt": {
      "extrinsic_hash": "0x03dff995ad423247b1096c63fe0fdcc16940f2b6eba2b602ac43ae5153026680",
      "block_hash": "0x6140c316ca255d036cfb607bfb2707da6ae4e45bcb0bfd2e58745859194235c4",
      "finalized": false,
      "extrinsic_index": 2,
      "address": "5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg",
      "call": {
        "module": "PeaqStorage",
        "function": "remove_item",
        "args": {
          "item_type": "my_key"
        }
      },
      "events": [...],
      "success": true,
      "total_fee": "2342748778674540"
    }
  }

  ```
</CodeGroup>