Guides

Monetize an API

You operate an HTTP API. Today it has a key-based or open developer model and you bill humans through invoices, dashboards, or PAYG cards. You want agents to be able to call it AND for the money to land in your M-Pesa account, on a schedule, without you running billing infra.

This guide takes you end-to-end.

1. Sign in as an API provider

Go to https://app.lipafy.xyz/login and sign in via Google or wallet. You now have an account; that account will own your capability listings.

2. Register your endpoint as a capability

From the dashboard, Capabilities → Register new. Or via API:

$curl -X POST https://api.lipafy.xyz/v1/capabilities \
>  -H "authorization: Bearer <jwt>" \
>  -H "content-type: application/json" \
>  -d '{
>    "slug": "kyc.your-brand.verify-id",
>    "name": "Verify Kenyan ID",
>    "description": "OCR + verification against IPRS. Returns name, ID number, photo match score.",
>    "provider_type": "passthrough",
>    "provider_config": {
>      "endpoint_url": "https://api.your-service.com/v1/verify",
>      "auth_type": "bearer",
>      "auth_value": "<your-upstream-api-key>"
>    },
>    "price_amount": "150",
>    "price_currency": "KES",
>    "status": "active"
>  }'

The auth_value is encrypted at rest with AES-256-GCM. Lipafy injects it on every forwarded request — the calling agent never sees your upstream key.

3. Test it

$# As an agent caller with funds:
$curl -X POST https://api.lipafy.xyz/gateway/kyc.your-brand.verify-id/ \
>  -H "authorization: Bearer lip_live_<some-test-key>" \
>  -H "content-type: application/json" \
>  -d '{"id_number":"...","selfie":"..."}'

Trace the charge in your dashboard’s recent transactions. For detailed per-capability volume and spend, call GET /v1/usage/breakdown.

4. Coordinate settlement

Lipafy collects successful capability revenue on the platform ledger, then settles to providers in batches. Settlement setup is operator-assisted today: keep your account phone number current, agree the revenue share during onboarding, and use the settlements API to inspect payout records once they exist.

5. Make your capability discoverable

By default, a capability you register through the dashboard is account-private. To make it discoverable by other agents, submit it through the public capability application flow:

  • Dashboard: open /capabilities/apply
  • API: POST /v1/capability-applications
  • After admin approval, the capability appears in GET /v1/capabilities and lipafy.list_capabilities

The agent-facing metadata (description, pricing, sample request) influences whether agents pick your capability over a competitor’s. Write it like ad copy for an LLM reader.

6. Iterate on pricing

Capabilities support a single flat price today. If you need different prices for different operations, register separate slugs for those operations.

What you don’t have to do

  • No PCI compliance — Lipafy handles wallet semantics, not card data
  • No billing system — no invoices, no Stripe Connect, no chasing payments
  • No KYC on every customer — Lipafy KYCs the wallet owner once; you bill Lipafy, not the end user
  • No dispute handling — Lipafy handles refunds against capability_requests; if your upstream returns a failure, the wallet hold is released automatically and you owe the customer nothing

Quality signals that drive volume

Agents pick capabilities by reading metadata. Strong signals:

  • Concrete description: “Verify a Kenyan national ID via IPRS in 800ms, returns confidence score 0–1” beats “ID verification”
  • Spend-aware notes in the description: “Use limit=10 for batch lookups; prefer GET when you only need existence checks”
  • Honest pricing that doesn’t shock the agent mid-flow
  • High success rate — Lipafy releases holds on upstream failures, so unreliable upstreams cost YOU lost revenue (the user wasn’t charged)

When you should NOT use Lipafy

  • Your API is consumed by humans on a subscription. Stick with monthly invoicing.
  • You need a non-KES settlement rail. Lipafy is M-Pesa today.
  • You charge per-second usage (streaming, video). Lipafy supports flat per-call pricing today.