HTTP API overview

This reference describes the public JSON API for EBG Tokenizer: create certificate collections, mint and update NFT metadata, and serve ERC-721 metadata documents. The service talks to the factory and certificate contracts on Arbitrum (chain id 42161).

Base URL (hosted): https://ebg-tokenizer.u3dev.deno.net/ — use BASE_URL in the examples below. Another operator may expose the same API at a different origin.

Terminology

• Factory — Onchain contract that deploys certificate collections and performs mints for callers with MINTER_ROLE. HTTP routes live under /factory.
• Certificate (contract) — One deployed ERC-721 collection per create_certificate. Use its address in /certificates/:address.
• NFT / token — Each mint is a token with a tokenId and the certificate struct stored onchain. Wallets resolve tokenURI to JSON; this API can serve that JSON at GET /metadata/:chainId/:addressOrCertificateId/:tokenId (public, no API key). When creating a collection, set baseUri so onchain base_uri + tokenId matches that URL (see NFT metadata).

Integration quickstart

The deployment must have chain access and a configured signer for write operations. Clients send JSON only—they never submit private keys.

flowchart LR create["POST /factory/certificates"] mint["POST /certificates/:address/mint"] create -->|certificateAddress| mint

1. Create a collection — POST /factory/certificates with nft.name, nft.symbol, and optionally nft.baseUri. Read certificateAddress from the response (Factory routes).
2. Mint an NFT — POST /certificates/{certificateAddress}/mint with to and certificate fields under certificate, data, or certificateData (Certificate routes).
3. (Optional) List deployments — GET /factory/certificates or GET /factory/certificate-count.

If your operator enabled API key authentication, add -H "x-api-key: YOUR_KEY" to POST (and other protected) requests. Omit the header only when the operator confirms auth is disabled.

BASE_URL="https://ebg-tokenizer.u3dev.deno.net"

curl -sS -X POST "$BASE_URL/factory/certificates" \
  -H "Content-Type: application/json" \
  -d '{"nft":{"name":"My Cohort","symbol":"CERT","baseUri":"https://example.com/meta/"}}'

curl -sS -X POST "$BASE_URL/certificates/0xYourCertificate/mint" \
  -H "Content-Type: application/json" \
  -d '{"to":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb","certificate":{"registration_date":1710892800,"delivery_correlative":"2024-001","participant_names":"Ada","participant_last_names":"Lovelace","course_name":"Intro","hours_number":40,"sessions_number":10,"issuing_institution":"Example University","image_url":"https://example.com/img.png","certificate_url":"https://example.com/cert.pdf"}}'

After mint, fetch the URI with GET /certificates/:address/token-uri/:tokenId (or .../tokens/:tokenId/tokenURI), and fetch metadata JSON at GET /metadata/42161/:certificateAddress/:tokenId or GET /metadata/42161/:certificateId/:tokenId (NFT metadata).

Integrator notes

• Chain — Use Arbitrum explorers with transaction hashes from API responses.
• Who signs — Browsers and integrators do not sign chain transactions for hosted writes; the service submits transactions on behalf of its configured account.
• CORS — Responses may include Access-Control-Allow-Origin: * and allow the x-api-key header so browser apps can call the API when that policy is acceptable; otherwise use a backend or BFF.
• Authentication — When enabled on a deployment, routes under /factory, /certificates, and /keys require a valid x-api-key: read keys allow GET/HEAD only; minter keys allow writes on factory and certificate routes but not /keys; master keys allow everything including issuing and revoking keys via /keys. GET /metadata/... and GET / typically stay public.

API authentication (x-api-key)

When authentication is enabled, the service checks x-api-key on /factory, /certificates, and /keys.

Status	When
401	Missing x-api-key header on a protected path, or key not recognized.
403	Valid key but wrong capability: e.g. read key on POST / PUT / PATCH / DELETE; minter or read key on /keys.

When authentication is disabled for a deployment, GET /, GET /metadata/..., and OPTIONS preflight remain usable without a key; protected routes may also accept anonymous callers depending on operator policy—confirm with your operator.

Mutating endpoints (index)

Method	Path	Documentation
POST	/factory/certificates	Factory routes — POST
POST	/certificates/:address/mint	Certificate routes — POST mint
PUT	/certificates/:address/tokens/:tokenId	Certificate routes — PUT
PATCH	/certificates/:address/tokens/:tokenId	Certificate routes — PATCH
POST	/keys	Keys routes — issue
DELETE	/keys/:id	Keys routes — revoke

API reference

Page	Coverage
Factory routes	POST / GET under /factory
Certificate routes	Collection routes, mint, metadata, ERC-721 helpers
Keys routes	Issue, list, and revoke issued minter/read keys (master key only)

Certificate-scoped paths are always /certificates/:address. To enumerate collections from the factory, use /factory/certificate-count and /factory/certificates/:index.

Base URL

GET https://ebg-tokenizer.u3dev.deno.net/ (or {BASE_URL}/) returns JSON with API metadata, for example:

{
  "title": "EBG Tokenizer API",
  "version": "1.0.0",
  "description": "API for the EBG Tokenizer",
  "routes": [
    { "path": "/factory", "description": "Factory routes" },
    { "path": "/certificates", "description": "Certificate routes" },
    { "path": "/metadata", "description": "Metadata routes" },
    { "path": "/keys", "description": "API key management" }
  ]
}

Deployment behavior (reference)

These are not request parameters; they describe what the operator configures on the service:

Area	Purpose
Factory contract address	Required for factory reads and for resolving numeric certificate ids in /metadata/....
Signing account (server-side)	Required for HTTP write routes; used only inside the service.
Metadata public origin	When creating a collection without an explicit baseUri, used so tokenURI can point at this API’s /metadata/... routes.
API keys (optional)	When enabled, protect /factory, /certificates, and /keys with x-api-key; master keys can issue additional minter/read keys via /keys.

If authentication is disabled, network access to write routes depends on who can reach the deployment—treat write endpoints as privileged.

Conventions for callers

• Send JSON with Content-Type: application/json.
• Onchain integers in JSON responses are often decimal strings (e.g. "42").
• Errors use { "message": string }. Typical statuses: 400 validation, 404 not found, 500 / 502 configuration or upstream failures.

BASE_URL="https://ebg-tokenizer.u3dev.deno.net"
curl -sS -X GET "$BASE_URL/factory/certificate-count"

Full request/response shapes: Factory routes, Certificate routes, Keys routes.