Tiers

Set a tier: start, renew, or upgrade its lease

Unified tier endpoint. The allowance settles first: send the ordinary SIGN-IN-WITH-X identity and, when the organization's allowance covers the price, the purchase settles from it with no 402, no payment header, and no wallet funds (response paid_with: allowance). An allowance that falls short gets a 402 whose allowance block names the allowance, price, and shortfall, with redeem-voucher and top-up next actions beside the x402/MPP challenge. Auto-detects start, renew, or upgrade (the action field; a start answers 201); downgrading during an active lease is rejected. Existing x402 behavior remains compatible. The explicit MPP Lightning charge path requires Run402-Payment-Profile: run402-mpp-lightning-charge-draft00-safety-v1, Accept-Payment selecting lightning/charge, exactly one supported principal credential, and one stable Idempotency-Key. It returns one fresh fixed-amount Bitcoin-mainnet BOLT11 invoice per emitted challenge, retains quote metadata, and requires exact-request reconciliation after possible dispatch.

post/tiers/v1/{tier}

Request

  • Base URL: https://api.run402.com
  • URL: https://api.run402.com/tiers/v1/{tier}
  • Auth: one of:
    • API key in header X-PAYMENT
    • API key in header SIGN-IN-WITH-X and API key in header Authorization

Path parameters

tier'prototype' | 'hobby' | 'team' required

Headers

Run402-Payment-Profile'run402-mpp-lightning-charge-draft00-safety-v1'

Exact opt-in for the draft-pinned MPP Lightning charge profile. Omit for existing payment behavior.

Accept-Paymentstring

Ordered payment capabilities. Lightning is selected only when it is the highest-quality supported match.

Idempotency-Keystring

Required for the explicit Lightning profile. Exact retries preserve the retained payment intent and committed tier result. On every other rail a replay within 24h answers without a second payment, and only to the same caller (the request's verified SIGN-IN-WITH-X wallet, or its exact Authorization: Bearer credential) sending the same query and JSON body; the same key with a different request answers 422 IDEMPOTENCY_KEY_REUSED.

Response

Tier renewed or upgraded — OR, for prototype on an organization that already holds perpetual prototype, a short-circuit before the paywall (kygit-handoff D4/D5): no 402 challenge is answered, no payment is verified or settled, no ledger row is written. Paying twice is not charged twice.

OR
OR

Example response

{
  "wallet": "0x..."
}

Changes

No recorded changes to this operation across all 1 revision of this API.