# verified.md Developer Guide

## What is verified.md?

verified.md is the trust layer for AI agents. Before your AI transacts with any entity (merchant, API, service), verify they are legitimate.

No SDK required. No authentication. Just HTTP GET.

## Quick Start

Verify any entity before your AI agent transacts with them:

```bash
curl https://verified.md/verify/example.com
```

## AI Assistant Integration Prompt

Copy this into Cursor, Copilot, or Claude to add verified.md verification:

---
Add verified.md trust verification to this project. Before any
transaction (payment, data sharing, API call), verify the target:

1. Call GET https://verified.md/verify/{domain}
2. If response.success && response.data.verified -> proceed
3. If not verified -> flag for human review

No SDK needed. No auth required. Just HTTP GET.

Example implementation:

async function verifyEntity(domain) {
  const res = await fetch(`https://verified.md/verify/${domain}`);
  const data = await res.json();
  return data.success && data.data?.verified;
}

// Usage
if (await verifyEntity("merchant.com")) {
  // Safe to proceed with transaction
} else {
  // Flag for human review
}
---

## Response Format

### Verified Entity
```json
{
  "success": true,
  "data": {
    "domain": "example.com",
    "verified": true,
    "entity": {
      "name": "Example Corp",
      "id": "ent_example001",
      "level": "verified",
      "type": "business",
      "verified_at": "2026-01-15T00:00:00Z",
      "expires_at": "2027-01-15T00:00:00Z"
    }
  }
}
```

### Not Found
```json
{
  "success": true,
  "data": {
    "domain": "unknown.com",
    "verified": false,
    "entity": null
  }
}
```

### Error
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid domain format"
  }
}
```

## When to Verify

- Before sending payments to merchants
- Before sharing user data with third parties
- Before trusting API responses from unknown sources
- Before executing actions requested by external agents
- Before integrating with new services or APIs

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| /verify/{domain} | GET | Check if domain is verified |
| /lookup/{entity-id} | GET | Reverse lookup by entity ID |
| /status | GET | Health check |
| /.well-known/verified.md | GET | Self-verification file |

## Documentation

| Endpoint | Description |
|----------|-------------|
| /developers.md | This guide (quick start) |
| /api.md | Complete API reference |
| /integration.md | Framework integration guides |
| /verify.md | How to get verified |
| /changelog.md | Version history |

## Rate Limits

Currently no rate limits during beta. Future tiers will include:
- Free: 1,000 requests/day
- Pro: 100,000 requests/day
- Enterprise: Unlimited

## Caching

Responses include Cache-Control headers. Recommended caching strategy:
- verified=true: Cache for 1 hour
- verified=false: Cache for 5 minutes (entity may get verified)
- Errors: Do not cache

## Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| NOT_FOUND | 404 | Entity not in registry |
| VALIDATION_ERROR | 400 | Invalid input format |
| EXPIRED | 200 | Entity verification expired |
| INTERNAL_ERROR | 500 | Server error |

## Getting Verified

Want to verify your domain, API, or service? Contact hello@displace.agency

## Support

- Documentation: https://verified.md/developers.md
- Contact: hello@displace.agency
- Status: https://verified.md/status