Für KI-Agenten

Gib deinem Agenten Hände in der echten Welt.

Ein MCP-Server und eine REST-API, über die ein Agent Dienstleistungen, Beratungen, Waren und Mikroaufgaben von verifizierten Menschen in Tschechien und der Slowakei bestellt — mit Treuhand, strukturierten Fehlern und einer next_actions-Liste in jeder Antwort.

MCP-Tools, jedes mit REST-Spiegel

Länder live

8 %

Provision, gezahlt vom Anbieter

Keine Gebühr für Agenten, kein Abo.

POST https://fordeal.ai/mcp · tools/call

{"method":"tools/call","params":{"name":"request_anything",
 "arguments":{"text":"Piano tuned, then carried up two floors",
              "address":"Praha 10","budget_max":3000}}}

{"job":{"id":"job_03H","kind":"open_request","status":"open"},
 "notified_providers":7,
 "next_actions":[{"tool":"get_offers","params":{"job_id":"job_03H"}}]}

In der Sandbox ausprobieren API-Key holen Lesen llms.txt

Die Demo unten braucht keinen Key. Dein eigener Key ist kostenlos und einen Aufruf entfernt.

Aufgabe eintippen, dem Marktplatz beim Antworten zusehen

Läuft live gegen die Sandbox, kein Key nötig: exakt die tools/call-Payloads, die ein echter Agent sendet, und die Antworten, die er zurückbekommt. Simulierte Anbieter, Spielgeld, bis zu 5 Läufe pro 10 Minuten.

POST /mcp · tools/call

$ wartet auf eine Aufgabe

Client verbinden

Streamable HTTP an einer URL, ein Bearer-Key im Header. Client wählen, einfügen, fertig.

Füge das in claude_desktop_config.json ein und starte die App neu.

Claude Desktop

{
  "mcpServers": {
    "fordeal": {
      "type": "http",
      "url": "https://fordeal.ai/mcp",
      "headers": {
        "Authorization": "Bearer <key>"
      }
    }
  }
}

Endpunkte

MCP-Server (Streamable HTTP, Bearer-Key)	https://fordeal.ai/mcp
REST-Basis	https://fordeal.ai/api/v1
OpenAPI 3.1	https://fordeal.ai/api/openapi.json
llms.txt	https://fordeal.ai/llms.txt
llms-full.txt	https://fordeal.ai/llms-full.txt
MCP-Manifest	https://fordeal.ai/.well-known/mcp.json

Authentifizierung und Antwortformat

Sende deinen Key als Header Authorization: Bearer <key>. Jeder Schreibzugriff akzeptiert einen idempotency_key. Jede Antwort enthält eine id, einen status, einen Preis mit Währung, Zeiten in ISO 8601 UTC und eine next_actions-Liste, sodass ein Agent nie raten muss, was als Nächstes aufzurufen ist.

Fehler

Fehler sind strukturiert und handlungsfähig: error.code sagt, was schiefging, und error.fix sagt, was zu ändern ist. Kein Parsen von Fließtext nötig.

{
  "error": {
    "code": "country_not_supported",
    "message": "Could not determine a supported country (got \"DE\")",
    "fix": "Pass an ISO 3166-1 alpha-2 country code in \"country\". Supported: CZ, SK."
  }
}

Sandbox

Den ganzen Ablauf zuerst gegen simulierte Anbieter mit Spielgeld durchlaufen. Tools, Argumente, Antworten und Fehler sind identisch mit dem Live-Marktplatz — live gehen heißt, den anderen Key zu senden.

So bekommst du die Keys

Die Registrierung gibt beide Keys desselben Agenten in einer Antwort zurück, einmalig. Speichere sie: Sie können nicht erneut abgerufen werden.

Registrierung

curl -sX POST https://fordeal.ai/api/v1/agents/register \
  -H 'Content-Type: application/json' \
  -d '{"name":"My shopping agent","owner_email":"you@example.com","platform":"claude","country":"CZ"}'

# { "api_key": "fd_live_…", "test_api_key": "fd_test_…",
#   "credit": { "balance": 500, "currency": "CZK" } }

fd_test_: Sandbox. Simulierte Anbieter, Spielgeld: Nichts wird abgebucht, keine Karte wird benutzt und kein echter Mensch kontaktiert. Jede Antwort enthält mode: "sandbox" und eine sandbox_note.
fd_live_: Der echte Marktplatz: echte Anbieter auf WhatsApp, echte Treuhand auf der Karte des Besitzers. Jede Antwort enthält mode: "live".

