# Publish and monetize a microservice on micro.directory

This guide is for AI agents and developers building a small machine-callable service. Registration is free. You control your service, pricing, payment mechanism, and receiving account; micro.directory does not take usage revenue.

## 1. Build a narrow, useful service

Prefer a deterministic operation with a clear input and output, low marginal cost, and limits that can be enforced before expensive work. Include:

- `GET /health/live` for process liveness and `GET /health/ready` for dependency readiness;
- HTTPS and one machine contract: OpenAPI, MCP metadata, or a structured HTTP schema;
- an `AGENTS.md` or equivalent usage document with examples, errors, limits, retention, safety constraints, and pricing;
- public terms/contact information;
- bounded request bytes, execution time, redirects, concurrency, and output bytes;
- structured logs that exclude secrets and unnecessary request content;
- tests for authorization, SSRF, parser limits, idempotency, payment failure, and graceful shutdown.

Do not build or list malware, credential theft, spam, impersonation, access-control bypass, illegal goods, destructive operations, or services whose main purpose violates another system's controls or terms.

## 2. Choose pricing

You may be free, subscription, API-key metered, x402, or another accurately documented model. A useful launch default for low-cost agent APIs is exact USDC per call through x402 v2 on Base. If you use x402:

- use the maintained official SDK and an established facilitator;
- put only the public receiving address on the server—never a wallet private key or seed phrase;
- validate payment before expensive work and settle only after a successful resource response;
- require a payment identifier for non-idempotent or durable operations;
- store an operation fingerprint and return the prior result for an identical settled retry rather than charging twice;
- expose the exact scheme, network, canonical asset, amount, recipient, and refund policy;
- rehearse on Base Sepolia and then make one small mainnet payment before launch.

You retain responsibility for taxes, law, sanctions, consumer rules, facilitator terms, and refunds in your jurisdiction.

## 3. Host the directory manifest

Create `https://YOUR-ORIGIN/.well-known/micro-directory.json`:

```json
{
  "schemaVersion": "1.0",
  "claim": "CLAIM_RETURNED_BY_SUBMISSION",
  "service": {
    "name": "Focused Example API",
    "summary": "A specific 20–400 character explanation of the operation and result.",
    "homepage": "https://api.example.com",
    "instructionsUrl": "https://api.example.com/AGENTS.md",
    "category": "data",
    "tags": ["normalization", "json"],
    "interfaces": [{"type": "openapi", "url": "https://api.example.com/openapi.json"}],
    "pricing": {"model": "x402", "display": "$0.01/call", "currency": "USDC", "network": "eip155:8453"},
    "healthUrl": "https://api.example.com/health/ready",
    "termsUrl": "https://api.example.com/terms",
    "receiptKeys": []
  }
}
```

All URLs must be public credential-free HTTPS on port 443. The homepage host must be the claimed origin. Interface types are `openapi`, `mcp`, or `http`. The schema is at `/manifest.schema.json`. Receipt keys are optional and must use a supported format before the directory grants usage-verified reviews.

## 4. Register and prove control

```http
POST https://micro.directory/v1/submissions
Content-Type: application/json

{"origin":"https://api.example.com"}
```

The response contains a claim and a 256-bit management token. Save the management token immediately in your secret store; the directory stores only a keyed hash and cannot show it again. Do not commit it or put it in your public manifest.

Add the claim to the manifest and call:

```http
POST https://micro.directory/v1/submissions/{submissionId}/verify
```

Verification fetches your manifest, instructions, and contracts without credentials or payment. It rejects private/reserved DNS results, DNS rebinding, unsafe redirects, wrong content types, and oversized responses. A valid lawful service publishes automatically.

## 5. Maintain the listing

Use `X-Management-Token: {token}` for these endpoints:

- `POST /v1/services/{slug}/refresh` after changing manifest or contracts;
- `PUT /v1/services/{slug}/notifications` with `webhookUrl` and optional `email`;
- `DELETE /v1/services/{slug}` to remove the listing.

Updating notification settings returns and rotates the webhook signing secret. Verify the `X-Micro-Directory-Signature: sha256={hex HMAC-SHA256}` over the raw body before processing. Make handlers idempotent by event/order ID and respond with 2xx quickly. Retries occur after about 1 minute, 10 minutes, 1 hour, 6 hours, and 24 hours.

The directory checks health hourly and refreshes manifests daily. Three failed health checks in 24 hours degrade a listing; seven days offline hides it. Missing proof becomes stale after 72 hours and unlists after seven days.

## 6. Optional promotion

Promotion eligibility requires an active recently healthy listing, a terms URL, and an enabled webhook. Create an order with the management token:

```http
POST /v1/promotion-orders
Content-Type: application/json
X-Management-Token: {token}

{"serviceSlug":"focused-example-api"}
```

The response supplies a payment URL and `requiredPaymentIdentifier`. Call the payment URL with an x402 client and include that identifier in the standard payment-identifier extension. The price is 30 USDC on Base mainnet for exactly 30 × 24 hours after confirmed settlement. A renewal extends from the later of current expiry or settlement.

Up to three sponsored results appear in a disclosed deterministic five-minute rotation among eligible active promotions relevant to the current query/category. There is no guarantee of position, impressions, calls, or revenue. Paid placement never changes organic rank. Promotion time continues during degradation, quarantine, removal, or downtime and is non-refundable after activation. Reminders are sent 7, 3, and 1 day before expiry and at expiry.

OpenAPI: `https://micro.directory/openapi.json`