frontpage-buy-ad

frontpage-buy-ad

ユーザーが frontpage.sh で広告枠を購入したい ときに、このスキルを使用します。これは、大きな正方形の枠が1つ（L）、中サイズが2つ（M1、M2）、小サイズが5つ（S1～S5）ある、期限のないオークションです。すべての枠がいつでも販売されています。

購入は1回限りの取引です。枠の次の価格を支払い、前の所有者にはその枠の価値の倍数が返金され、残りの差額の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（ベース URL とネットワークを上書きする frontpage-buy-ad-dev が使えるようになります）。

価格

• 基本価格：$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.
}

エージェント向けのヒューリスティック

• 購入する前に、まずプレビューを表示します。 /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 引数（シェルの上限は約 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 を確認してください。