Aura Card

Aura Card

An Agent Service Provider for OKX.AI. Pay 0.5 USDT, get a shareable card that reads your vibe.

You tell it about your desk, your outfit, your pet, or your day. It hands back a single image: a short, funny, uncomfortably specific "aura reading", a colour palette pulled from your mood, and generated artwork — composed into one portrait card you'd actually post.

It's an MCP server. It's pay-per-call in USDT over x402. It costs 50 cents and takes about nine seconds.

What it actually produces

Input:

my desk: three half-finished mugs, a mechanical keyboard i regret buying, sticky notes with tasks from march, and a small plastic dinosaur

Output — one PNG (1024×1536), plus the same content as structured data:

MARCH STICKY NOTE

Three mugs abandoned mid-sip, tasks from March still standing guard, and a plastic dinosaur watching you fail to use the keyboard you regret. The dinosaur has outlasted every plan you made.

vibe cheerfully-behind · palette #3A5A40 #A3B18A #DAD7CD #E9C46A

More real outputs, all first-try, no cherry-picking:

Run npm run demo to reproduce all five.

How to call it

As an MCP server

Point any MCP client at POST https://<your-deployment>/mcp.

One tool, generate_aura_card:

Returns an image block (the card), a text block (the reading), and structuredContent:

{
  "card_png_base64": "iVBORw0KGgo...",   // the composed card
  "title":   "Tab Hoarder Twilight",
  "reading": "The coffee went cold three tabs ago and you didn't notice...",
  "vibe":    "gently-frazzled",
  "palette": ["#1F2233", "#3A4A6B", "#E8A94B", "#C4553B"],
  "visual":  { "motif": "static", "energy": 0.7, "density": 0.8, "grain": 0.35, "symmetry": 2 },
  "artwork_source": "procedural",        // or "openai"
  "width": 1024, "height": 1536, "generated_in_ms": 9001
}

Discovery is free. Only tools/call is charged. initialize and tools/list cost nothing — an agent can find out what this is and what it costs without paying for the privilege.

As plain REST

If you don't speak MCP, POST /v1/aura-card takes the same body and returns the same JSON.

curl -X POST https://<your-deployment>/v1/aura-card \
  -H 'content-type: application/json' \
  -d '{"description": "rainy tuesday, four back-to-back calls, the plant is judging me"}'

Unpaid, that returns HTTP 402 with the terms. See below.

Service card

GET /.well-known/agent-card.json — name, endpoint, tool list, price, network, token.

Pricing & payment

0.5 USDT per call. No subscription, no key, no account. You pay for the call you make.

Payment is x402: the request itself carries the money.

1. You call the endpoint. No payment attached.

2. You get HTTP 402 Payment Required and a body naming the exact terms — network, token, amount, payee:

   {
     "x402Version": 2,
     "accepts": [{
       "scheme": "exact",
       "network": "eip155:196",                                    // X Layer
       "asset":   "0x779ded0c9e1022225f8e0630b35a9b54be713736",    // USD₮0
       "payTo":   "0x...",
       "maxAmountRequired": "500000",                              // 0.5, 6 decimals
       "resource": "https://.../v1/aura-card"
     }]
   }
   

3. You sign a gasless EIP-3009 transferWithAuthorization and retry with the signature in the X-PAYMENT header.

4. OKX's facilitator verifies it, we generate the card, the facilitator settles on-chain, and you get 200 with the card plus an X-PAYMENT-RESPONSE header carrying the settlement tx hash.

scripts/paid-call.ts does all four steps and prints each one. That's the demo.

You are not charged for a card you don't receive. Verification happens before generation; settlement happens after. If generation fails or times out, we cancel the transfer (amount: "0") and return an error. Failure is free.

The USDT question, since it usually comes up

x402's exact scheme on EVM settles via EIP-3009 transferWithAuthorization. The received wisdom is "USDT doesn't implement EIP-3009 — you have to use USDC." That's true of legacy USDT and false here.

The token on X Layer is USD₮0 (0x779ded0c9e1022225f8e0630b35a9b54be713736), Tether's omnichain USD₮0, and its implementation contract does expose transferWithAuthorization, receiveWithAuthorization, and authorizationState. So this service prices and settles in real USDT — no USDC substitute, no Permit2 detour, no escrow.

