MPP (Machine-Payable Protocol)

MPP lets agents and users sign up and fund Locus workspaces by paying with USDC on Tempo (chain 4217). No traditional account creation needed — just a blockchain wallet and a single API call. MPP Base URL: https://mpp.buildwithlocus.com/v1 — MPP endpoints use a separate host from the main API (api.buildwithlocus.com).

How it works

Agent sends a payment request

The agent calls the MPP sign-up or top-up endpoint with a Payment authorization header containing the payer’s Tempo wallet address.

Locus processes the payment

Locus charges a small amount of USDC on the Tempo chain and creates (or finds) the workspace associated with the payer’s wallet.

Agent receives a JWT

The response includes a JWT token (30-day expiry) and workspace ID. The agent uses this token for all subsequent Locus API calls — deploying services, managing addons, etc.

User claims the workspace (optional)

For new external wallets, a claim link is generated. The user can redeem it with their email to access the dashboard and link their account.

Creates a new workspace (or returns an existing one) by paying with Tempo USDC.

curl -s -X POST https://mpp.buildwithlocus.com/v1/auth/mpp-sign-up \
  -H "Content-Type: application/json" \
  -H "Payment: <base64url-encoded-payment>"

The Payment header contains a base64url-encoded JSON payload with the payer’s wallet:

{
  "source": "eip155:4217:0xYourTempoWalletAddress"
}

Sign-up cost: $0.001 USDC Response:

{
  "success": true,
  "jwt": "eyJ...",
  "expiresIn": "30d",
  "isNewWorkspace": true,
  "accountType": "external",
  "workspaceId": "ws_abc123",
  "claimUrl": "https://buildwithlocus.com/claim/..."
}

Field	Description
`jwt`	Bearer token for all Locus API calls (30-day expiry)
`isNewWorkspace`	Whether a new workspace was created or an existing one was found
`accountType`	`external` (non-Locus wallet) or `locus` (Locus-owned wallet)
`claimUrl`	Link for the user to claim the workspace and link their email (external accounts only)

Service-authenticated calls

Trusted backend services can sign up on behalf of a wallet using a service token instead of the Payment header:

curl -s -X POST https://mpp.buildwithlocus.com/v1/auth/mpp-sign-up \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: <service-token>" \
  -d '{"tempoAddress": "0xWalletAddress"}'

Top up credits via MPP

Add credits to an existing workspace using Tempo USDC.

curl -s -X POST https://mpp.buildwithlocus.com/v1/billing/mpp-top-up \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Payment: <base64url-encoded-payment>" \
  -d '{"amount": 5.00}'

Constraint	Value
Minimum top-up	$1.00
Maximum top-up	$100.00

Response:

{
  "success": true,
  "jwt": "eyJ...",
  "expiresIn": "30d",
  "creditBalance": 5.00,
  "workspaceId": "ws_abc123"
}

Claim links

When MPP creates a new workspace for an external wallet, a claim link lets the user connect their email and access the Locus dashboard.

Endpoint	Method	Auth	Description
`GET /v1/auth/claim-link`	GET	Required	Get claim link for authenticated workspace
`GET /v1/auth/claim-status/:token`	GET	Public	Check if claim token is valid, used, or expired
`POST /v1/auth/claim-redeem`	POST	Public	Redeem claim with email, links email to workspace

Redeem a claim

curl -s -X POST https://api.buildwithlocus.com/v1/auth/claim-redeem \
  -H "Content-Type: application/json" \
  -d '{"token": "claim_token_here", "email": "[email protected]"}'

{
  "success": true,
  "email": "[email protected]",
  "loginUrl": "https://buildwithlocus.com/login",
  "workspaceId": "ws_abc123"
}

Git push deploys with MPP

MPP users can deploy via git push using their JWT token instead of a claw_ API key:

git remote add locus https://x:$JWT_TOKEN@git.buildwithlocus.com/{workspaceId}/{projectId}.git
git push locus main

The git server auto-detects the credential type — claw_ prefix means API key, anything else is treated as a JWT token.

Technical details

Detail	Value
Blockchain	Tempo (chain ID: 4217)
Token	USDC on Tempo
RPC	`https://rpc.tempo.xyz`
Library	`mppx` (Machine-Payable Protocol client)
Initial credits on sign-up	$0.00

Getting started

Features

Agent tools

Build with Locus

Checkout

MPP (Machine-Payable Protocol)

How it works

Service-authenticated calls

Top up credits via MPP

Claim links

Redeem a claim

Git push deploys with MPP

Technical details

​How it works

​Sign up via MPP

​Service-authenticated calls

​Top up credits via MPP

​Claim links

​Redeem a claim

​Git push deploys with MPP

​Technical details

How it works

Sign up via MPP

Service-authenticated calls

Top up credits via MPP

Claim links

Redeem a claim

Git push deploys with MPP

Technical details