feat(#312): skills marketplace x402 micro-payment flow

[Peolite001]

Summary

Implements the x402 micro-payment flow for the skills marketplace. When an agent invokes a skill from another agent, the x402 HTTP payment protocol handles the micro-payment automatically: captures 402 responses, settles payment on-chain, retries with proof, and logs every

Related Issue

Closes #312

Changes

Added lib/marketplace/x402-middleware.ts — Payment middleware:
attemptSkillInvocation() — HTTP call to skill callUrl
invokeSkillWithPayment() — full flow: attempt → 402 → quote → settle → retry with X-Payment header
settleSkillPayment() — wraps x402 settlement (mock-aware)
Added lib/marketplace/invocation-ledger.ts — Payment ledger:
Records every invocation: { agentId, skillId, amountXLM, txHash, invokedAt, status }
Query by agent, skill, or limit; calculate total spent per agent
50k entry cap
Added app/api/marketplace/skills/[skillId]/invoke/route.ts — POST endpoint:
Body: { agentId, payload }
Validates skill exists, invokes with payment flow, records to ledger
Returns 402 with { error: "insufficient_balance" } when payment fails
Added tests/lib/marketplace/x402-middleware.test.ts — 5 integration tests
Added tests/lib/marketplace/invocation-ledger.test.ts — 6 unit tests

API Reference

Invoke a skill
POST /api/marketplace/skills/{skillId}/invoke
Content-Type: application/json

{
"agentId": "agent-1",
"payload": { "input": "hello" }
}

Response 200 (payment succeeded + skill executed)

{
"ok": true,
"response": { "result": "skill executed" },
"receipt": {
"txHash": "mock_tx_...",
"chain": "stellar",
"amountUsd": 0.25
},
"ledgerId": "inv_abc123"
}

Response 402 (insufficient balance)

{
"ok": false,
"error": "insufficient_balance",
"ledgerId": "inv_def456"
}

Testing

[x] Unit tests pass (npm test — 11 assertions, all green)
[x] Type check passes (npx tsc --noEmit)

Test coverage highlights

Scenario	Test
Agent invokes skill → 402 → payment → 200	handles 402 → payment → retry → 200 flow
Payment proof stored in ledger	records invocation in ledger after successful payment
Mock x402 flow → correct txHash logged	mock x402 flow → invocation logged with correct txHash
Insufficient balance → 402	returns insufficient_balance when payment settlement fails
Non-402 response bypasses payment	returns non-402 response directly without payment
Ledger filters and totals	filters by skillId and limits results, calculates total spent by agent

Architecture Notes

Uses existing lib/protocols/x402.ts quote/settle functions — no duplication
Mock mode aware: falls back to settleMockX402() when NEXT_PUBLIC_MOCK_MODE=true
Skill registry is currently a mock map pending PR#304; marked with TODO for easy integration
The X-Payment header carries the payment proof as JSON for the skill endpoint to verify

[sonarqubecloud]

Quality Gate failed

Failed conditions
C Security Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE