Laravel MPP: монетизація API для AI-агентів через HTTP 402

Laravel MPP - це middleware, що реалізує Machine Payments Protocol (MPP) і дозволяє стягувати плату з AI-агентів за доступ до захищених маршрутів. При запиті без оплати сервер повертає HTTP-відповідь 402 Payment Required з підписаним викликом. Агент, здатний платити, виконує виклик через підтримуваний платіжний метод і повторює запит.

Основні можливості

Пакет пропонує низку функцій для гнучкої монетизації API:

• Два платіжні методи - Stripe Shared Payment Tokens (SPTs) та Tempo pathUSD
• Поіменна або лічильникова тарифікація - оплата за кожен запит або одноразовий платіж з багаторазовим доступом
• HMAC-підписані виклики - агенти отримують підписаний виклик 402 для оплати та повторної спроби
• Лічильникові сесії - атомарні балансові рахунки з перевіркою області дії, що зберігаються в кеші або базі даних
• Передумови - іменовані перевірки, які виконуються перед платіжним шлюзом для раннього відхилення непридатних запитів

Захист маршруту

Для встановлення платного доступу достатньо додати middleware mpp до маршруту із зазначенням ціни та валюти. Запит без оплати отримає відповідь 402 з викликом:

Route::get('/resource', MyPaidResource::class)
    ->middleware('mpp:0.50,USD');

Також можна оголосити ціноутворення через атрибут RequiresPayment на методі контролера і дозволити middleware його зчитувати. Для автоматичного застосування можна ввімкнути MPP_ATTRIBUTES_ENABLED=true:

#[RequiresPayment(amount: '5.00', currency: 'USD', grants: 10)]
public function report()
{
    // ...
}
Route::get('/report', ReportController::class)->middleware('mpp');

Лічильникові сесії

Коли платіж визначає grants більше одиниці, один платіж покриває кілька звернень. Успішна відповідь включає заголовок Payment-Session із залишковим балансом та областю дії:

Payment-Session: id="sess_...", remaining="9", scope="report.basic", expiresAt="..."

Агент відтворює ідентифікатор сесії в наступних запитах замість повторної оплати:

curl -si https://your-host/report \
  -H 'Authorization: Payment method="stripe", session="sess_..."'

Сесії зберігаються в кеші за замовчуванням або в базі даних для збереження стану:

MPP_SESSION_DRIVER=cache      # За замовчуванням
MPP_SESSION_DRIVER=database   # Постійне зберігання; запустіть опубліковані міграції
MPP_SESSION_CACHE_STORE=redis # Опціональне власне сховище кешу

Передумови

Передумови - це іменовані перевірки, які виконуються перед платіжним шлюзом. Вони дозволяють відхилити непридатний запит до того, як агента буде запропоновано платити. Їх реєструють у config/mpp.php і прикріплюють до окремих маршрутів або виконують глобально:

// config/mpp.php
'preconditions' => [
    'checks' => [
        'postexists' => [\App\Mpp\Checks\PostExists::class, 'check'],
    ],
    'global' => ['usernotblocked'],
],

Перевірка повертає null для успішного проходження або Response для переривання запиту:

class PostExists
{
    public function check(Request $request, PaymentSpec $spec): ?Response
    {
        return Post::find($request->route('post'))
            ? null
            : response()->json(['error' => 'No such post.'], 404);
    }
}

Route::get('/posts/{post}', ShowPost::class)
    ->middleware('mpp:1.00,USD,preconditions=postexists');

Платіжні методи

Пакет постачається з двома платіжними методами. Stripe використовує Shared Payment Tokens (SPTs) і налаштовується через ключі Stripe та попередню версію API:

STRIPE_SECRET_KEY=sk_test_...
STRIPE_NETWORK_ID=profile_...
STRIPE_API_VERSION=2026-05-27.preview

Tempo здійснює розрахунки в pathUSD он-чейн. Його можна вибрати для окремого маршруту через параметр method=tempo:

Route::get('/paid', fn () => response()->json(['data' => 'paid']))
    ->middleware('mpp:0.01,USD,method=tempo,scope=paid');

Можна приймати кілька платіжних методів на одному маршруті через methods=stripe|acme, а також зареєструвати власний метод, реалізувавши інтерфейс Verifier. При успішному платежі відповідь містить заголовок Payment-Receipt з ідентифікацією методу, суми та посилання.

Встановлення

Встановлення виконується через Composer з подальшою публікацією конфігурації:

composer require square1/laravel-mpp
php artisan vendor:publish --tag=mpp-config

Для використання лічильникових сесій з драйвером бази даних потрібно опублікувати та виконати міграції:

php artisan vendor:publish --tag=mpp-migrations
php artisan migrate

Важливо зауважити, що MPP та Stripe SPT API все ще перебувають у попередньому перегляді і можуть змінюватися. Остання версія v1.1.0 розповсюджується під ліцензією MIT та доступна на GitHub.