Was der Simulator tut

Nach create_job antworten zwei oder drei simulierte Anbieter mit einem festen Preis nahe der Schätzung, und einer lehnt ab. Nach accept_offer beginnt der gewählte Anbieter mit der Arbeit und meldet sie dann mit Beweisfoto und GPS als erledigt. Beratungen bekommen einen Meeting-Link, und gekaufte Artikel werden verschickt, sodass jeder Ablauf von Anfang bis Ende durchlaufen werden kann. Reaktionen dauern ein paar Sekunden, genau wie ein Anbieter, der auf WhatsApp antwortet, also frage get_status und get_offers so ab, wie du es in der Produktion tun würdest.

Setze einen dieser Schalter in die Auftragsbeschreibung, um einen Fehlerpfad zu erzwingen:

SIMULATE_NO_OFFERS — niemand antwortet. Der Auftrag bleibt offen, und get_offers gibt eine leere Liste zurück.
SIMULATE_DISPUTE — der Anbieter meldet den Auftrag mit absichtlich schlechtem Nachweis als erledigt (falsche Adresse, GPS weit entfernt), sodass du confirm_done mit approve: false aufrufen und den Streitfall sehen kannst.

POST https://fordeal.ai/api/v1/sandbox/reset — löscht alles, was dein Key in der Sandbox getan hat, und lässt andere Agenten in Ruhe. Die Sandbox lebt im Arbeitsspeicher, sie wird also auch beim Neustart des Servers zurückgesetzt.

POST https://fordeal.ai/api/v1/sandbox/demo — führt die ganze Runde auf dem Demo-Agenten der Sandbox ohne Key aus und gibt jeden Aufruf und jede Antwort zurück. Die interaktive Demo oben nutzt ihn; 5 Läufe pro IP pro 10 Minuten.

Startguthaben

Ein neu registrierter Agent bekommt ein Startguthaben in der Währung seines Landes: 500,00 CZK (Tschechien) · 20,00 € (Slowakei). Bei Live-Aufträgen wird das Guthaben vor der Karte des Besitzers verbraucht — accept_offer autorisiert nur den Teil, den das Guthaben nicht abdeckt, und wenn es den ganzen Preis abdeckt, gibt es gar keine Kartenzahlung. Jede Auftragsantwort sagt, was aus dem Guthaben und was von der Karte kam, und GET /api/v1/agents/me gibt das verbleibende Guthaben zurück. Sandbox-Läufe rühren es nie an.

Ein Auftrag, von Anfang bis zur Bezahlung

Fünf Aufrufe mit den Antworten, die die Sandbox wirklich zurückgibt. Sende den Test-Key in Authorization: Bearer, dann wiederhole dieselben fünf Aufrufe mit dem Live-Key — sonst ändert sich nichts.

1. create_job   {"description":"Kape kohoutek v koupelně","category":"plumber","address":"Vinohradská 10, Praha 2"}
   → {"job":{"id":"8f21…","status":"open","currency":"CZK"},"mode":"sandbox","sandbox_note":"Sandbox: … the money is fake …"}
2. get_offers   {"job_id":"8f21…"}                                    ← poll for a few seconds
   → {"offers":[{"id":"of_1","price":{"amount":1500,"currency":"CZK"},"eta":"…T09:00:00Z"},{"id":"of_2","price":{"amount":1320,"currency":"CZK"}}],"mode":"sandbox"}
3. accept_offer {"job_id":"8f21…","offer_id":"of_2"}
   → {"job":{"status":"accepted","price_agreed":{"amount":1320,"currency":"CZK"}},"payer":{"credit_used":{"amount":0},"card_charged":{"amount":1320}},"mode":"sandbox"}
4. get_status   {"job_id":"8f21…"}
   → {"job":{"status":"done_by_provider","proof":{"photos":["https://sandbox.fordeal.ai/proof/8f21….jpg"],"gps":{"lat":50.07,"lng":14.44}}},"mode":"sandbox"}
5. confirm_done {"job_id":"8f21…","approve":true}
   → {"job":{"status":"paid","commission":{"amount":105.6,"currency":"CZK"},"payout":{"amount":1214.4,"currency":"CZK"}},"mode":"sandbox"}

Agenten registrieren

Die Registrierung ist kostenlos und gibt dir einen API-Key, ein monatliches Budgetlimit, das du kontrollierst, und ein Audit-Log, das der Besitzer lesen kann.

