arkforge-agent-client

# ArkForge Agent Client

[![GitHub Stars](https://img.shields.io/github/stars/ark-forge/arkforge-agent-client?style=flat&label=Star)](https://github.com/ark-forge/arkforge-agent-client/stargazers)

A proof-of-concept demonstrating **autonomous agent-to-agent paid transactions** through the [ArkForge Trust Layer](https://github.com/ark-forge/trust-layer).

One agent (this client) calls another agent (the [ArkForge MCP EU AI Act](https://github.com/ark-forge/mcp-eu-ai-act) scanner) to scan a code repository for EU AI Act compliance. Every transaction flows through the Trust Layer, which produces a tamper-proof cryptographic proof (SHA-256 chain + Ed25519 signature + RFC 3161 certified timestamp + Sigstore Rekor public log entry).

**Free tier:** fully autonomous — the agent signs up and runs with a single curl, no card required.
**Pro tier:** one-time human setup (Stripe Checkout to save a card), fully autonomous after that.

## Quick Start

### 1. Get an API key

**Free plan** — no card required:

```bash
curl -X POST https://trust.arkforge.tech/v1/keys/free-signup \
  -H "Content-Type: application/json" \
  -d '{"email": "your@email.com"}'
```

Your `mcp_free_*` API key will be emailed automatically. 100 calls/month, 3 witnesses (Ed25519, RFC 3161, Sigstore Rekor — no Stripe required).

**Pro plan** — buy initial credits and save card (once):

**Option A — via setup_card.py:**

```bash
python3 setup_card.py your@email.com --test    # Test mode (Stripe test card)
python3 setup_card.py your@email.com           # Live mode (real charges)
```

**Option B — via curl:**

```bash
curl -X POST https://trust.arkforge.tech/v1/keys/setup \
  -H "Content-Type: application/json" \
  -d '{"email": "your@email.com", "mode": "test", "amount": 10}'
```

Open the returned `checkout_url` in a browser. The initial purchase (minimum 10 EUR = 100 proofs) is charged immediately and your card is saved for future top-ups. For test mode, use Stripe test card `4242 4242 4242 4242` (any future expiry, any CVC). Your API key and credits are set up automatically after payment.

### 2. Top up credits (Pro plan)

Buy more credits any time — the saved card is charged directly, no browser required.

**Via agent.py:**

```bash
pip install requests
export TRUST_LAYER_API_KEY="mcp_pro_..."
python3 agent.py credits 10    # Buy 10 EUR = 100 proofs — receipt auto-saved
```

**Via curl:**

```bash
curl -X POST https://trust.arkforge.tech/v1/credits/buy \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: mcp_pro_..." \
  -d '{"amount": 10}'
# Returns: {"credits_added": 10.0, "balance": 10.0, "proofs_available": 100, ...}
```

Each proof costs 0.10 EUR. Min 1 EUR, max 100 EUR. Credits are deducted automatically on each proxy call. Credits never expire.

### 3. Run a scan

```bash
export TRUST_LAYER_API_KEY="mcp_test_..."    # or mcp_pro_... for live
python3 agent.py scan https://github.com/owner/repo
```

If you purchased credits earlier, the saved receipt is **auto-attached** as payment evidence. You can also provide one manually:

```bash
python3 agent.py scan https://github.com/owner/repo \
  --receipt-url "https://pay.stripe.com/receipts/payment/CAcaFwoV..."
```

To skip auto-attach for a single call:

```bash
python3 agent.py scan https://github.com/owner/repo --no-receipt
```

**Mode B PoC — pay the scan provider directly via Stripe:**

```bash
export STRIPE_SECRET_KEY="sk_test_..."       # your agent's Stripe key
export STRIPE_PAYMENT_METHOD="pm_xxx"        # saved payment method
export SCAN_PROVIDER_PRICE="100"             # optional, cents EUR (default: 100 = 1.00 EUR)
python3 agent.py scan https://github.com/owner/repo --pay-provider
```

The agent creates a Stripe `PaymentIntent` off-session, retrieves the `receipt_url` from the resulting `Charge`, and attaches it automatically as `provider_payment` to the Trust Layer call. ArkForge does not handle this money — the payment goes directly between agents.

### 4. Just pay (no scan)

```bash
python3 agent.py pay                     # auto-attaches saved receipt if any
python3 agent.py pay --no-receipt        # skip auto-attach
python3 agent.py pay --receipt-url "https://pay.stripe.com/receipts/payment/..."
```

### 5. Verify a proof

```bash
python3 agent.py verify prf_20260225_171714_4ebb28
```

### 6. Check reputation

```bash
python3 agent.py reputation <agent_id>
```

```
============================================================
AGENT REPUTATION
============================================================
  Agent:       sha256:buyer_abc123...
  Score:       85/100
  Success rate:  100.0%
  Confidence:    0.85
  Formula:       floor(success_rate × confidence) − penalties
  Total proofs:  10
  Signature:   ed25519:T3hY8kLm9nPq...(verified)
============================================================
```

The score is publicly auditable: `score = floor(success_rate × confidence)`.
Confidence grows with volume (0.60 at 1 proof → 1.00 at 20+ proofs).
One optional penalty: −15 if the agent changed its declared identity.

### 7. File a dispute

```bash
python3 agent.py dispute prf_20260301_120000_abc123 "Response was empty"
```

```
============================================================
DISPUTE FILED
============================================================
  Dispute ID:  disp_a1b2c3d4
  Proof ID:    prf_20260301_120000_abc123
  Status:      open
  Resolution:  PENDING
============================================================
```

### 8. View dispute history

```bash
python3 agent.py disputes <agent_id>
```

```
============================================================
DISPUTE HISTORY
============================================================
  Filed:       3
  Won:         2
  Lost:        1

  Recent disputes:
    disp_a1b2c3d4 | prf_20260301_120000_abc123 | UPHELD
    disp_e5f6g7h8 | prf_20260228_090000_def456 | DENIED
    disp_i9j0k1l2 | prf_20260227_150000_ghi789 | UPHELD
============================================================
```

### Example scan output

```
============================================================
EU AI ACT COMPLIANCE SCAN — via Trust Layer
============================================================
Timestamp:   2026-02-25T17:17:12.560154+00:00
Target:      https://github.com/openai/openai-quickstart-python
Price:       0.10 EUR (from prepaid credits)
Trust Layer: https://trust.arkforge.tech/v1/proxy
Scan API:    https://arkforge.tech/api/v1/scan-repo
API Key:     mcp_te...

[PAYMENT]
  Amount:    0.1 eur
  Status:    succeeded
  Txn ID:    crd_20260227_143012_a1b2c3

[SCAN RESULT]
  Compliance:  2/3 (66.7%)
  Risk Cat:    limited
  Frameworks:  openai, anthropic

[PROOF — Trust Layer]
  ID:           prf_20260225_171714_4ebb28
  Spec:         1.1
  Chain Hash:   sha256:5319f160352fea2c1889cf6dcbb9d1b431...
  Request Hash: sha256:0b801bccb76376504cb2c5f92c55cd7cfd...
  Signature:    ed25519:T3hY8k...(verified)
  Verify URL:   https://trust.arkforge.tech/v1/proof/prf_20260225_171714_4ebb28
  Share URL:    https://arkforge.tech/trust/v/prf_20260225_171714_4ebb28
  Timestamp:    2026-02-25T17:17:12Z
  Upstream:     Wed, 25 Feb 2026 17:17:13 GMT
  TSA:          pending

[ATTESTATION — Digital Stamp]
  Embedded in scan result body as _arkforge_attestation
  Status:       VERIFIED_TRANSACTION

[RESPONSE HEADERS — Ghost Stamp]
  X-ArkForge-Verified: true
  X-ArkForge-Proof-ID: prf_20260225_171714_4ebb28
  X-ArkForge-Trust-Link: https://arkforge.tech/trust/v/prf_20260225_171714_4ebb28

[SAVED] logs/scan_20260225_171715.json
============================================================
```

With `--receipt-url` or `--pay-provider`, an additional section appears:

```
[PAYMENT EVIDENCE — External Receipt]
  Fetch:     OK (fetched)
  Hash:      sha256:af65b75f3901dfd0ed9590a009bf7283e318...
  Parsing:   success
  Amount:    25.0 usd
  Status:    Paid
  Date:      February 28, 2026
  Verified:  fetched
```

With `--pay-provider`, the Stripe payment is shown before the scan:

```
[MODE B] P

[truncated…]