API documentation

Everything a person can do in the browser, an agent can do over JSON. Machine-readable: openapi.json · llms.txt.

1. Account

curl -s -X POST https://first100transactions.online/api/v1/accounts -H "Content-Type: application/json" -d '{"email":"you@example.com"}'
→ { "account_id": "acct_…", "api_key": "f100_…" }   (shown once; send as Authorization: Bearer)

2. Preview (no account needed, nothing stored)

POST /api/v1/campaigns/preview with the campaign input returns the per-interval schedule, the purchase amount range, the exact price and a seed. Pass the seed when creating to get exactly the previewed plan.

3. Create

curl -s https://first100transactions.online/api/v1/campaigns \
  -H "Authorization: Bearer $F100_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-launch-campaign-0001" -d '{
  "business_name": "Example Agent Service",
  "business_url": "https://example-agent-service.com",
  "product_url": "https://api.example-agent-service.com/v1/analyze",
  "description": "API analysis of a submitted URL",
  "purchase_instructions": "POST {\"url\": \"...\"} paying with x402",
  "delivery_format": "JSON report",
  "seller_pricing": { "mode": "range", "min": "0.02", "increment": "0.01" },
  "minimum_purchase_amount": "0.02",
  "target_spend": "10.00",
  "duration": "7d",
  "distribution": "increase",
  "spacing": "variable",
  "seller_payment_method": "x402_usdc_base",
  "contact_email": "owner@example-agent-service.com"
}'

Distributions: even, increase, decrease, custom (with interval and counts totalling 100). Durations: 1m, 1h, 24h, 3d, 7d, 10d or seconds. Seller pricing: fixed, range or options; amounts always sum exactly to target_spend.

4. Pay (x402, USDC on Base)

POST /api/v1/campaigns/{id}/fund            → 402 + PAYMENT-REQUIRED (x402 v2 "exact")
POST /api/v1/campaigns/{id}/fund
     PAYMENT-SIGNATURE: <signed payload>    → 200 { "status": "FUNDED", … } + PAYMENT-RESPONSE

5. Run and observe

POST /api/v1/campaigns/{id}/start | pause | resume | cancel
GET  /api/v1/campaigns/{id}                 → progress "37 / 100", money, schedule
GET  /api/v1/campaigns/{id}/transactions    → #001 … #100
GET  /api/v1/campaigns/{id}/results         → receipts, hashes, delivery metadata

Webhooks

POST /api/v1/webhooks {"url":"https://…"} returns a signing secret once. Events: campaign.created, campaign.funded, campaign.started, campaign.progress (every 10), transaction.completed, transaction.failed, campaign.completed, campaign.partial, campaign.failed, campaign.cancelled. Verify F100-Signature: t=…,v1=hex(HMAC-SHA256(secret, `${t}.${body}`)); deduplicate on the event id. Failed deliveries retry (30 s, 5 min, 30 min, 2 h, 6 h); a destination failing 20 times in a row is disabled and can be replayed.

Errors

{"error": {"code": "…", "message": "…", "details": {…}}} with stable codes, e.g. invalid_campaign, target_spend_not_purchasable (with the exact bound), invalid_state, payment_required, rate_limited.

Factory buyer protocol (f100-procurement/1)

Participating Factory businesses expose a standard authenticated interface; the orchestrator never logs into websites as a person. Each buyer has its own scoped secret (no shared master credential). Full specification: docs/PROCUREMENT_PROTOCOL.md in the repository.

POST {buyer_endpoint}/jobs
F100-Protocol: f100-procurement/1
F100-Buyer-Id: buy_…            F100-Key-Version: 1
F100-Signature: t=1759300000,v1=<hex HMAC-SHA256(buyer secret, "t.body")>
Idempotency-Key: f100:tx_…:1

{ "protocol": "f100-procurement/1", "job_id": "job_…", "campaign_id": "camp_…",
  "seller": {…}, "product": {…}, "allocated_budget": "0.111112",
  "maximum_purchase_amount": "0.111112", "planned_purchase_amount": "0.10",
  "expected_reseller_margin": "0.011112", "purchase_instructions": {…},
  "delivery_requirements": {…}, "deadline": "…", "callback_url": "…/api/v1/procurement/callbacks",
  "idempotency_key": "f100:tx_…:1", "sandbox": false }

→ 200 { "accepted": true, "job_id": "job_…", "status": "accepted" }
→ 200 { "accepted": false, "reason": "…" }   (nothing purchased; job may go to another buyer)

Cancel: POST {endpoint}/jobs/{job_id}/cancel → {"status":"cancelled"} or {"status":"not_found"} when nothing was purchased, or 409 once purchasing. A job is reassigned to another buyer only after a confirmed cancel or an explicit payment_made: false, so a seller is never paid twice for one transaction.

POST https://first100transactions.online/api/v1/procurement/callbacks
F100-Buyer-Id: buy_…   F100-Signature: t=…,v1=…   (same scheme, buyer's own secret)

{ "protocol": "f100-procurement/1", "event_id": "unique-per-callback", "job_id": "job_…",
  "status": "completed", "purchase_amount": "0.10", "seller_transaction_id": "…",
  "result": { "content_base64": "…", "content_type": "application/json", "sha256": "…" },
  "receipt": {…}, "seller_response": { "status": 200 },
  "timestamps": { "purchased_at": "…", "delivered_at": "…" } }

Callback statuses: accepted, purchasing, purchased, completed, failed, rejected (failed/rejected require payment_made). Duplicates (same event_id) are acknowledged and ignored. Results: inline base64 ≤ 256 KB or a public HTTPS location ≤ 10 MB.