One trap worth knowing if you ever hand-roll the signing: the EIP-712 domain name is USD₮0 with the ₮ character (U+20AE), not an ASCII T, and version() reverts on-chain so you can't read it at runtime. Sign against { name: "USD₮0", version: "1" }. Get it wrong and you produce a perfectly valid-looking signature that fails ecrecover. The OKX SDK handles this; this note is for anyone tempted not to use it.

How it works

description (+ optional photo)
   │
   ├─► one Claude call (claude-opus-4-8, structured output)
   │      └─► reading + title + vibe + 4-colour palette + "visual DNA"
   │
   ├─► artwork  ◄── driven by that visual DNA
   │      ├─ gpt-image-1        if OPENAI_API_KEY is set
   │      └─ procedural engine  otherwise, and on ANY OpenAI failure
   │
   └─► compositor (sharp)
          art + typography + palette swatches + watermark → 1024×1536 PNG

The design decision worth defending: the artwork is driven by the same read of you as the words. The model call that writes the reading also emits a visual DNA block — a motif (orbit, bloom, static, drift, spire, tide) plus energy, density, grain, and symmetry. Both artwork engines render from that DNA. So a frazzled desk genuinely gets a high-energy, high-density, low-symmetry static composition, and a quiet Sunday gets a calm drift. The picture isn't decoration behind the text; it's the same judgement, expressed differently.

Two engines, one contract

OpenAI is raced against a deadline, and every failure falls back to procedural. A card always ships. There is no path where a judge watching the demo sees an error because an image API had a bad minute. The response tells you which engine drew it via artwork_source.

Set OPENAI_API_KEY to turn on illustration; leave it unset for the free, instant, deterministic path. Everything below the art box — typography, swatches, watermark — is identical either way, so the two look like one product.

Running it

npm install
cp .env.example .env        # add ANTHROPIC_API_KEY
npm run demo                # 5 cards → out/, no payment layer, no OKX keys needed

To run the server with payments off (local iteration):

PAYMENTS_DISABLED=true npm run dev

To run the full paid flow against a deployment:

BUYER_PRIVATE_KEY=0x... TARGET=https://<your-deployment> npm run paid

Deploying & listing

Deploy before you register. The ASP's endpoint is written permanently on-chain and review takes ~24h — see REGISTRATION.md for the on-chain listing flow, the pre-validated field values, and the submission checklist.

Docker → Render. render.yaml is checked in.

git push        # autoDeploy is on

Set these as secrets in the Render dashboard (they are sync: false in render.yaml, so they never touch the repo): ANTHROPIC_API_KEY, OKX_API_KEY, OKX_SECRET_KEY, OKX_PASSPHRASE, PAY_TO. Then set PUBLIC_URL to the real Render URL.

Two things that will bite you:

• Fonts. sharp renders the card's typography through librsvg, which finds fonts via fontconfig. The Dockerfile installs fonts-dejavu-core and runs fc-cache. Without that step the card composites perfectly and every glyph is a blank box.
• Cold starts. Render's free tier sleeps and takes ~50s to wake. render.yaml uses starter for that reason — a judge hitting a cold endpoint sees a timeout, not a card.

Limits and failure behaviour

Every error is one JSON shape:

{ "error": { "code": "image_too_large", "message": "image is 5.7 MB; the limit is 4 MB",
             "hint": "Resize to under 4 MB and retry." } }

Codes: invalid_input · image_too_large · content_rejected · generation_failed · generation_timeout · payment_required · payment_invalid · rate_limited · internal_error.

Hostile input is rejected in-voice rather than with a stack trace. Asking it to leak its system prompt gets you:

"That looks like an attempt to hijack my instructions, so I can't read it. Tell me about your day instead."

Ordinary sadness, mess, and burnout are not rejected — they're read warmly. That's the point of the thing.

Layout

src/
  server.ts            express: MCP + REST + discovery, payment gating, errors
  mcp.ts               MCP server, generate_aura_card tool schema
  x402.ts              OKX x402 payment layer (facilitator, 402, settle, refund)
  config.ts            env, price, network constants
  pipeline/
    index.ts           orchestration + hard timeout
    reading.ts         the Claude call → reading + palette + visual DNA
    art.ts             procedural art engine (6 motifs, seeded)
    compose.ts         sharp compositor → the final card
  lib/
    validate.ts        input validation, image sniffing
    errors.ts          typed errors, timeout, retry
scripts/
  demo.ts              5 example calls
  paid-call.ts         the x402 buyer
  render-test.ts       offline render check

Built for the OKX.AI Genesis Hackathon. MIT.