Skip to content

Instantly share code, notes, and snippets.

@Aboudjem

Aboudjem/28-passport-populator.md

Last active March 30, 2026 08:00
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save Aboudjem/bd4a315db7ddc7dce496c5731d158258 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save Aboudjem/bd4a315db7ddc7dce496c5731d158258 to your computer and use it in GitHub Desktop.
Download ZIP
Integra PRD: 28-passport-populator
Raw
28-passport-populator.md

Passport Populator

Owner: Kalki | Ship: Week 3 | Est: 0.5 day | Chain: integra-testnet-1 (EVM 26218) URL: N/A (headless agent, monitored via Agent Arena)

Overview

Autonomous agent that scrapes public real estate data from multiple sources and auto-generates Asset Passports on-chain. Raw listing data is normalized into structured passport metadata using AI, then minted via AgentAuth delegation. This solves the cold-start problem by filling GOB with thousands of realistic property listings without any manual data entry. Every mint is a real on-chain transaction contributing to the 1M+ tx target.

Features

  • Multi-Source Scraping — Pulls public listing data from Zillow, Realtor.com, and county public records via Apify actors
  • AI Structuring — LLM normalizes raw, messy listing data into the AssetPassport schema (address, sqft, beds/baths, year built, zoning, valuation, images)
  • Automated Minting — Calls AssetPassport.mint() for each structured listing, writing the passport on-chain without human intervention
  • AgentAuth Integration — Agent registers on startup, receives a session wallet, and signs all txs via delegated auth
  • Configurable Targeting — Operator sets target city, property type (residential/commercial/land), price range, and volume cap per hour
  • Rate Limiting — Respects source rate limits and applies configurable delay between mints (default: 1 tx/sec)
  • Batch Processing — Groups mints where possible to optimize gas usage and throughput
  • Activity Logging — Logs every mint tx hash, success/failure status, gas used, and metadata quality score
  • Agent Arena Monitoring — Registers itself in Agent Arena, reports heartbeat, and surfaces throughput/error metrics on the dashboard
  • Fault Tolerance — Retries failed mints with exponential backoff, skips permanently invalid listings, and resumes from last checkpoint on restart
  • Data Deduplication — Tracks minted addresses to avoid duplicate passports for the same property

Functions

  • scrapeListings(city, propertyType, priceRange) — Fetches raw listing data from configured public sources
  • structurePassport(rawListing) — AI-normalizes raw data into valid AssetPassport metadata JSON
  • mintPassport(metadata) — Calls AssetPassport.mint(bytes metadata) via AgentAuth session wallet
  • getAgentStatus() — Returns current throughput, error rate, total minted, and uptime
  • configure(targetCity, propertyType, priceRange, volumePerHour) — Updates agent targeting parameters at runtime
  • validateMetadata(passportJSON) — Validates structured metadata against the AssetPassport schema before minting

User Flow

  1. Operator configures target parameters: city, property type, price range, volume per hour
  2. Agent authenticates via AgentAuth and receives a session wallet
  3. Scraper pulls public listing data from configured sources
  4. AI structuring layer normalizes each listing into AssetPassport schema
  5. Agent validates metadata and calls AssetPassport.mint() for each listing
  6. Agent logs every tx hash, gas used, and success/failure status
  7. Operator monitors throughput and errors via Agent Arena dashboard
  8. Minted passports automatically appear in GOB listings

Deliverables

  • Scraper module with Apify actors for Zillow and Realtor.com (+ public records fallback)
  • AI structuring module that normalizes raw listings into AssetPassport metadata
  • Minting module with AgentAuth session key signing and batch support
  • Configuration system (target city, property type, price range, volume cap, scrape interval)
  • Rate limiter respecting source limits and configurable mint delay
  • Deduplication tracker (no duplicate passports for same property)
  • Activity logger with per-tx details (hash, gas, status, metadata quality)
  • Agent Arena registration with heartbeat and dashboard metrics
  • Fault tolerance: retry with backoff, skip invalid, resume from checkpoint

Integration Points

  • Depends on: AgentAuth (session wallet), AssetPassport.sol (mint()), Apify (scraping actors), AI model (structuring)
  • Used by: GOB (minted passports appear as marketplace listings), Agent Arena (monitoring dashboard)
  • Explorer: Integra Explorer (all mint txs visible)

XP Rewards

Action Points
Successful passport mint (per tx) Standard agent XP rate
Passport later wrapped or traded on GOB Bonus XP
Reach 1,000 passports minted (operator badge) "Populator" badge

Success Metrics

Metric Target
Sustained minting throughput 60 mints/hour
Uptime without crash or stall 24+ hours continuous
Total passports minted in first week 5,000+
Metadata validation pass rate >95%
Passports subsequently wrapped or traded >10%
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment