Skip to content

moltycash: thin out skill — link to per-user docs #490

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
0xsnackbaker wants to merge 1 commit into
base: main
Choose a base branch
from
Open

moltycash: thin out skill — link to per-user docs #490

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
196 changes: 70 additions & 126 deletions moltycash/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
name: moltycash
description: >
USDC payments from AI agents to humans via molty.cash. Use when the agent wants to
tip someone, hire a person for a task, or create a pay-per-task gig. Payments settle
on-chain via x402 on Base using Bankr wallet for signing.
tip someone, hire a person for a specific published product, or post a pay-per-task
gig. Payments settle on-chain via x402 on Base using the bankr wallet for signing.
Do NOT use for token swaps, DeFi, or non-USDC payments.
metadata:
{
Expand All @@ -18,45 +18,58 @@ metadata:

# MoltyCash — Agent-to-Human Payments with USDC

[molty.cash](https://molty.cash) lets AI agents pay humans with USDC. Tip someone, hire them for a task, or post a gig for multiple people to earn from — all settled on-chain via [x402](https://x402.org) on Base.
[molty.cash](https://molty.cash) lets AI agents pay humans with USDC. Three actions: **tip**, **hire**, and **gig.create** — all signed by the bankr wallet via [x402](https://x402.org) on Base.

This skill covers three actions: **tip**, **hire**, and **gig create**. All use the Bankr CLI (`bankr x402 call`) for x402 payment signing.
This skill covers **bankr's transport** for moltycash endpoints. For payment rules, fees, services, tiers, and rewards, this doc links to the live molty.cash docs so it doesn't go stale.

### `--max-payment`
---

## Prerequisites

`bankr x402 call` defaults to a $1 max payment. The total charged is amount + platform fee (see Fees below), so pass `--max-payment` when the total exceeds $1:
- Bankr CLI installed + `bankr whoami` confirms a session
- Funded bankr wallet (Base USDC)
- *Optional:* `MOLTY_IDENTITY_TOKEN` — without it, molty auto-creates an anonymous agent profile for the sender. Get a token from the profile dropdown at [molty.cash](https://molty.cash) → "Identity Token", then `export MOLTY_IDENTITY_TOKEN="..."`.

---

## Transport pattern

```bash
# Example: hire for $1.00 → fee is 3% ($0.03) → total $1.03 → needs --max-payment 1.03
bankr x402 call <url> --max-payment 1.03 ...
bankr x402 call <url> --method POST --max-payment <usdc> --body '<json>'
```

Max allowed value is `10`.
- `--max-payment` must be ≥ `amount + fee` (or `price × quantity × 1.03` for gigs). Default $1; **bankr's hard cap is $10 per call**.
- Bankr signs `x402` on **Base** (`eip155:8453`) only. Molty itself supports more chains via other wallets — bankr is the binding constraint here.
- Molty hire/gig caps go to $50, but bankr's $10 `--max-payment` ceiling is what you'll hit first.

---

## Prerequisites
## Fees

1. Bankr CLI installed and logged in (`bankr whoami` to verify)
2. Funded Bankr wallet (Base USDC)
3. `MOLTY_IDENTITY_TOKEN` — required for **tip**, **hire**, and **gig create**
| Amount | Platform fee |
|---|---|
| < $1 | **1¢** flat |
| ≥ $1 | **3%** |

### Getting an Identity Token
The fee is added on top of `amount` — the payer authorises `amount + fee` total. Tier-based rebate available via rewards (see below).

1. Login to [molty.cash](https://molty.cash) with your X account
2. Open the profile dropdown and click "Identity Token"
3. Generate your token and copy it
4. `export MOLTY_IDENTITY_TOKEN="your_token"`
---

## Refunds (escrow)

- **Hire**: payment is escrowed. If the recipient doesn't claim the assignment within 4h, funds auto-refund to the payer.
- **Gig**: each unfilled slot auto-refunds after the 24h gig deadline. Expired assignments (no proof in 4h) free the slot for someone else.
- **Reviews**: unreviewed submissions auto-approve after 4h.

---

## Tip

Send a USDC tip to any molty.cash user.
URL: `POST https://api.molty.cash/{handle}/a2a`

```bash
bankr x402 call https://api.molty.cash/0xmesuthere/a2a \
--method POST \
--method POST --max-payment 0.15 \
--body '{
"jsonrpc": "2.0",
"id": 1,
Expand All @@ -68,170 +81,101 @@ bankr x402 call https://api.molty.cash/0xmesuthere/a2a \
}'
```

### Tip any user
Per-user tip details, recipient bio, and any handle-specific minimums:
[`https://molty.cash/{handle}/TIP.md`](https://molty.cash/0xmesuthere/TIP.md)

Replace `0xmesuthere` with any X handle:

```bash
bankr x402 call https://api.molty.cash/{username}/a2a \
--method POST \
--body '{
"jsonrpc": "2.0",
"id": 1,
"method": "tip",
"params": {
"amount": 0.50,
"identity_token": "'$MOLTY_IDENTITY_TOKEN'"
}
}'
```
> **Recipient discovery.** If that URL redirects to a profile that says "no Molty Profile yet" (or doesn't render as `text/markdown`), the handle isn't on molty yet. Send the tip anyway — your payment **creates** the recipient's profile, claimable later via X login.

---

## Hire

Hire a specific person to complete a task. Payment is escrowed via x402. The person is auto-assigned and has 4 hours to submit proof.
URL: `POST https://api.molty.cash/{handle}/a2a`

```bash
bankr x402 call https://api.molty.cash/0xmesuthere/a2a \
--method POST \
--max-payment 1.03 \
--body '{
"jsonrpc": "2.0",
"id": 1,
"method": "hire",
"params": {
"amount": 1.00,
"description": "explain how bankr and MoltyCash integration works in a post",
"identity_token": "'$MOLTY_IDENTITY_TOKEN'"
}
}'
```

### Hire any user

Replace `0xmesuthere` with any X handle:
`service` + `product_type` are required — every hire targets a real published product on the recipient's profile. Open-format hires are no longer supported.

```bash
bankr x402 call https://api.molty.cash/{username}/a2a \
--method POST \
--max-payment 1.03 \
bankr x402 call https://api.molty.cash/0xmesuthere/a2a \
--method POST --max-payment 1.05 \
--body '{
"jsonrpc": "2.0",
"id": 1,
"method": "hire",
"params": {
"amount": 1.00,
"description": "Your task description here",
"description": "Write an X article on agent payments",
"service": "x_paid_promotion",
"product_type": "x_article",
"identity_token": "'$MOLTY_IDENTITY_TOKEN'"
}
}'
```

### Hire Rules
The recipient's published products + the `service` and `product_type` values you must pass:
[`https://molty.cash/{handle}/HIRE.md`](https://molty.cash/0xmesuthere/HIRE.md)

| Rule | Detail |
|------|--------|
| Max amount | 10 USDC |
| Description | Max 500 characters |
| Assignment TTL | 4 hours to submit proof |
| Review deadline | 4h auto-approve if not reviewed |
| Hold period | 2h after approval before payment release |
> **Recipient discovery.** If `HIRE.md` redirects to a "no Molty Profile yet" page, or shows the user has no published products, hire is **unavailable** until they publish one. There is no fallback — the call will fail with `INVALID_PARAMS`. For a casual payment with no product, use **tip** instead.

---

## Gig Create
## Gig.create

Create a gig that multiple people can earn from. You define the task, set a price per completion, and review submissions.
URL: `POST https://api.molty.cash/a2a` (global endpoint — no `{handle}` because anyone eligible can pick the gig)

```bash
bankr x402 call https://api.molty.cash/a2a \
--method POST \
--method POST --max-payment 1.00 \
--body '{
"jsonrpc": "2.0",
"id": 1,
"method": "gig.create",
"params": {
"identity_token": "'$MOLTY_IDENTITY_TOKEN'",
"description": "Share a post about bankr and mention @moltycash on X",
"description": "Post a short thread mentioning @moltycash on X",
"price": 0.30,
"quantity": 3
"quantity": 3,
"service": "x_paid_promotion",
"product_type": "x_thread",
"identity_token": "'$MOLTY_IDENTITY_TOKEN'"
}
}'
```

### With eligibility criteria
### Verified humans only

Set `verified_humans_only: true` to restrict the gig to earners who've completed [World ID](https://world.org/world-id) verification — useful for AI-resistant tasks like in-person visits, hand-written reviews, or anti-Sybil campaigns.

```bash
bankr x402 call https://api.molty.cash/a2a \
--method POST \
--method POST --max-payment 1.05 \
--body '{
"jsonrpc": "2.0",
"id": 1,
"method": "gig.create",
"params": {
"identity_token": "'$MOLTY_IDENTITY_TOKEN'",
"description": "Share a post about bankr and mention @moltycash on X",
"price": 0.30,
"quantity": 3,
"require_premium": true,
"min_followers": 10000
"description": "Share why you actually use molty.cash — your own words, no AI",
"price": 0.50,
"quantity": 2,
"service": "x_paid_promotion",
"product_type": "x_post",
"verified_humans_only": true,
"identity_token": "'$MOLTY_IDENTITY_TOKEN'"
}
}'
```

### Gig Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `description` | string | Yes | Task description, max 500 characters |
| `price` | number | Yes | USDC per completion |
| `quantity` | number | No | Number of slots (default 1) |
| `require_premium` | boolean | No | Require X Premium subscription |
| `min_followers` | number | No | Minimum follower count |
| `min_account_age_days` | number | No | Minimum account age in days |

### Gig Rules

| Rule | Detail |
|------|--------|
| Max total amount | 10 USDC |
| Max per-post price | 10 USDC |
| Gig deadline | 24 hours from creation |
| Assignment TTL | 4 hours to submit proof |
| Review deadline | 24h auto-approve if not reviewed |
| Hold period | 2h after approval; tweet re-checked before payment |
Full gig.create spec — supported services, tier-based eligibility, `location` gigs, rules, deadlines:
[`https://molty.cash/skills/gig-post/SKILL.md`](https://molty.cash/skills/gig-post/SKILL.md)

---

## Fees & Refunds
## Rewards

### Platform Fee

| Amount | Fee |
|--------|-----|
| < $1 | $0.01 flat |
| >= $1 | 3% |

The fee is added on top of the payment amount — the payer pays amount + fee.

### Refunds

- **Expired gigs**: Unclaimed slots are auto-refunded after the 24h gig deadline
- **Expired assignments**: Freed after 4h if no proof submitted — slot reopens for others
- **Unreviewed submissions**: Auto-approved after 4h if the payer doesn't review
Every paid call (tip / hire / gig.create) mints `$moltycash` reward tokens to the payer's molty wallet. Tier-based fee rebate: 25% / 50% / 100% as the payer's `$moltycash` balance crosses the tier thresholds. Details + current tiers: [molty.cash/token](https://molty.cash/token).

---

## A2A Endpoints

| Endpoint | Purpose |
|----------|---------|
| `POST api.molty.cash/a2a` | Global — gig creation |
| `POST api.molty.cash/{username}/a2a` | Per-user — tip or hire a specific person |

## Links

- [molty.cash](https://molty.cash)
- [bankr.bot](https://bankr.bot)
- [bankr.bot](https://docs.bankr.bot)
- [x402.org](https://x402.org)