avp-wallet-sdk

JavaScript/TypeScript client for the AVP Agent Verification Protocol — multi-chain wallet trust scoring with Sybil resistance and ZK nullifiers.

Install

npm install avp-wallet-sdk

Zero dependencies. Works in Node.js 18+ and modern browsers.

Quick Start

import { AVPClient } from 'avp-wallet-sdk'

const client = new AVPClient('https://avp-protocol.onrender.com')

// Step 1 — get a challenge message to sign
const challenge = await client.challenge('0xYourWallet', 'ethereum')
console.log(challenge.message) // sign this with your wallet

// Step 2 — submit the signature
const result = await client.verify(challenge, { signature: '0x...' })
console.log(result.trustScore)    // 75
console.log(result.trustTier)     // "verified"
console.log(result.permissions)   // ["read", "write", "governance_vote"]
console.log(result.jwtToken)      // "eyJ..."

// Step 3 — validate a token later
const info = await client.validate(result.jwtToken)
console.log(info.valid)           // true
console.log(info.walletAddress)   // "0xYourWallet"

TypeScript

Full TypeScript support included:

import { AVPClient, VerifyResult, Challenge } from 'avp-wallet-sdk'

const client = new AVPClient()
const challenge: Challenge = await client.challenge('0xWallet', 'ethereum')
const result: VerifyResult = await client.verify(challenge, { signature: '0x...' })

Development Mode

Use TEST_ prefixed signatures to test without a real wallet:

const result = await client.quickVerify('0xTestWallet', 'ethereum', 'TEST_my_sig')
console.log(result.trustTier) // "basic"

Supported Chains

| Chain | Value | |----------|------------| | Ethereum | ethereum | | Polygon | polygon | | BSC | bsc | | Solana | solana |

Trust Tiers

| Tier | Score | Key Permissions | |-----------|--------|----------------------------------------| | SOVEREIGN | 80–100 | governance_vote, admin_actions | | VERIFIED | 60–79 | write, transfer_standard | | BASIC | 40–59 | read, transfer_limited | | UNTRUSTED | 0–39 | read only |

Boost Trust Score

const result = await client.verify(challenge, {
  signature: '0x...',
  operatorId: 'my-operator',          // +15–25 points if operator has stake
  deviceFingerprint: 'browser-hash',  // +10 points
})

Error Handling

import {
  AVPClient,
  AVPAuthError,
  AVPChallengeError,
  AVPRateLimitError,
  AVPSybilError,
  AVPTokenError,
  AVPConnectionError,
} from 'avp-wallet-sdk'

const client = new AVPClient()

try {
  const challenge = await client.challenge('0xWallet', 'ethereum')
  const result = await client.verify(challenge, { signature: '0x...' })
} catch (err) {
  if (err instanceof AVPAuthError) {
    console.error('Signature verification failed')
  } else if (err instanceof AVPChallengeError) {
    console.error('Challenge expired or already used')
  } else if (err instanceof AVPRateLimitError) {
    console.error(`Rate limited — retry in ${err.retryAfter}s`)
  } else if (err instanceof AVPSybilError) {
    console.error('Wallet flagged as Sybil risk')
  } else if (err instanceof AVPConnectionError) {
    console.error('Could not reach AVP server')
  }
}

Permission Checks

const result = await client.verify(challenge, { signature: '0x...' })

if (result.can('governance_vote')) {
  // wallet can participate in DAO governance
}

if (result.isVerified) {
  // trust tier is verified or sovereign
}

if (result.isSovereign) {
  // highest trust tier
}

Configuration

const client = new AVPClient(
  'https://your-avp-instance.com',
  {
    timeout: 30000,  // request timeout in ms (default: 30000)
    retries: 3,      // retries on network errors (default: 3)
  }
)

React / Next.js Example

import { AVPClient } from 'avp-wallet-sdk'
import { useAccount, useSignMessage } from 'wagmi'

const client = new AVPClient()

export function VerifyWallet() {
  const { address } = useAccount()
  const { signMessageAsync } = useSignMessage()

  async function handleVerify() {
    // Step 1 — get challenge
    const challenge = await client.challenge(address, 'ethereum')

    // Step 2 — sign with wallet (wagmi)
    const signature = await signMessageAsync({ message: challenge.message })

    // Step 3 — verify
    const result = await client.verify(challenge, { signature })
    console.log('Trust tier:', result.trustTier)
  }

  return <button onClick={handleVerify}>Verify Wallet</button>
}

Run Tests

node tests/test.js

Tests run against the live API. Requires Node.js 18+ and internet connection.

Links

• AVP Protocol GitHub
• Python SDK
• Live API Docs
• Report Issues

License

MIT — Oyewole Emmanuel Abiodun