Tools

Jedes Tool unten ist sowohl als MCP-Tool als auch als Aufruf auf der REST-Basis verfügbar.

Dienstleistungen und offene Anfragen

12 Tools

search_providersGET /api/v1/providers?address=&category=Verifizierte Anbieter nach Kategorie, Text, Ort und Radius finden, mit Statistiken und Preisen.

Aufruf

{
  "category": "plumber",
  "address": "Praha 4",
  "radius_km": 15,
  "max_price": 2000
}

Antwort

{
  "providers": [
    {
      "id": "prv_01H",
      "slug": "jan-h-instalater",
      "display_name": "Jan H.",
      "city": "Praha",
      "distance_km": 3.2,
      "hourly_rate": {
        "min": 750,
        "max": 1200,
        "currency": "CZK"
      },
      "verified": true,
      "stats": {
        "jobs_completed": 84,
        "on_time_rate": 0.96,
        "price_kept_rate": 0.98,
        "response_minutes_avg": 12
      }
    }
  ],
  "next_actions": [
    {
      "tool": "estimate_price",
      "description": "Get a price range before creating a job"
    }
  ]
}

estimate_pricePOST /api/v1/price-estimateEine Preisspanne für einen beschriebenen Auftrag an einem bestimmten Ort erhalten, bevor etwas angelegt wird.

Aufruf

{
  "category": "plumber",
  "description": "Dripping bathroom tap, two days",
  "address": "Praha 4"
}

Antwort

{
  "min": 900,
  "max": 1600,
  "currency": "CZK",
  "unit": "job",
  "reasoning": "Call-out plus one hour at Prague rates",
  "next_actions": [
    {
      "tool": "create_job",
      "description": "Create the request"
    }
  ]
}

create_jobPOST /api/v1/jobsEine Auftragsanfrage anlegen. Gibt eine Auftrags-ID, einen Status und die nächsten Aktionen zurück.

Aufruf

{
  "category": "plumber",
  "description": "Dripping bathroom tap, two days",
  "address": "Krymska 12, Praha 10",
  "time_window": {
    "start": "2026-09-10T08:00:00Z",
    "end": "2026-09-10T16:00:00Z"
  },
  "budget_max": {
    "amount": 2000,
    "currency": "CZK"
  },
  "photos": [
    "https://files.fordeal.ai/u/abc.jpg"
  ],
  "idempotency_key": "job-2026-09-07-001"
}

Antwort

{
  "job": {
    "id": "job_01H",
    "status": "open",
    "currency": "CZK",
    "price_estimate": {
      "min": 900,
      "max": 1600,
      "currency": "CZK"
    },
    "time_window_start": "2026-09-10T08:00:00Z",
    "time_window_end": "2026-09-10T16:00:00Z"
  },
  "next_actions": [
    {
      "tool": "get_offers",
      "description": "Poll for offers",
      "params": {
        "job_id": "job_01H"
      }
    }
  ]
}

request_anythingPOST /api/v1/requestsFreie Anfrage. Fordeal klassifiziert den Text: Eine klare Zuordnung wird ein normaler Auftrag, sonst eine offene Anfrage, die jeder verifizierte Anbieter in der Nähe mit einem Angebot beantworten kann. Gibt job_id, open_request und classified_as zurück.

Aufruf

{
  "text": "Someone to tune my grandmother's piano and then carry it up two floors, Saturday morning",
  "address": "Krymska 12, Praha 10",
  "budget_max": 3000,
  "deadline": "2026-09-12T12:00:00Z",
  "idempotency_key": "anything-2026-09-07-001"
}

Antwort

{
  "job": {
    "id": "job_03H",
    "kind": "open_request",
    "category": null,
    "status": "open",
    "currency": "CZK",
    "budget_max": {
      "amount": 3000,
      "currency": "CZK"
    }
  },
  "classified_as": {
    "category": null,
    "confidence": 0
  },
  "open_request": true,
  "notified_providers": 7,
  "next_actions": [
    {
      "tool": "get_offers",
      "description": "Open request sent to 7 providers nearby; check for offers",
      "params": {
        "job_id": "job_03H"
      }
    }
  ]
}

list_open_requestsGET /api/v1/requests/open?address=&radius_km=Offene Anfragen in der Nähe eines Ortes, zu denen keine Kategorie passte, für Anbieter und Agenten, die für sie handeln. Öffentlich, nichts Persönliches darin.

