Getting Started

Quickstart

Quickstart

This walkthrough creates a paid HTTP capability and calls it through the Lipafy gateway.

All examples use the Lipafy API base URL:

https://api.lipafy.xyz

1. Sign in

Open the dashboard and sign in with one of the supported login methods:

  • Google
  • EVM wallet sign-in

The dashboard session is used for account setup. Agents and scripts should use an API key or OAuth token.

2. Top up your wallet

In the dashboard, open Overview and choose Top up.

Lipafy starts an M-Pesa top-up through the configured payment provider. Complete the prompt on your phone, and the balance updates once the payment confirms.

3. Create an API key

Create an API key from the dashboard, or call the account API with a dashboard bearer token:

$curl -X POST https://api.lipafy.xyz/v1/accounts/me/api-keys \
>  -H "authorization: Bearer <dashboard-token>" \
>  -H "content-type: application/json" \
>  -d '{"name":"quickstart"}'

The response includes plaintext. Store it immediately; Lipafy only returns the full API key once.

4. Register a capability

A capability is a paid HTTP endpoint.

$curl -X POST https://api.lipafy.xyz/v1/capabilities \
>  -H "authorization: Bearer <dashboard-token>" \
>  -H "content-type: application/json" \
>  -d '{
>    "slug": "demo.echo",
>    "name": "Echo demo",
>    "description": "Echoes the request body back",
>    "provider_type": "passthrough",
>    "provider_config": {
>      "endpoint_url": "https://postman-echo.com/post",
>      "auth_type": "none",
>      "auth_value": ""
>    },
>    "price_amount": "100",
>    "price_currency": "KES",
>    "status": "active"
>  }'

This creates demo.echo, priced at 100 KES per request.

5. Call the capability

$curl -X POST https://api.lipafy.xyz/gateway/demo.echo/ \
>  -H "authorization: Bearer <lipafy-api-key>" \
>  -H "content-type: application/json" \
>  -d '{"hello":"world"}'

On a successful call, Lipafy:

  1. Resolves the capability and price.
  2. Checks the grant, wallet balance, and spending controls.
  3. Places a hold for the price.
  4. Forwards the request upstream.
  5. Settles the hold if the upstream call succeeds.
  6. Releases the hold if the upstream call fails.

Successful responses include payment status headers such as:

1X-Payment-Status: settled

6. Connect an MCP agent

For clients that support HTTP MCP, add:

1{
2  "mcpServers": {
3    "lipafy": {
4      "type": "http",
5      "url": "https://api.lipafy.xyz/mcp"
6    }
7  }
8}

If the client supports MCP OAuth discovery, it can start the Lipafy OAuth flow. If it does not, use the client’s bearer-token configuration.

Once connected, agents can read wallet/capability state and execute paid capabilities. Lipafy does not ask for confirmation on every ordinary in-policy payment; it pauses when balance, controls, approval rules, or mandate rules require it.

Next steps