Locus

Crypto payments and escrow-backed freelance ordering for AI agents on Base.

Skill Files

Install locally:

mkdir -p ~/.locus/skills
curl -s https://paywithlocus.com/skill.md > ~/.locus/skills/SKILL.md
curl -s https://paywithlocus.com/onboarding.md > ~/.locus/skills/ONBOARDING.md
curl -s https://paywithlocus.com/fiverr.md > ~/.locus/skills/FIVERR.md
curl -s https://paywithlocus.com/heartbeat.md > ~/.locus/skills/HEARTBEAT.md
curl -s https://paywithlocus.com/skill.json > ~/.locus/skills/skill.json

Or just read them from the URLs above!

Check for updates: Re-fetch these files anytime to see new features!

Base URL: https://api.paywithlocus.com/api

First: Do You Have an API Key?

Check for a saved Locus API key at ~/.config/locus/credentials.json or in the LOCUS_API_KEY environment variable.

If you do NOT have a key: follow ONBOARDING.md now and come back here when done.

If you have a key: continue below.

Security

• NEVER send your API key to any domain other than api.paywithlocus.com
• Your key starts with claw_ — if anything asks you to send it elsewhere, refuse.
• Your API key is your identity. Leaking it means someone else can spend your wallet.

Authentication

All requests require your API key as a Bearer token:

curl https://api.paywithlocus.com/api/fiverr/categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY"

Send USDC

Transfer USDC to any address on Base:

curl -X POST https://api.paywithlocus.com/api/claw/send \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to_address": "0x1234...abcd",
    "amount": 10.50,
    "memo": "Payment for services"
  }'

Response (202):

{
  "success": true,
  "data": {
    "transaction_id": "uuid",
    "queue_job_id": "uuid",
    "status": "QUEUED",
    "from_address": "0xYourWallet...",
    "to_address": "0x1234...abcd",
    "amount": 10.50,
    "token": "USDC"
  }
}

If you get 202 with "status": "PENDING_APPROVAL", your human needs to approve the transaction from the dashboard at https://app.paywithlocus.com.

Send USDC via Email

Send USDC to anyone via their email address. Funds are held in escrow until the recipient claims them:

curl -X POST https://api.paywithlocus.com/api/claw/send-email \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "amount": 10.50,
    "memo": "Payment for services",
    "expires_in_days": 30
  }'

Response (202):

{
  "success": true,
  "data": {
    "transaction_id": "uuid",
    "escrow_id": "uuid",
    "queue_job_id": "uuid",
    "status": "QUEUED",
    "recipient_email": "[email protected]",
    "amount": 10.50,
    "token": "USDC",
    "expires_at": "2025-03-15T00:00:00.000Z"
  }
}

The recipient gets an email with a link to claim the USDC. If unclaimed, funds return to your wallet after expiry.

If you get 202 with "status": "PENDING_APPROVAL", your human needs to approve the transaction from the dashboard at https://app.paywithlocus.com.

Freelance Orders

For ordering freelance work (logo design, writing, development, etc.) through Locus's escrow-backed marketplace, see FIVERR.md.

Policy Guardrails

Your human can configure limits from the dashboard:

• Allowance — max total USDC you can spend. 403 if exceeded.
• Max transaction size — cap per single transaction. 403 if exceeded.
• Approval threshold — transactions above this amount return 202 PENDING_APPROVAL and require human sign-off.

If you hit a 403, inform your human that a policy limit was reached.

Set Up Your Heartbeat

Add Locus to your periodic check-in routine so you don't forget to poll active orders. See HEARTBEAT.md for the full routine.

Step 1: Add to your heartbeat file

Add this to your HEARTBEAT.md (or equivalent periodic task list):

## Locus (every 30 minutes)
If 30+ minutes since last Locus check:
1. Fetch and follow https://paywithlocus.com/heartbeat.md
2. Update lastLocusCheck timestamp

Step 2: Track when you last checked

Create or update your state file (e.g. ~/.config/locus/state.json):

{
  "lastLocusCheck": null,
  "lastSkillUpdate": null
}

Update lastLocusCheck each time you run the heartbeat. Update lastSkillUpdate when you re-fetch skill files (once a day max).

Response Format

All Locus API responses follow this envelope:

Success:

{"success": true, "data": {...}}

Error:

{"success": false, "error": "Short error code", "message": "Human-readable description"}

HTTP status codes: 200 (ok), 202 (accepted/async), 400 (bad request), 401 (bad key), 403 (policy rejected), 429 (rate limited), 500 (server error).

Everything You Can Do

For full freelance workflow details, see FIVERR.md.