foundry-settlement

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:

1. IntentMandate - task or requirement intent
2. CartMandate - accepted work or pricing context
3. 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