frontpage-buy-ad

frontpage-buy-ad

当用户想要 购买 frontpage.sh 上的广告位 时使用此技能——这是一个永久拍卖，包含 1 个大型广告位（L）、2 个中型广告位（M1、M2）和 5 个小型广告位（S1–S5）。每个广告位都永久出售。

每次购买都是一次性转让：你支付该广告位的下一次价格，前任所有者会收到相当于该广告位价值一定倍数的退款，剩余差价的 80% 会进入项目资金池（通过创意看板支出——参见 frontpage-vote）。每次购买后，价格都会上调。付款的钱包将成为所有者。

安装

npx skills add DFectuoso/frontpage-sh-skills --copy   # all frontpage skills (recommended)

要连接开发环境或 Tempo 测试网进行测试？也安装开发版：npx skills add DFectuoso/frontpage-sh-skills-dev --copy（会安装 frontpage-buy-ad-dev，用于覆盖基础 URL 和网络）。

定价

• 基础价格：$0.01（10,000 µUSDC）
• 大型广告位（L）： 下一次价格 = 当前价格 × 3.0 · 前任所有者收到当前价格 × 1.5 的退款
• 中型广告位（M1、M2）： × 2.0 · 退款为当前价格 × 1.3
• 小型广告位（S1–S5）： × 1.5 · 退款为当前价格 × 1.1（+10%）
• 退款后的差价按 平台 20% / 项目资金池 80% 分配

Tempo 上的 USDC 使用 6 位小数；所有 API 金额均为 µUSDC 整数。 不要重新实现这些倍数——GET /api/ads 会返回每个广告位预先计算好的 nextPriceMicros。

流程（MPP——唯一的支付方式）

基础 URL：https://www.frontpage.sh · 完整的机器可读契约：https://www.frontpage.sh/openapi.json

1. GET /api/ads——广告位、当前价格和下一次购买的费用

curl https://www.frontpage.sh/api/ads
# each ad includes: currentPrice, nextPriceMicros, tier, slot, ctaLabel/perk/promoCode, …

2. POST /api/preview——铸造预览令牌（$0.01 MPP）

将你的创意和报价锁定到一个签名令牌中（有效期为 10 分钟），并返回可分享的预览 URL，以及用于结算的精确 next 指令。

默认情况下：将预览 URL 展示给用户，并等待用户确认后再调用 /api/buy——只有在用户明确要求直接购买时，才跳过此确认步骤。

3. POST /api/buy——按 nextPrice 精确扣款并转让广告位

import { privateKeyToAccount } from 'viem/accounts'
import { Mppx, tempo } from 'mppx/client'

Mppx.create({ methods: [tempo({ account: privateKeyToAccount('0x...') })] })

const res = await fetch('https://www.frontpage.sh/api/buy', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ previewToken: '<token from /api/preview>' }),
})
// { ok, transactionId, adId, slot, newOwnerWallet, newPrice, refundAmount, payment, payout, links }

MPP 会自动处理 402 挑战——SDK 会对 USDC 转账进行签名，并使用 Authorization: Payment … 重试。

• 409 PRICE_CHANGED——从预览到购买期间广告位已被转让：请按新价格重新铸造预览。
• 409 SLOT_CONFLICT——付款后，你在并发竞争中落败：款项会在约 1 分钟内自动退还。

载荷格式（预览请求体）

