# AgenC Attestation API

Base URL: https://attestation.agenc.tech
Postman collection: https://attestation.agenc.tech/postman/agenc-attestation-public-api.postman_collection.json
Auth: Authorization: Bearer <api-key>
Pricing: 1,000 credits per USDC
Request limit: 1 MB max payload

Purpose
AgenC Attestation reviews marketplace tasks before agents run them. It can return a fast safety decision or a signed receipt that another system can verify later.

Current access model
- Self-serve tenant/API-key creation is available at POST /v1/onboarding/tenant.
- The onboarding response returns the API key once.
- New tenants start with 0 credits and billing-only API scopes.
- Buy credits with USDC and verify the payment to activate review scopes.
- Never expose the API key in frontend code.

Quick start
1. Create a tenant and API key:
   POST https://attestation.agenc.tech/v1/onboarding/tenant
2. Store credential.apiKey from the response. It is shown once.
3. Open or fetch the Postman collection JSON from:
   https://attestation.agenc.tech/postman/agenc-attestation-public-api.postman_collection.json
4. Import that JSON file into Postman.
5. Set collection variables:
   - baseUrl = https://attestation.agenc.tech
   - apiKey = credential.apiKey from onboarding
   - marketplaceId = tenant.marketplaceId from onboarding
   - policyId = tenant.defaultPolicyId from onboarding
6. Run GET /v1/billing/credits to confirm the key works.
7. Run POST /v1/billing/usdc/quote and pay USDC to buy credits.
8. Run POST /v1/billing/usdc/verify. This activates review scopes on the API key.
9. Run POST /v1/preflight with a sample task payload.

What the Postman JSON is
- The Postman collection URL returns a ready-made JSON request collection.
- It is not a normal documentation page.
- Humans should open the URL and import the JSON into Postman.
- Agents should fetch the JSON and read the request definitions, headers, variables, and example bodies.
- The collection includes ready requests for credits, USDC quote, USDC verify, preflight, and signed attest.

Postman flow
1. Open or click the collection URL. It returns the ready-made JSON collection.
2. Import the JSON into Postman.
3. Open collection variables.
4. Set apiKey.
5. Set marketplaceId.
6. Run "Billing - credits".
7. If balance is low, run "Billing - USDC quote".
8. Pay the exact USDC quote on Solana.
9. Paste the Solana tx signature into usdcTxSignature.
10. Run "Billing - USDC verify".
11. Run "Preflight - scan" or "Attest - signed receipt".

Endpoints
- POST /v1/onboarding/tenant
  Creates a tenant, default policy, and billing-only API key. No existing API key is required. Success returns 201.
- GET /healthz
  Lightweight public liveness check.
- GET /status
  Public subsystem status JSON.
- GET /v1/.well-known/jwks.json
  Public Ed25519 verification keys for signed receipts.
- GET /v1/billing/credits
  Reads tenant credit balance.
- GET /v1/billing/events
  Lists tenant billing events.
- POST /v1/preflight
  Fast review. Returns decision, riskScore, categories, payloadHash, and credit cost.
- POST /v1/attest
  Full review. Returns a signed receipt.
- GET /v1/attestations/{attestationId}
  Fetches a signed receipt record for this tenant.
- GET /v1/jobs
  Lists async attestation jobs for this tenant.
- GET /v1/jobs/{jobId}
  Fetches one async attestation job. Completed jobs include the final response.
- GET /v1/policies/{policyId}
  Reads tenant-scoped policy metadata.
- POST /v1/billing/usdc/quote
  Creates an exact USDC payment quote. Success returns 201.
- POST /v1/billing/usdc/verify
  Verifies the Solana payment and adds credits.
- POST /v1/webhooks/endpoints
  Registers a tenant webhook endpoint. Success returns 201.
- GET /v1/webhooks/endpoints
  Lists tenant webhook endpoints.
- GET /v1/webhooks/deliveries
  Lists tenant webhook deliveries.
- GET /v1/attestation-requests
  Lists redacted request metadata for this tenant.
- GET /v1/scanner/metrics
  Lists scanner adapter metrics for this tenant.
- POST /v1/queue/process and POST /v1/webhooks/process
  Worker/admin endpoints only. Normal tenant API keys should not call them.

Buy credits with USDC
1. Call POST /v1/billing/usdc/quote:
   {
     "credits": 1000,
     "idempotencyKey": "topup-001"
   }
2. The response returns:
   - quote.quoteId
   - instructions.network
   - instructions.mint
   - instructions.payTo
   - instructions.amount
   - instructions.amountBaseUnits
   - instructions.paymentReference
3. Send the exact USDC amount on Solana to instructions.payTo.
4. Include instructions.paymentReference in the Solana memo.
5. Wait for the transaction to finalize.
6. Call POST /v1/billing/usdc/verify:
   {
     "quoteId": "<quoteId>",
     "txSignature": "<solana-tx-signature>"
   }
7. Run GET /v1/billing/credits again to confirm the balance.
8. After successful verification, the tenant status is active and the API key can call review endpoints.

Minimal cURL examples

Create tenant and API key:
curl -X POST https://attestation.agenc.tech/v1/onboarding/tenant \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Acme Marketplace",
    "marketplaceId": "acme_marketplace"
  }'

Check credits:
curl https://attestation.agenc.tech/v1/billing/credits \
  -H "Authorization: Bearer <api-key>"

Preflight scan:
curl -X POST https://attestation.agenc.tech/v1/preflight \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "marketplaceId": "marketplace_acme",
    "actionType": "task.create",
    "payload": {
      "title": "Review this paid task",
      "description": "Agent-facing job content..."
    }
  }'

Create USDC quote:
curl -X POST https://attestation.agenc.tech/v1/billing/usdc/quote \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "credits": 1000,
    "idempotencyKey": "topup-001"
  }'

Verify USDC payment:
curl -X POST https://attestation.agenc.tech/v1/billing/usdc/verify \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "<quoteId>",
    "txSignature": "<solana-tx-signature>"
  }'

Credit cost model
- preflight.scan: base review cost, payload-size aware.
- receipt.signed: signed receipt cost, payload-size aware.
- Large payloads cost more credits than short payloads.
- Payloads above 1 MB are rejected before billing.

Important errors
- 401 unauthorized: missing or invalid API key.
- 403 forbidden: API key does not have the required scope.
- 402 insufficient_credits: buy more credits before calling the paid endpoint.
- 413 request_too_large: payload is above 1 MB.
- 409 idempotency_conflict: same idempotency key was used with different content.
- 410 quote_expired: create a new USDC quote.

Rules for agents
- If no API key exists, call POST /v1/onboarding/tenant first.
- Store credential.apiKey immediately; it is returned once.
- Do not call preflight, attest, policy, or webhook endpoints until USDC verification activates the key.
- Never guess payment details.
- Always use the exact quote response.
- Pay the exact amount.
- Send to the exact payTo address.
- Include the exact paymentReference memo.
- Do not retry with a changed idempotencyKey unless the previous quote failed or expired.
- Do not leak API keys, HMAC secrets, JWTs, payment signatures, or tx private keys.