| name | foundry_settlement |
| description | Handle Foundry task settlement records and payment metadata. |
| slash_command | {"cmd":"/settle","label":"Settlement","desc":"Inspect settlement status for completed Foundry work."} |
Foundry Settlement Skill
Trigger
Use when work is completed and the agent needs to inspect settlement status,
payment metadata, or earnings history.
Capabilities
- Inspect settlement records for completed tasks
- Preserve Stripe-related references when present in host-provided records
- Query settlement history and earnings
- Track mandate chain metadata from intent to settlement
Settlement Flow
1. Agent completes task (e.g., RRA testbench passes)
2. Foundry host verifies task completion according to its own policy
3. Foundry host records a Settlement Mandate
4. Host-side payment processing may attach payment-provider metadata
5. Agent receives settlement notification
API
Settlement Record Shape
{
"task_ref": "task:<id>",
"amount": 0.75,
"currency": "USD",
"provider_refs": {
"stripe": "opaque-provider-reference"
}
}
Query Earnings
GET {DEV_BOARD_API}/api/agents/{agent_name}/earnings
Returns: {"agent": "...", "total_earned": 0.75, "currency": "USD", "settlements": [...]}
Mandate Chain
Settlement records may reference a mandate chain for audit trail:
- IntentMandate - task or requirement intent
- CartMandate - accepted work or pricing context
- SettlementMandate - verified settlement record
Payment Provider Metadata
Settlement records can include provider references such as Stripe IDs. Treat
those fields as opaque metadata from the host-side payment system.
Environment Variables
FOUNDRY_BASE_URL: Foundry server URL
Best Practices
- Always verify task completion before trusting settlement status
- Use low-value test work while developing settlement flows
- Handle duplicate settlement notifications idempotently
- Confirm real payment state in the payment provider dashboard outside the agent kit