Aufruf

{
  "address": "Praha",
  "radius_km": 25
}

Antwort

{
  "count": 1,
  "country": "CZ",
  "requests": [
    {
      "id": "job_03H",
      "title": "Piano tuned and carried up two floors",
      "description": "Someone to tune my grandmother's piano and then carry it up two floors, Saturday morning",
      "city": "Praha",
      "budget_max": {
        "amount": 3000,
        "currency": "CZK"
      },
      "deadline": "2026-09-12T12:00:00Z",
      "created_at": "2026-09-07T09:12:00Z",
      "distance_km": 2.4
    }
  ],
  "next_actions": [
    {
      "tool": "request_anything",
      "description": "Post your own free-form request"
    }
  ]
}

get_offersGET /api/v1/jobs/{job_id}/offersDie Angebote auflisten, die Anbieter für einen Auftrag gesendet haben, mit Preis, ETA und Anbieterstatistiken.

Aufruf

{
  "job_id": "job_01H"
}

Antwort

{
  "offers": [
    {
      "id": "ofr_01H",
      "provider_id": "prv_01H",
      "price": {
        "amount": 1200,
        "currency": "CZK"
      },
      "eta": "2026-09-10T09:30:00Z",
      "status": "sent",
      "provider": {
        "display_name": "Jan H.",
        "stats": {
          "on_time_rate": 0.96,
          "price_kept_rate": 0.98
        }
      }
    }
  ],
  "next_actions": [
    {
      "tool": "accept_offer",
      "description": "Accept one offer",
      "params": {
        "job_id": "job_01H",
        "offer_id": "ofr_01H"
      }
    }
  ]
}

accept_offerPOST /api/v1/jobs/{job_id}/acceptEin Angebot annehmen. Die Zahlung wird an diesem Punkt auf das Treuhandkonto autorisiert.

Aufruf

{
  "job_id": "job_01H",
  "offer_id": "ofr_01H",
  "idempotency_key": "accept-001"
}

Antwort

{
  "job": {
    "id": "job_01H",
    "status": "accepted",
    "price_agreed": {
      "amount": 1200,
      "currency": "CZK"
    }
  },
  "payment": {
    "status": "requires_capture",
    "held": {
      "amount": 1200,
      "currency": "CZK"
    }
  },
  "next_actions": [
    {
      "tool": "get_status",
      "description": "Follow the job",
      "params": {
        "job_id": "job_01H"
      }
    }
  ]
}

get_statusGET /api/v1/jobs/{job_id}Den aktuellen Zustand eines Auftrags lesen: Status, Nachrichten, Nachweise, Preis und Zeiten.

Aufruf

{
  "job_id": "job_01H"
}

Antwort

{
  "job": {
    "id": "job_01H",
    "status": "done_by_provider",
    "done_at": "2026-09-10T10:40:00Z",
    "proof": {
      "photos": [
        "https://files.fordeal.ai/p/1.jpg"
      ]
    },
    "auto_confirm_at": "2026-09-12T10:40:00Z"
  },
  "next_actions": [
    {
      "tool": "confirm_done",
      "description": "Release or dispute",
      "params": {
        "job_id": "job_01H",
        "approve": true
      }
    }
  ]
}

confirm_donePOST /api/v1/jobs/{job_id}/confirmBestätigen, dass der Auftrag erledigt ist, und das Geld freigeben, oder ablehnen und einen Streitfall eröffnen.

Aufruf

{
  "job_id": "job_01H",
  "approve": true,
  "note": "Fixed, clean work"
}

Antwort

{
  "job": {
    "id": "job_01H",
    "status": "paid",
    "paid_at": "2026-09-10T10:45:00Z"
  },
  "payout": {
    "amount": 1104,
    "currency": "CZK"
  },
  "commission": {
    "amount": 96,
    "currency": "CZK",
    "rate": 0.08
  },
  "next_actions": []
}

book_servicePOST /api/v1/bookingsEine Festpreis-Dienstleistung sofort in einem freien Slot buchen (Anbieter mit Sofortbuchung).

Aufruf

{
  "service_id": "svc_01H",
  "slot": "2026-09-12T09:00:00Z"
}

Antwort

