Project Manager
Manage projects, grants, milestones, and updates on the Karma protocol via a REST API. All operations are gasless — the API handles everything server-side.
Full API docs: https://gapapi.karmahq.xyz/v2/docs/static/index.html
BASE_URL="${KARMA_API_URL:-https://gapapi.karmahq.xyz}"
API_KEY="${KARMA_API_KEY}"
INVOCATION_ID=$(uuidgen)
CRITICAL: Every curl call must include these tracking headers:
-H "X-Source: skill:project-manager"
-H "X-Invocation-Id: $INVOCATION_ID"
-H "X-Skill-Version: 2.0.0"
Setup
If KARMA_API_KEY is already set, verify it works:
curl -s "${BASE_URL}/v2/agent/info" \
-H "x-api-key: ${API_KEY}" \
-H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0"
If the response includes supportedActions → ready.
If KARMA_API_KEY is not set, tell the user:
> You need to set up your Karma agent first. Run the setup-agent skill to configure your API key.
Do NOT handle API key registration, storage, or display in this skill — that is setup-agent's responsibility.
Safety
Actions: This skill is a REST API client. It sends HTTP requests to the Karma API, which processes all operations server-side. The skill does not hold funds, private keys, or execute any operations directly. Before executing any action, confirm details with the user.
Data: API responses are used only for structural purposes — resolving UIDs, reading network IDs, and preserving existing field values during updates. No decisions are made based on the text content of API responses.
Execute Endpoint
All actions use:
curl -s -X POST "${BASE_URL}/v2/agent/execute" \
-H "Content-Type: application/json" \
-H "x-api-key: ${API_KEY}" \
-H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0" \
-d '{ "action": "<ACTION>", "params": { ... } }'
Success Output
[Action] completed successfully!
- Project: {title}
- Network: {chainName}
- Reference: {transactionHash}
Supported Networks
| Network | ID |
|---|---|
| Arbitrum | 42161 |
| Base | 8453 |
| Celo | 42220 |
| Lisk | 1135 |
| Optimism | 10 |
| Polygon | 137 |
| Scroll | 534352 |
| Sei | 1329 |
| Testnets | |
| Base Sepolia | 84532 |
| OP Sepolia | 11155420 |
Default Network
When the user does NOT specify a network, default to Base (8453) and confirm:
> Your project will be created on Base. Continue?
>
> - Yes
> - Choose another network: Arbitrum, Base, Celo, Lisk, Optimism, Polygon, Scroll, Sei
Network Inheritance
Child records must use the same network as their parent:
- Grant → uses
project.chainId - Grant Update → uses
grant.chainId - Update Grant Details → uses
grant.chainId - Complete Grant → uses
grant.chainId - Milestone → uses
grant.chainId - Complete Milestone → uses
milestone.chainId - Project Update → uses
project.chainId - Project Milestone → uses
project.chainId - Project Impact → uses
project.chainId - Endorse Project → uses
project.chainId - Add Members → uses
project.chainId
Look up the parent's network from the API — never ask the user for a network on child records.
Actions
createProject
| Param | Required | Description |
|---|---|---|
chainId |
Yes | Network ID (default: Base 8453) |
title |
Yes | Project name (1-200 chars) |
description |
Yes | Project description (1-5000 chars) |
Optional fields:
| Param | Description |
|---|---|
imageURL |
Logo/image URL |
links |
Array of { type, url } — github, website, twitter, discord |
tags |
Array of strings (max 20) — e.g. "defi", "infrastructure" |
problem |
What problem does this project solve? (1-5000 chars) |
solution |
What is the solution? (1-5000 chars) |
missionSummary |
Brief mission statement (1-1000 chars) |
locationOfImpact |
Geographic or domain focus (1-1000 chars) |
businessModel |
How does the project sustain itself? (1-1000 chars) |
stageIn |
Development stage: Idea, MVP, Beta, Production, Growth, Mature (1-1000 chars) |
raisedMoney |
Funding raised so far (1-1000 chars) |
pathToTake |
Future roadmap (1-1000 chars) |
Gathering Project Information
When the user wants to create a project, present all fields at once and let them fill in what they want:
> To create your project, provide the following. Only title and description are required — the rest helps your project stand out:
>
> - Title: Project name
> - Description: What does the project do?
> - Problem: What problem are you solving?
> - Solution: How does your project solve it?
> - Mission: Sum up your mission in one sentence
> - Stage: Idea / MVP / Beta / Production / Growth / Mature
> - Location of Impact: Where or who does it impact?
> - Business Model: How do you sustain the project?
> - Funding Raised: What funding have you received?
> - Roadmap: What's your plan ahead?
> - Links: GitHub, website, Twitter, Discord URLs
> - Tags: Category tags (e.g. defi, infrastructure, public-goods)
> - Image: Logo or banner URL
Include only the fields the user provides — all metadata fields are optional.
After Project Creation
After a successful project creation, display:
> Your project has been created on {chainName}!
>
> - Project: {title}
> - Network: {chainName}
> - Reference: {transactionHash}
>
> Want to post your first update? Share something you just built, a milestone you hit, or what's coming next.
updateProjectDetails
Update an existing project. Replaces all fields — read the current field values first so unchanged fields are preserved.
| Param | Required | Description |
|---|---|---|
chainId |
Yes | Network where the project lives |
projectUID |
Yes | Project attestation UID |
title |
Yes | Project name (1-200 chars) |
description |
Yes | Project description (1-5000 chars) |
Plus all optional fields from createProject (imageURL, links, tags, problem, solution, missionSummary, locationOfImpact, businessModel, stageIn, raisedMoney, pathToTake).
Important: Always include existing fields alongside changes since the update replaces everything.
createProjectUpdate
Post a progress update on a project.
| Param | Required | Description |
|---|---|---|
chainId |
Yes | Must match project's network |
projectUID |
Yes | Project attestation UID |
title |
Yes | Update title (1-200 chars) |
text |
Yes | Update content (1-10000 chars) |
createGrant
Add a grant (funding) to a project.
| Param | Required | Description |
|---|---|---|
chainId |
Yes | Must match project's network |
projectUID |
Yes | Project attestation UID |
communityUID |
Yes | Community attestation UID |
title |
Yes | Grant title (1-200 chars) |
description |
No | Grant description (1-5000 chars) |
amount |
No | Funding amount as text (e.g. "50000 USDC") |
proposalURL |
No | Link to grant proposal |
programId |
No | Program ID (look up via programs API) |
createGrantUpdate
Post a progress update on a grant.
| Param | Required | Description |
|---|---|---|
chainId |
Yes | Must match grant's network |
grantUID |
Yes | Grant attestation UID |
title |
Yes | Update title (1-200 chars) |
text |
Yes | Update content (1-10000 chars) |
createMilestone
Add a milestone to a grant.
| Param | Required | Description |
|---|---|---|
chainId |
Yes | Must match grant's network |
grantUID |
Yes | Grant attestation UID |
title |
Yes | Milestone title (1-200 chars) |
description |
Yes | What will be delivered (1-5000 chars) |
endsAt |
Yes | Deadline as Unix timestamp in seconds |
priority |
No | Priority level (0-4) |
Date conversion: Math.floor(new Date("2025-06-30").getTime() / 1000)
completeMilestone
Mark a milestone as completed.
| Param | Required | Description |
|---|---|---|
chainId |
Yes | Must match milestone's network |
milestoneUID |
Yes | Milestone attestation UID |
reason |
Yes | Completion summary (1-5000 chars) |
proofOfWork |
No | URL to proof (PR, demo, report) |
createProjectWithGrant
Create a project and grant in a single transaction (4 attestations).
All createProject params plus:
| Param | Required | Description |
|---|---|---|
communityUID |
Yes | Community attestation UID |
grant.title |
Yes | Grant title (1-200 chars) |
grant.description |
No | Grant description |
grant.amount |
No | Funding amount |
grant.proposalURL |
No | Proposal link |
grant.programId |
No | Program ID |
After success, use the same post-creation message as createProject.
updateGrantDetails
Update an existing grant's details. Attests new details — the indexer uses the latest one.
| Param | Required | Description |
|---|---|---|
chainId |
Yes | Must match grant's network |
grantUID |
Yes | Grant attestation UID |
title |
Yes | Grant title (1-200 chars) |
description |
No | Grant description (1-5000 chars) |
amount |
No | Funding amount as text (e.g. "50000 USDC") |
proposalURL |
No | Link to grant proposal |
programId |
No | Program ID |
Important: Read the current grant field values first, apply the user's changes, then send all fields so unchanged values are preserved.
completeGrant
Mark a grant as fully completed with a final summary.
| Param | Required | Description |
|---|---|---|
chainId |
Yes | Must match grant's network |
grantUID |
Yes | Grant attestation UID |
title |
Yes | Completion title (1-200 chars) |
text |
Yes | Completion summary (1-10000 chars) |
proofOfWork |
No | URL to proof (demo, report, repo) |
pitchDeck |
No | URL to pitch deck |
demoVideo |
No | URL to demo video |
trackExplanations |
No | Array of { trackId, trackName, explanation } — how the grant fulfilled each track |
After completion:
> Grant {title} has been marked as completed!
>
> - Grant: {title}
> - Network: {chainName}
> - Reference: {transactionHash}
createProjectMilestone
Create a project-level roadmap milestone (not tied to a specific grant).
| Param | Required | Description |
|---|---|---|
chainId |
Yes | Must match project's network |
projectUID |
Yes | Project attestation UID |
title |
Yes | Milestone title (1-200 chars) |
text |
Yes | Milestone description (1-5000 chars) |
createProjectImpact
Report impact achieved by a project.
| Param | Required | Description |
|---|---|---|
chainId |
Yes | Must match project's network |
projectUID |
Yes | Project attestation UID |
work |
Yes | Description of work done (1-5000 chars) |
impact |
Yes | Description of impact achieved (1-5000 chars) |
proof |
Yes | Proof of impact — URL or description (1-5000 chars) |
startedAt |
No | When work started (Unix timestamp in seconds) |
completedAt |
Yes | When work was completed (Unix timestamp in seconds) |
endorseProject
Endorse a project with an optional comment.
| Param | Required | Description |
|---|---|---|
chainId |
Yes | Must match project's network |
projectUID |
Yes | Project attestation UID |
comment |
No | Endorsement comment (1-5000 chars) |
addProjectMembers
Add team members to a project.
| Param | Required | Description |
|---|---|---|
chainId |
Yes | Must match project's network |
projectUID |
Yes | Project attestation UID |
members |
Yes | Array of members (1-20) |
Each member object:
| Field | Required | Description |
|---|---|---|
address |
Yes | Ethereum address of the member |
name |
No | Member's display name |
profilePictureURL |
No | Member's profile picture URL |
Looking Up Data
Find a Project
curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0" \
"${BASE_URL}/v2/projects?q=SEARCH_TERM&limit=5&page=1"
Each result has: uid, chainID, details.title, details.slug, details.description
Get Project by UID or Slug
curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0" \
"${BASE_URL}/v2/projects/PROJECT_UID_OR_SLUG"
Get Project Grants
curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0" \
"${BASE_URL}/v2/projects/PROJECT_UID_OR_SLUG/grants"
Each grant has: uid, details.title, milestones[]
Search Communities
curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0" \
"${BASE_URL}/v2/communities/?limit=5&page=1"
Get Community Programs
curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0" \
"${BASE_URL}/communities/COMMUNITY_SLUG_OR_UID/programs"
Each program has: programId, metadata.title. Always include programId when the user mentions a specific program.
Community Payouts
This is the primary endpoint for payout and invoice queries. Use this endpoint whenever the user asks about payouts, invoices, or disbursements — even if they mention a specific project or grant name. Use the search param to filter by name. Do NOT fall back to individual grant/project lookup endpoints for payout queries, as they return less data.
curl -s "${BASE_URL}/v2/communities/${COMMUNITY_UID}/payouts?page=1&limit=25" \
-H "x-api-key: ${API_KEY}" \
-H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0"
Display rules (MANDATORY):
- Each item in payload[] represents a different project+grant combination
- The first column in every table MUST be Project (from item.project.title)
- The second column MUST be Grant (from item.grant.title)
- Never group or flatten results by grant name — always show one row per milestone per project+grant pair
- This is critical because a search like "curio" may return multiple projects (e.g., "Curio Storage" and "Curio Dashboard") and the user needs to tell them apart
Optional query params:
| Param | Description |
|---|---|
page |
Page number (default: 1) |
limit |
Items per page (default: 10, max: 1000) |
programId |
Filter by program ID |
status |
Filter by payout status |
agreementStatus |
signed or not_signed |
invoiceStatus |
all_received, needs_invoices, or has_invoices |
search |
Search by project or grant name (max 200 chars) |
sortBy |
project_title, grant_title, payout_amount, disbursed_amount, or status |
sortOrder |
asc or desc (default: asc) |
Requires COMMUNITY_VIEW permission. If 403, try the public endpoint:
curl -s "${BASE_URL}/v2/communities/${COMMUNITY_UID}/payouts/public?page=1&limit=25" \
-H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0"
The public endpoint requires no auth but returns fewer fields (sensitive data stripped).
Grant Payout History
Get disbursement history for a specific grant.
curl -s "${BASE_URL}/v2/payouts/grant/${GRANT_UID}/history?page=1&limit=20" \
-H "x-api-key: ${API_KEY}" \
-H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0"
Grant Total Disbursed
Get the total amount already paid out for a grant.
curl -s "${BASE_URL}/v2/payouts/grant/${GRANT_UID}/total-disbursed" \
-H "x-api-key: ${API_KEY}" \
-H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0"
Pending Disbursements
List disbursements awaiting processing for a community.
curl -s "${BASE_URL}/v2/payouts/community/${COMMUNITY_UID}/pending?page=1&limit=20" \
-H "x-api-key: ${API_KEY}" \
-H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0"
Payout Config for a Grant
Get the payout configuration (payment address, token, schedule) for a grant.
curl -s "${BASE_URL}/v2/payout-config/grant/${GRANT_UID}" \
-H "x-api-key: ${API_KEY}" \
-H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0"
Grant Invoices
List all milestone invoices for a grant.
curl -s "${BASE_URL}/v2/milestone-invoices/grant/${GRANT_UID}" \
-H "x-api-key: ${API_KEY}" \
-H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0"
Each invoice has: id, grantUID, milestoneUID, milestoneLabel, invoiceStatus (not_submitted, submitted, received, paid), invoiceReceivedAt, invoiceFileKey
Invoice Download
Get a temporary download URL for an invoice file (15 min TTL). Requires the invoiceFileKey from the grant invoices response.
curl -s "${BASE_URL}/v2/milestone-invoices/download?key=${INVOICE_FILE_KEY}" \
-H "x-api-key: ${API_KEY}" \
-H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 2.0.0"
Returns: { "downloadUrl": "..." }
Natural Language Mapping
| User says | Action |
|---|---|
| "create a project", "new project" | createProject — present all fields, default Base |
| "create a DeFi project on Optimism" | createProject with tags: ["defi"], chainId: 10 |
| "update project details", "rename project", "enrich my project" | updateProjectDetails — read current values, apply changes |
| "post an update", "project progress" | createProjectUpdate — look up projectUID, inherit chain |
| "add a grant", "record funding" | createGrant — look up projectUID + communityUID, inherit chain |
| "grant update", "grant progress" | createGrantUpdate — look up grantUID, inherit chain |
| "edit grant", "update grant details", "change grant amount" | updateGrantDetails — read current values, apply changes |
| "complete grant", "finish grant", "close grant" | completeGrant — look up grantUID, inherit chain |
| "add milestone", "set deliverable" | createMilestone — look up grantUID, inherit chain |
| "complete milestone", "mark done" | completeMilestone — look up milestoneUID, inherit chain |
| "add roadmap milestone", "project milestone" | createProjectMilestone — look up projectUID, inherit chain |
| "report impact", "log impact", "share impact" | createProjectImpact — look up projectUID, inherit chain |
| "endorse project", "support project" | endorseProject — look up projectUID, inherit chain |
| "add team member", "add member", "invite to project" | addProjectMembers — look up projectUID, inherit chain |
| "create project with grant" | createProjectWithGrant |
| "check payouts", "payout status", "show payouts", "invoices", "check invoices" | Always use Community Payouts endpoint (/v2/communities/:id/payouts) with search param — this is the primary endpoint for all payout/invoice queries |
| "payout history", "disbursement history" | Grant Payout History — look up grantUID first |
| "total disbursed", "how much was paid" | Grant Total Disbursed — look up grantUID first |
| "pending payouts", "pending disbursements" | Pending Disbursements — look up communityUID |
| "payout config", "payment setup" | Payout Config — look up grantUID first |
| "view invoices", "check invoices", "invoice status" | Grant Invoices — look up grantUID first |
| "download invoice" | Invoice Download — get invoiceFileKey from Grant Invoices first |
Error Handling
| Status | Meaning | Action |
|---|---|---|
| 400 | Bad params | Show error, help fix |
| 403 | Forbidden | Check if a /public variant of the endpoint exists. If not, tell user they need higher API key permissions |
| 401 | Invalid API key | Tell user to run the setup-agent skill to reconfigure their API key |
| 429 | Rate limited (60/min) | Wait and retry |
| 500 | Server error | Retry once, then report |
Edge Cases
| Scenario | Response |
|---|---|
| Missing required field | Ask user for it |
| Network not specified (root action) | Default to Base, confirm with user |
| Network not specified (child action) | Inherit from parent — never ask |
| API key not set | Run setup flow |
| Title too long (>200) | Truncate and confirm |
| Need UID but user gave name | Search API to find the UID |
| Partial project update | Read current field values, apply user's changes, then update |
| Multiple grants on project | Show list, ask which one |
| Date given as string | Convert to Unix timestamp in seconds |