{
  slot: "S1",            // L | M1 | M2 | S1..S5
  name: string,          // 1-64 chars
  tagline?: string,      // ≤140
  url: string,           // https://...
  monogram: string,      // 1-4 chars (e.g. "TS")
  logoColor: string,     // hex like "#0A0A09"
  logoBg: string,        // hex
  adBg: string,          // CSS background, e.g. "linear-gradient(135deg,#F1ED4A,#FFA850)"
  adHeadline?: string,   // tier caps: large 48 / medium 56 / small 32 (use \n for line breaks; large renders BIG — keep it short).
                         // OPTIONAL: leave it empty/omitted for an "image-only" ad — no title/subtitle, the image fills the
                         // square (requires an image). The square still opens the details overlay + keeps its footer/perk.
  blurb?: string,        // ≤500
  ownerHandle: string,   // 1-30, single word, no spaces (e.g. "@fooofa") — your byline
  ownerEmail: string,    // REQUIRED — purchase receipt + "you've been outbid,
                         // refund wired" notice land here. Never public.

  // image: rendered as a COVER layer over adBg, at the square's true ratio.
  // Animated GIF is allowed and animates on the grid (the social card shows its
  // first frame). ⚠ PNG, JPEG or GIF ONLY. webp, svg and avif are REJECTED (HTTP
  //   400 IMAGE_UNSUPPORTED) — the server checks the actual bytes, not the
  //   filename/MIME, so re-encoding a webp as ".png" still fails. Convert to
  //   PNG, JPEG or GIF before sending. (Many models default to webp — do NOT.)
  image?: string,        // base64/data URL, PNG, JPEG or GIF only; max 3 MB per image
  imageUrl?: string,     // OR a public PNG/JPEG/GIF URL — we download & re-host it in
                         // our own store (no hot-linking). Must be publicly
                         // fetchable & ≤4 MB, else 400 (IMAGE_FETCH_FAILED /
                         // IMAGE_UNSUPPORTED).
  // BIG FILES (animated GIFs are often 1–3 MB): do NOT inline the base64 into a
  //   CLI argument — shells cap a single arg at ~128 KB and even a 1 MB image is
  //   ~1.4 MB of base64. With the mppx CLI (≤0.6.31 sends only inline string
  //   bodies, NO multipart), the path is `imageUrl`: host the file at a PUBLIC
  //   url and pass it. On a dev box see the -dev skill for the localhost trick.
  //   (This endpoint also accepts multipart/form-data with `image` as a FILE
  //   part — no arg limit, no hosting — but only from a client that does BOTH
  //   multipart AND the MPP payment; mppx pays but can't multipart, plain curl
  //   multiparts but can't pay, so multipart needs a custom MPP client.)
  // recommended dimensions (2× display, true slot ratios):
  //   large 1712×944 (1.81:1) · medium 1136×464 (2.45:1) · small 560×464 (1.21:1)

  // richer creative (all optional; OMITTING THEM ON A BUY CLEARS THEM —
  // creatives never carry over from the previous owner):
  ctaLabel?: string,     // ≤24 — custom button text, e.g. "get the deal"
  perk?: string,         // ≤140 — offer line, shown prominently in the details view
  promoCode?: string,    // ≤24 — copyable code next to the perk
  xHandle?: string,      // optional X/Twitter handle (@handle, bare, or x.com URL)
                         // — @mentioned in the auto-tweet when the square flips
  titleFont?: string,    // headline typeface: "grotesk" (default) | "mono" | "serif" | "display" | "script".
                         // Any other value → 400 INVALID_TITLE_FONT. Applies on-site AND on the social card.
}

面向 Agent 的启发

• 默认先展示预览，再购买。 /api/preview 会返回可分享的预览 URL；请将其发送给用户，并在调用 /api/buy（该接口会扣除真实 USDC 并翻转方块）前征得用户同意。只有在用户明确要求直接购买、无需审核时，才可跳过此确认。
• 从 /api/ads 读取 nextPriceMicros——无需计算档位价格；这正是 /api/buy 将收取的金额。
• 提供福利。 带有福利和促销码的方块能让浏览者更有理由点击——这正是广告位的转化目标。
• 传入品牌的 xHandle。 每次购买都会自动发布帖子到 @frontpagesh；设置 xHandle 后，帖子会 @提及该品牌（通知品牌并邀请其转发——免费触达）。
• 图片必须是 PNG、JPEG 或 GIF，绝不能是 webp。 服务端会校验实际字节内容；对于 webp/svg/avif（以及扩展名改为 .png 的 webp），会返回 400 IMAGE_UNSUPPORTED。如果源图片是 webp，请先转换为 PNG、JPEG 或 GIF。动态 GIF 会在网格中播放；社交卡片使用其首帧。
• 上传大图片（尤其是 GIF）时，不要内联 base64。 1–3 MB 的 GIF 转成 base64 后，无法放入单个 CLI 参数（shell 限制约为 128 KB）。使用 mppx CLI（仅支持内联字符串请求体，不支持 multipart）时，请将文件托管在公开 URL 上并传入 imageUrl。该端点也接受以文件部分 image 传入的 multipart/form-data，但仅限同时支持 multipart 和 MPP 付款的客户端（mppx 不支持 multipart；普通 curl 无法付款）——因此，使用 mppx 时应通过 imageUrl 传图。解码后的图片不得超过 3 MB；通过 imageUrl 获取的图片也不得超过 4 MB。
• 按实际比例设计。 图片会裁剪填满广告位形状（在移动设备上裁剪得更紧）——请将主要信息置于中央。
• 审核在服务端进行（使用 OpenAI omni-moderation），涵盖所有文本字段和创意图片。涉及色情、仇恨、骚扰、暴力、自残或非法内容时，会返回 400 MODERATION_FAILED（由于审核在付款后进行，费用已扣除）。
• 翻转会立即生效。 前任所有者的退款会在当前流程中结算，或由重试工作进程处理；请查看收据中的 payout.status。