Wallet Setup and Configuration

Connect and configure your Web3 wallet to interact with the AgrospAI Data Space Portal. This guide covers wallet setup, network configuration, and token management.

Supported Wallets

The portal supports multiple wallet providers through WalletConnect and direct integrations:

MetaMask: Browser extension and mobile app
WalletConnect: Compatible with 100+ wallets
Coinbase Wallet: Browser extension and mobile
Trust Wallet: Mobile application
Brave Wallet: Built into Brave browser

MetaMask is recommended for the best user experience and full feature support.

Initial Setup

Install Wallet Extension

MetaMask Installation

Visit metamask.io
Click “Download” for your browser
Add extension to browser
Follow setup wizard

Create New Wallet

Set a strong password
Save your Secret Recovery Phrase securely
Confirm recovery phrase
Complete setup

Never share your Secret Recovery Phrase. Store it offline in a secure location. Anyone with this phrase can access your funds.

Import Existing Wallet

Select “Import wallet”
Enter your Secret Recovery Phrase
Set password
Complete import

Connect to Portal

Connect your wallet to the AgrospAI portal:

Click “Connect Wallet” button in header
Select your wallet provider
Approve connection in wallet popup
Confirm account selection

// Wallet connection using Wagmi
import { useAccount, useConnect } from 'wagmi'

const { address, isConnected } = useAccount()
const { connect, connectors } = useConnect()

// Connect to wallet
connect({ connector: connectors[0] })

Connection Status

Green indicator: Connected and ready
Yellow indicator: Wrong network
Red indicator: Disconnected

Configure Networks

Add supported networks to your wallet:

Network Configuration

The portal supports multiple networks. Add them to MetaMask:Example: Polygon Network

{
  "chainId": "0x89",
  "chainName": "Polygon Mainnet",
  "nativeCurrency": {
    "name": "MATIC",
    "symbol": "MATIC",
    "decimals": 18
  },
  "rpcUrls": ["https://polygon-rpc.com"],
  "blockExplorerUrls": ["https://polygonscan.com"]
}

Automatic Network SwitchingThe portal prompts network changes when needed:

import { useNetwork, useSwitchNetwork } from 'wagmi'

const { chain } = useNetwork()
const { switchNetwork } = useSwitchNetwork()

// Switch to asset's network
if (asset.chainId !== chain?.id) {
  switchNetwork?.(asset.chainId)
}

Some operations require specific networks. The portal will prompt you to switch networks when necessary.

Add Tokens

Import Base Tokens

Add tokens used for payments:OCEAN Token Example

{
  "address": "0x967da4048cD07aB37855c090aAF366e4ce1b9F48",
  "symbol": "OCEAN",
  "decimals": 18,
  "image": "https://gateway.pinata.cloud/ipfs/..."
}

Add Token to MetaMask

Open MetaMask
Scroll to bottom, click “Import tokens”
Select “Custom token”
Enter token address
Confirm token details
Click “Add Custom Token”

Portal Token IntegrationThe portal can automatically prompt token addition:

import { useMarketMetadata } from '@context/MarketMetadata'

const { approvedBaseTokens } = useMarketMetadata()

// Display approved tokens for network
approvedBaseTokens.forEach(token => {
  // Token information for wallet import
})

Import Custom Tokens

For marketplace-specific tokens, use the token import feature:

Navigate to User Settings
Select “Custom Tokens”
Click “Import Token”
Enter token contract address
Verify token details
Complete import

Fund Your Wallet

Obtain Network Tokens

You need native tokens for gas fees:Mainnet Networks

Purchase from exchanges (Coinbase, Binance, Kraken)
Transfer from another wallet
Use on-ramp services (MoonPay, Wyre)

Testnet NetworksUse faucets for test tokens:

### Available Faucets

- Mumbai (Polygon Testnet): https://faucet.polygon.technology/
- Goerli (Ethereum Testnet): https://goerlifaucet.com/
- Sepolia (Ethereum Testnet): https://sepoliafaucet.com/

Faucet Usage

