JSON-OS • Policy Caps & Autonomous Ad Buys

Complete technical reference for building AI agents that autonomously discover, evaluate, and purchase verified ad placements using our JSON-OS contracts and MCP server integration.

The Plan → Guard → Receipt Flow

1. Plan
Agent discovers & evaluates slots

Your agent calls ads.list@1 to discover available slots. Filter by domain reputation, pricing, dimensions, and EAS attestations.

2. Guard
Policy caps enforce spending limits

Before executing ads.buy@1, your policy object checks: max spend per window, approved domains, creative guidelines, and budget caps.

3. Receipt
On-chain verification & settlement

After SLA verification, ads.settle@1 emits an immutable receipt with proof bundles, Merkle roots, and payment details.

Copy-Paste Policy Objects

Define spending limits and approval rules for your autonomous agent. These policies are enforced before any transaction is executed.

example-policy.json
{
  "version": "1.0",
  "maxSpendPerWindow": {
    "amount": "100",
    "currency": "USDC"
  },
  "approvedDomains": [
    "example.com",
    "trusted-site.io"
  ],
  "windowTypes": ["day", "week"],
  "maxSlotPrice": {
    "day": "10",
    "week": "50"
  },
  "requiredAttestations": [
    "EAS:DomainOwnership",
    "EAS:SlotProof"
  ],
  "creativeGuidelines": {
    "maxFileSize": "500kb",
    "allowedFormats": ["image/png", "image/jpeg"],
    "dimensions": ["300x250", "728x90"]
  },
  "autoApprove": false,
  "notifyOnPurchase": true
}

Minimal ads.list/buy/settle Reference

ads.list@1
Discover available ad slots

Request:

POST /api/ads/list
{
  "filters": {
    "minReputation": 80,
    "maxPrice": "50",
    "dimensions": ["728x90"],
    "hasEAS": true
  }
}

Response:

{
  "slots": [
    {
      "id": "slot_abc123",
      "domain": "example.com",
      "dimensions": "728x90",
      "pricePerDay": "10",
      "pricePerWeek": "50",
      "reputation": 95,
      "easAttestations": ["0x..."],
      "availability": "immediate"
    }
  ]
}
ads.buy@1
Purchase a verified slot

Request:

POST /api/ads/buy
{
  "slotId": "slot_abc123",
  "window": "week",
  "creativeIPFS": "ipfs://Qm...",
  "escrowAmount": "50",
  "walletAddress": "0x..."
}

Response:

{
  "campaignId": "camp_xyz789",
  "status": "escrowed",
  "startTime": "2025-01-15T00:00:00Z",
  "endTime": "2025-01-22T00:00:00Z",
  "txHash": "0x..."
}
ads.settle@1
Verify SLA and settle payment

Automatic Settlement:

{
  "campaignId": "camp_xyz789",
  "slaStatus": "passed",
  "uptimePercentage": 99.8,
  "proofBundle": {
    "merkleRoot": "0x...",
    "visibilityChecks": 1008,
    "failedChecks": 2
  },
  "settlement": {
    "publisherPayout": "49",
    "protocolFee": "1",
    "refund": "0"
  },
  "receiptTxHash": "0x..."
}

JSON-OS Invocation & Agent Pseudocode

Example implementation for an autonomous agent that discovers and purchases ad slots within policy constraints.

autonomous-agent.ts
import { AgentAds } from '@agent-ads/sdk'
import { loadPolicy } from './policy-loader'

async function autonomousAdBuying() {
  // Load policy constraints
  const policy = await loadPolicy('./my-policy.json')
  
  // Initialize SDK with MCP server
  const ads = new AgentAds({
    mcpServer: 'https://mcp.agentads.io',
    walletAddress: process.env.AGENT_WALLET
  })
  
  // Discover slots matching policy
  const slots = await ads.list({
    maxPrice: policy.maxSlotPrice.week,
    requiredAttestations: policy.requiredAttestations,
    domains: policy.approvedDomains
  })
  
  // Evaluate and rank by reputation/price
  const bestSlot = slots
    .filter(s => s.reputation >= 80)
    .sort((a, b) => b.reputation - a.reputation)[0]
  
  // Check policy guard
  if (!policy.autoApprove) {
    await notifyHuman(bestSlot)
    return
  }
  
  // Execute purchase within spending cap
  if (parseFloat(bestSlot.pricePerWeek) <= policy.maxSpendPerWindow.amount) {
    const campaign = await ads.buy({
      slotId: bestSlot.id,
      window: 'week',
      creativeIPFS: await uploadCreative('./ad.png'),
      escrowAmount: bestSlot.pricePerWeek
    })
    
    console.log(`Campaign ${campaign.id} escrowed. Receipt: ${campaign.txHash}`)
    
    // Monitor settlement
    await ads.onSettle(campaign.id, (receipt) => {
      console.log(`Settlement complete. Uptime: ${receipt.uptimePercentage}%`)
    })
  }
}

autonomousAdBuying()

Safety & Attestation Model

Domain Verification

Publishers prove ownership via DNS-TXT challenge. The verification result is attested on-chain using Ethereum Attestation Service (EAS).

EAS Schema: DomainOwnership
Attester: 0x...AgentAdsVerifier

Slot Proofs

Each ad slot receives an EAS SlotProof attestation linking the domain, wallet, dimensions, and policies. This creates portable trust across the ecosystem.

EAS Schema: SlotProof
Includes: domain, wallet, size, SLA

Visibility Verification

IntersectionObserver APIs track actual visibility. DOM hashes and screenshot proofs verify creative presence. Random checks from diverse ASNs prevent cloaking.

Checks: Every 10 min
Proof Bundle: Merkle root on-chain

Dispute Resolution

All proof bundles are public and verifiable. A dispute window allows challenges before final settlement. Failed SLAs trigger automatic partial/full refunds.

Dispute Window: 24 hours
Refund: Proportional to downtime

Try It Now Add Your SiteView on GitHub