{
  "job": {
    "id": "job_05H",
    "kind": "instant_booking",
    "status": "accepted",
    "price_agreed": {
      "amount": 450,
      "currency": "CZK"
    },
    "scheduled_at": "2026-09-12T09:00:00Z"
  },
  "next_actions": [
    {
      "tool": "get_status",
      "description": "Poll the booking",
      "params": {
        "job_id": "job_05H"
      }
    }
  ]
}

cancel_jobPOST /api/v1/jobs/:id/cancelEinen Auftrag vor Arbeitsbeginn stornieren; kostenlos, solange kein Angebot angenommen ist.

Aufruf

{
  "job_id": "job_01H",
  "reason": "No longer needed"
}

Antwort

{
  "job": {
    "id": "job_01H",
    "status": "cancelled"
  },
  "next_actions": []
}

leave_reviewPOST /api/v1/jobs/:id/reviewEine verifizierte Bewertung hinterlassen, nachdem der Auftrag bezahlt ist.

Aufruf

{
  "job_id": "job_01H",
  "rating": 5,
  "text": "On time, price as quoted"
}

Antwort

{
  "ok": true
}

Beratungen

4 Tools

explain_medical_reportPOST /api/v1/medical/explainEinen Arztbericht oder Laborwerte in verständlicher Sprache erklären und vorschlagen, welches Fachgebiet zu konsultieren ist.

Aufruf

{
  "file_url": "https://files.fordeal.ai/u/report.pdf",
  "locale": "en"
}

Antwort

{
  "summary": "Blood count is normal apart from slightly raised CRP.",
  "values": [
    {
      "name": "CRP",
      "value": "12 mg/l",
      "reference": "0-5 mg/l",
      "status": "above"
    }
  ],
  "questions_for_doctor": [
    "Could the raised CRP come from the infection treated last week?"
  ],
  "specialty_suggested": "general-practitioner",
  "disclaimer": "This is an explanation, not a diagnosis.",
  "next_actions": [
    {
      "tool": "search_consultants",
      "description": "Find a doctor",
      "params": {
        "category": "general-practitioner"
      }
    }
  ]
}

search_consultantsPOST /api/v1/search_consultantsVerifizierte Berater eines Fachgebiets mit freien Slots finden.

Aufruf

{
  "category": "dermatologist",
  "date": "2026-09-11",
  "language": "en"
}

Antwort

{
  "consultants": [
    {
      "id": "prv_09H",
      "display_name": "MUDr. Eva N.",
      "license_verified": true,
      "registry": "CLK",
      "consultation_price": {
        "amount": 900,
        "currency": "CZK"
      },
      "slots": [
        {
          "id": "slt_1",
          "start": "2026-09-11T13:00:00Z",
          "end": "2026-09-11T13:30:00Z"
        }
      ]
    }
  ],
  "next_actions": [
    {
      "tool": "book_consultation",
      "description": "Book a slot"
    }
  ]
}

book_consultationPOST /api/v1/consultationsEinen Slot von 15, 30 oder 60 Minuten bei einem Berater buchen.

Aufruf

{
  "provider_id": "prv_09H",
  "slot": "slt_1",
  "minutes": 30,
  "idempotency_key": "cons-001"
}

Antwort

{
  "consultation": {
    "job_id": "job_03H",
    "provider_id": "prv_09H",
    "slot_start": "2026-09-11T13:00:00Z",
    "slot_end": "2026-09-11T13:30:00Z",
    "channel": "video"
  },
  "next_actions": [
    {
      "tool": "get_consultation_link",
      "description": "Get the meeting link",
      "params": {
        "job_id": "job_03H"
      }
    }
  ]
}

get_consultation_linkGET /api/v1/consultations/{job_id}/linkDen Video- oder Chat-Link für eine gebuchte Beratung erhalten.

Aufruf

{
  "job_id": "job_03H"
}

Antwort

{
  "meeting_url": "https://meet.fordeal.ai/job_03H",
  "valid_from": "2026-09-11T12:55:00Z"
}

Nachhilfe

4 Tools

search_tutorsGET /api/v1/tutors?subject=&level=&mode=Nachhilfelehrer für ein Fach und Niveau finden, nach Passung sortiert, mit freien Unterrichtsslots. Nur Erwachsene.

Aufruf

{
  "subject": "math",
  "level": "secondary",
  "mode": "online",
  "style": "patient, exam papers",
  "country": "CZ"
}

Antwort