Visit faucet website
Enter your wallet address
Complete captcha/verification
Receive test tokens (usually within minutes)

For testnet environments, check the portal’s onboarding guide for direct faucet links specific to your network.

Acquire Base Tokens

Obtain tokens for purchasing assets:DEX (Decentralized Exchange)

Uniswap
SushiSwap
QuickSwap (Polygon)

CEX (Centralized Exchange)

Binance
Coinbase
Kraken

Example: Swap for OCEAN

// User typically swaps ETH/MATIC for OCEAN
// via external DEX, then returns to portal

Wallet Management

Viewing Balances

The portal displays your token balances:

import useBalance from '@hooks/useBalance'

const { balance } = useBalance()

// Balance structure
interface UserBalance {
  native: {
    symbol: string      // e.g., "ETH", "MATIC"
    balance: string     // formatted balance
  }
  approved?: {
    [address: string]: string  // token address => balance
  }
}

Balance Display

Native token (ETH, MATIC, etc.)
Approved base tokens (OCEAN, USDC, etc.)
Datatokens for owned assets

Managing Transactions

Transaction History View in MetaMask:

Open MetaMask
Click “Activity” tab
View all transactions
Click transaction for details

Transaction States

Pending: Waiting for confirmation
Confirmed: Successfully completed
Failed: Transaction reverted
Dropped: Replaced or cancelled

Speeding Up Transactions

// If transaction is stuck
// 1. Click pending transaction in MetaMask
// 2. Select "Speed Up"
// 3. Increase gas price
// 4. Confirm new transaction

Security Best Practices

Critical Security Measures

Never share private keys or recovery phrases
Verify all transaction details before confirming
Use hardware wallets for large amounts
Keep software updated
Beware of phishing attempts
Bookmark the portal URL
Enable wallet password/biometrics
Review token approvals regularly

Checking Token Approvals

import { Datatoken } from '@oceanprotocol/lib'

// Check allowance
const datatoken = new Datatoken(signer)
const allowance = await datatoken.allowance(
  tokenAddress,
  ownerAddress,
  spenderAddress
)

Tools for managing approvals:

Network Switching

Automatic Network Detection

The portal detects network mismatches:

import { useAsset } from '@context/Asset'
import useNetworkMetadata from '@hooks/useNetworkMetadata'

const { isAssetNetwork } = useAsset()
const { isSupportedOceanNetwork } = useNetworkMetadata()

if (!isAssetNetwork) {
  // Prompt: "Please switch to {network} to interact with this asset"
}

if (!isSupportedOceanNetwork) {
  // Prompt: "Unsupported network"
}

Manual Network Switching

Via Portal

Click network indicator in header
Select desired network from dropdown
Approve switch in wallet

Via MetaMask

Open MetaMask
Click network dropdown at top
Select network
Refresh portal page

Advanced Configuration

Custom RPC Endpoints

Improve performance with custom RPC providers: Infura Configuration

{
  "rpcUrls": [
    "https://mainnet.infura.io/v3/YOUR_PROJECT_ID"
  ]
}

Alchemy Configuration

{
  "rpcUrls": [
    "https://eth-mainnet.alchemyapi.io/v2/YOUR_API_KEY"
  ]
}

Hardware Wallet Integration

Ledger Setup

Connect Ledger device
Open Ethereum app on device
In MetaMask, select “Connect Hardware Wallet”
Choose Ledger
Select account to use
Confirm on device

Trezor Setup

Connect Trezor device
In MetaMask, select “Connect Hardware Wallet”
Choose Trezor
Complete Trezor Connect verification
Select account

Hardware wallets provide maximum security for high-value operations. Recommended for publishers and frequent traders.

Multiple Account Management

Switching Accounts

import { useAccount } from 'wagmi'

const { address } = useAccount()

// Portal automatically updates when account changes
// All operations use currently connected account

Account Isolation

Each account has separate:
- Asset ownership
- Transaction history
- Token balances
- Allowlist/denylist status

Troubleshooting

Connection Issues

Wallet won’t connect

Refresh the page
Disable conflicting extensions
Try incognito/private mode
Clear browser cache
Update wallet extension

“Unsupported chain” error

// Portal only supports configured networks
// Check appConfig.rbacUrl for network list

Solution:

Switch to supported network
Contact admin to add network support

Transaction Failures

“Insufficient funds for gas”

Add native tokens to wallet
Reduce transaction amount to leave room for gas

“Transaction underpriced”

Increase gas price
Wait for network congestion to decrease
Use “Fast” or “Rapid” gas settings

“Nonce too low”

// Reset account in MetaMask:
// Settings > Advanced > Reset Account

“Execution reverted”

Check asset state (may be disabled by publisher)
Verify token allowances are sufficient
Ensure you meet access requirements (allowlist)
Check for smart contract errors in block explorer

Balance Display Issues

Tokens not showing

Manually import token (see Add Tokens step)
Verify you’re on correct network
Check token balance on block explorer
Refresh browser page

Balance incorrect

// Force balance refresh
const { refetch } = useBalance()
refetch()

Wallet Best Practices

Use separate wallets: Different wallets for different purposes (trading, holding, testing)
Regular backups: Keep multiple copies of recovery phrase in secure locations
Test with small amounts: Verify operations work before large transactions
Monitor token approvals: Revoke unused approvals periodically
Enable notifications: Stay informed of account activity
Verify addresses: Double-check addresses before sending
Update software: Keep wallet and browser extensions current
Use strong passwords: Unique, complex passwords for wallet access
Consider hardware wallet: For high-value assets
Review transactions carefully: Check all details before confirming

Getting Help

If you encounter wallet issues:

Portal Support: Check FAQ and documentation
Wallet Provider: MetaMask support, WalletConnect docs
Community: Discord, Telegram channels
Block Explorer: Verify transaction status

Code References

Key implementation files:

Wallet connection: src/@utils/wallet/EthersWalletConnector.ts
Balance management: src/@hooks/useBalance.ts
Network utilities: src/@hooks/useNetworkMetadata.ts
Account state: wagmi useAccount, useNetwork hooks

Get Started

Core Features

User Guides

Configuration

Supported Wallets

Initial Setup

MetaMask Installation

Network Configuration

Import Base Tokens

Import Custom Tokens

Obtain Network Tokens

Acquire Base Tokens

Wallet Management

Viewing Balances

Managing Transactions

Security Best Practices

Network Switching

Automatic Network Detection

Manual Network Switching

Advanced Configuration

Custom RPC Endpoints

Hardware Wallet Integration

Multiple Account Management

Troubleshooting

Connection Issues

Transaction Failures

Balance Display Issues

Wallet Best Practices

Getting Help

Code References

Build docs developers (and LLMs) love

Get Started

Core Features

User Guides

Configuration

​Supported Wallets

​Initial Setup

​MetaMask Installation

​Network Configuration

​Import Base Tokens

​Import Custom Tokens

​Obtain Network Tokens

​Acquire Base Tokens

​Wallet Management

​Viewing Balances

​Managing Transactions

​Security Best Practices

​Network Switching

​Automatic Network Detection

​Manual Network Switching

​Advanced Configuration

​Custom RPC Endpoints

​Hardware Wallet Integration

​Multiple Account Management

​Troubleshooting

​Connection Issues

​Transaction Failures

​Balance Display Issues

​Wallet Best Practices

​Getting Help

​Related Resources

​Code References

Build docs developers (and LLMs) love

Supported Wallets

Initial Setup

MetaMask Installation

Network Configuration

Import Base Tokens

Import Custom Tokens

Obtain Network Tokens

Acquire Base Tokens

Wallet Management

Viewing Balances

Managing Transactions

Security Best Practices

Network Switching

Automatic Network Detection

Manual Network Switching

Advanced Configuration

Custom RPC Endpoints

Hardware Wallet Integration

Multiple Account Management

Troubleshooting

Connection Issues

Transaction Failures

Balance Display Issues

Wallet Best Practices

Getting Help

Related Resources

Code References