{
  "adults_only": true,
  "currency": "CZK",
  "tutors": [
    {
      "id": "prv_21H",
      "display_name": "Mgr. Jana K.",
      "tutoring": {
        "subjects": [
          "math",
          "physics"
        ],
        "levels": [
          "secondary"
        ],
        "price_per_hour": {
          "amount": 450,
          "currency": "CZK"
        },
        "modes": [
          "online"
        ],
        "style": "Patient, step by step.",
        "package_discount_percent": {
          "5": 5,
          "10": 10
        }
      },
      "match": {
        "score": 0.92,
        "reason": "teaches math, secondary level, style: patient"
      },
      "slots": [
        {
          "id": "avail_prv_21H_20260914T130000",
          "start": "2026-09-14T13:00:00Z",
          "end": "2026-09-14T14:00:00Z"
        }
      ]
    }
  ],
  "next_actions": [
    {
      "tool": "book_lesson",
      "description": "Book one lesson in a listed slot",
      "params": {
        "provider_id": "prv_21H",
        "slot_start": "2026-09-14T13:00:00Z",
        "subject": "math",
        "level": "secondary",
        "student_is_adult": true
      }
    }
  ]
}

book_lessonPOST /api/v1/lessonsEine Unterrichtsstunde in einem gelisteten Slot buchen; das Honorar wird pro Stunde auf dem Treuhandkonto gehalten. Erfordert student_is_adult=true.

Aufruf

{
  "provider_id": "prv_21H",
  "slot_start": "2026-09-14T13:00:00Z",
  "subject": "math",
  "level": "secondary",
  "mode": "online",
  "package_id": "pkg_01H",
  "student_is_adult": true,
  "idempotency_key": "lesson-001"
}

Antwort

{
  "job": {
    "id": "job_07H",
    "kind": "consultation",
    "status": "accepted",
    "price_agreed": {
      "amount": 405,
      "currency": "CZK"
    },
    "lesson_package_id": "pkg_01H",
    "scheduled_at": "2026-09-14T13:00:00Z"
  },
  "consultation": {
    "channel": "video",
    "meeting_url": "https://fordeal.ai/meet/job_07H"
  },
  "payment": {
    "status": "requires_capture"
  },
  "lesson": {
    "subject": "math",
    "level": "secondary",
    "mode": "online",
    "duration_min": 60,
    "price": {
      "amount": 405,
      "currency": "CZK"
    },
    "package_id": "pkg_01H",
    "lessons_left": 4
  },
  "next_actions": [
    {
      "tool": "get_consultation_link",
      "description": "Meeting link for the video lesson",
      "params": {
        "job_id": "job_07H"
      }
    }
  ]
}

buy_lesson_packagePOST /api/v1/lesson-packagesEinen vergünstigten Preis pro Stunde für 5 oder 10 Stunden festschreiben. Nichts wird abgebucht, bis jede Stunde gebucht ist.

Aufruf

{
  "provider_id": "prv_21H",
  "lessons": 5,
  "subject": "math",
  "level": "secondary",
  "idempotency_key": "pkg-001"
}

Antwort

{
  "package": {
    "id": "pkg_01H",
    "lessons_total": 5,
    "lessons_used": 0,
    "price_per_lesson": {
      "amount": 405,
      "currency": "CZK"
    },
    "status": "active"
  },
  "lessons": [],
  "lessons_left": 5,
  "charged_now": {
    "amount": 0,
    "currency": "CZK"
  },
  "next_actions": [
    {
      "tool": "book_lesson",
      "description": "Book a lesson from this package",
      "params": {
        "provider_id": "prv_21H",
        "package_id": "pkg_01H",
        "subject": "math",
        "level": "secondary",
        "student_is_adult": true
      }
    }
  ]
}

get_lesson_packageGET /api/v1/lesson-packages/{package_id}Ein Paket lesen: genutzte Stunden, verbleibende Stunden und jede daraus gebuchte Stunde.

Aufruf

{
  "package_id": "pkg_01H"
}

Antwort

{
  "package": {
    "id": "pkg_01H",
    "lessons_total": 5,
    "lessons_used": 2,
    "price_per_lesson": {
      "amount": 405,
      "currency": "CZK"
    },
    "status": "active"
  },
  "lessons": [
    {
      "id": "job_07H",
      "status": "paid"
    },
    {
      "id": "job_08H",
      "status": "accepted"
    }
  ],
  "lessons_left": 3,
  "next_actions": [
    {
      "tool": "book_lesson",
      "description": "Book the next lesson",
      "params": {
        "provider_id": "prv_21H",
        "package_id": "pkg_01H"
      }
    }
  ]
}

Waren

9 Tools

search_itemsPOST /api/v1/search_itemsZum Verkauf stehende Waren nach Text, Kategorie, Ort und Höchstpreis suchen.

Aufruf

{
  "text": "road bike",
  "category": "sports",
  "location": "Brno",
  "max_price": 12000
}

Antwort

{
  "items": [
    {
      "id": "itm_01H",
      "title": "Road bike 56 cm",
      "price": {
        "amount": 9500,
        "currency": "CZK"
      },
      "condition": "used",
      "city": "Brno",
      "delivery_options": [
        "pickup",
        "courier"
      ]
    }
  ],
  "next_actions": [
    {
      "tool": "buy_item",
      "description": "Buy at the listed price",
      "params": {
        "item_id": "itm_01H"
      }
    }
  ]
}

buy_itemPOST /api/v1/items/{item_id}/buyEinen Artikel zum angegebenen Preis kaufen. Das Geld geht auf das Treuhandkonto.

Aufruf

{
  "item_id": "itm_01H",
  "delivery": "courier",
  "delivery_address": "Veveří 1, Brno",
  "idempotency_key": "buy-001"
}

Antwort

{
  "order": {
    "id": "ord_01H",
    "status": "paid",
    "price": {
      "amount": 9500,
      "currency": "CZK"
    },
    "delivery": "courier"
  },
  "next_actions": [
    {
      "tool": "get_status",
      "description": "Follow the order",
      "params": {
        "order_id": "ord_01H"
      }
    }
  ]
}

make_offerPOST /api/v1/items/{item_id}/offersEinen anderen Preis für einen Artikel anbieten.

Aufruf

{
  "item_id": "itm_01H",
  "price": {
    "amount": 8500,
    "currency": "CZK"
  },
  "message": "Can collect today"
}

Antwort

{
  "offer": {
    "id": "iof_01H",
    "status": "sent",
    "price": {
      "amount": 8500,
      "currency": "CZK"
    }
  },
  "next_actions": []
}

list_itemPOST /api/v1/itemsEinen Artikel zum Verkauf inserieren.

Aufruf

{
  "title": "Road bike 56 cm",
  "description": "Aluminium frame, serviced in June",
  "price": {
    "amount": 9500,
    "currency": "CZK"
  },
  "condition": "used",
  "photos": [
    "https://files.fordeal.ai/u/bike.jpg"
  ],
  "location": "Brno"
}

Antwort

{
  "item": {
    "id": "itm_02H",
    "status": "active"
  },
  "next_actions": []
}

accept_item_offerPOST /api/v1/items/{item_id}/offers/{offer_id}/acceptEin Angebot annehmen, das jemand für deinen Artikel gemacht hat.

Aufruf

{
  "item_id": "itm_02H",
  "offer_id": "iof_02H"
}

Antwort

{
  "order": {
    "id": "ord_02H",
    "status": "paid",
    "price": {
      "amount": 8500,
      "currency": "CZK"
    }
  },
  "next_actions": [
    {
      "tool": "get_status",
      "description": "Follow the order",
      "params": {
        "order_id": "ord_02H"
      }
    }
  ]
}

get_item_statusGET /api/v1/items/:idEinen Artikel und seine Bestellung prüfen: Angebote, Versand, Auszahlung.

Aufruf

{
  "item_id": "itm_01H"
}

Antwort

{
  "item": {
    "id": "itm_01H",
    "status": "reserved",
    "price": {
      "amount": 250,
      "currency": "EUR"
    }
  },
  "order": {
    "status": "shipped",
    "tracking_url": "https://tracking.example/1"
  },
  "next_actions": [
    {
      "tool": "confirm_item_received",
      "description": "Release the payment once the item arrived",
      "params": {
        "item_id": "itm_01H"
      }
    }
  ]
}

update_itemPATCH /api/v1/items/:idPreis, Beschreibung oder Verfügbarkeit deines Artikels ändern.

Aufruf

{
  "item_id": "itm_01H",
  "price": 220,
  "negotiable": true
}

Antwort

{
  "item": {
    "id": "itm_01H",
    "price": {
      "amount": 220,
      "currency": "EUR"
    },
    "negotiable": true
  },
  "next_actions": []
}

mark_item_shippedPOST /api/v1/items/:id/shippedDer Verkäufer markiert den Artikel als verschickt, optional mit Sendungsverfolgung.

Aufruf

{
  "item_id": "itm_01H",
  "tracking_url": "https://tracking.example/1"
}

Antwort

{
  "order": {
    "status": "shipped"
  },
  "next_actions": [
    {
      "tool": "get_item_status",
      "description": "Wait for the buyer to confirm receipt"
    }
  ]
}

confirm_item_receivedPOST /api/v1/items/:id/confirm-receivedDer Käufer bestätigt den Empfang; die Treuhand wird abzüglich Provision an den Verkäufer freigegeben.

Aufruf

{
  "item_id": "itm_01H"
}

Antwort

{
  "item": {
    "id": "itm_01H",
    "status": "sold"
  },
  "order": {
    "status": "paid_out",
    "commission": {
      "amount": 20,
      "currency": "EUR"
    },
    "payout": {
      "amount": 230,
      "currency": "EUR"
    }
  },
  "next_actions": []
}

Arbeit und Mikroaufgaben

2 Tools

create_taskPOST /api/v1/tasksEine Mikroaufgabe für eine Person vor Ort anlegen, mit den Nachweisen, die du verlangst.

Aufruf

{
  "description": "Photograph the notice board at the town hall entrance",
  "address": "Mariánské náměstí 2, Praha 1",
  "deadline": "2026-09-08T17:00:00Z",
  "pay": {
    "amount": 250,
    "currency": "CZK"
  },
  "proof_required": [
    "photo",
    "gps"
  ]
}

Antwort

{
  "job": {
    "id": "job_02H",
    "kind": "micro_task",
    "status": "open",
    "proof_required": [
      "photo",
      "gps"
    ]
  },
  "next_actions": [
    {
      "tool": "get_status",
      "description": "Follow the task",
      "params": {
        "job_id": "job_02H"
      }
    }
  ]
}

post_jobPOST /api/v1/job-postingsEine Stelle im Bereich Arbeit ausschreiben — Aushilfe, Saison oder Vollzeit.

Aufruf

{
  "title": "Warehouse helper, evening shift",
  "type": "temp",
  "description": "Loading parcels, 6 hour shifts",
  "location": "Brno",
  "pay": {
    "amount": 180,
    "currency": "CZK",
    "unit": "hour"
  }
}

Antwort

{
  "posting": {
    "id": "pst_01H",
    "status": "open",
    "city": "Brno",
    "pay": {
      "amount": 180,
      "currency": "CZK"
    },
    "pay_unit": "hour"
  },
  "next_actions": []
}

Referenz

1 Tool

list_categoriesGET /api/v1/categories?locale=enDer ganze Kategoriebaum mit lokalisierten Namen, Säulen und der Verifizierungsstufe, die Anbieter bestehen müssen.

Aufruf

{
  "locale": "en"
}

Antwort

{
  "categories": [
    {
      "slug": "craftsmen",
      "parent_slug": null,
      "pillar": "services",
      "name": "Craftsmen",
      "verification_level": "none",
      "minors_allowed": false,
      "minors_online_only": false
    },
    {
      "slug": "plumber",
      "parent_slug": "craftsmen",
      "pillar": "services",
      "name": "Plumber",
      "verification_level": "none",
      "minors_allowed": false,
      "minors_online_only": false
    },
    {
      "slug": "babysitting",
      "parent_slug": "care",
      "pillar": "services",
      "name": "Babysitting",
      "verification_level": "criminal_record",
      "minors_allowed": false,
      "minors_online_only": false
    }
  ]
}

Discovery

Alles, was ein Crawler, ein Modell oder ein Paketmanager braucht, um Fordeal ohne einen Menschen dazwischen zu finden.

llms.txt: https://fordeal.ai/llms.txt
llms-full.txt (die ganze Dokumentation in einer Datei): https://fordeal.ai/llms-full.txt
MCP-Manifest: https://fordeal.ai/.well-known/mcp.json
A2A-Agent-Card: https://fordeal.ai/.well-known/agent.json
OpenAPI 3.1: https://fordeal.ai/api/openapi.json
npm-Paket: @fordeal/mcpdemnächst

Preise

Der MCP-Server und die REST-API sind für Agenten kostenlos. Das einzige Geld, das Fordeal nimmt, sind 8 % eines erledigten und bezahlten Auftrags, und das zahlt der Anbieter. Erklärungen von Arztberichten sind für Menschen kostenlos und werden für Agenten pro Aufruf abgerechnet, sobald dieser Endpunkt die Pilotphase verlässt.