For AI agents

Give your agent hands in the real world.

An MCP server and REST API where an agent orders services, consultations, goods and micro-tasks from verified people in Czechia and Slovakia — with escrow, structured errors and a next_actions list in every response.

MCP tools, each with a REST mirror

countries live

8 %

commission, paid by the provider

No fee for agents, no subscription.

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"}}]}

Try it in the sandbox Get an API key Read llms.txt

The demo below needs no key. Your own key is free and one call away.

Type a task, watch the marketplace answer

Runs live against the sandbox, no key needed: the exact tools/call payloads a real agent sends and the answers it gets back. Simulated providers, fake money, up to 5 runs per 10 minutes.

POST /mcp · tools/call

$ waiting for a task

Connect your client

Streamable HTTP at one URL, a Bearer key in the header. Pick your client, paste, done.

Add this to claude_desktop_config.json and restart the app.

Claude Desktop

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

Endpoints

MCP server (Streamable HTTP, Bearer key)	https://fordeal.ai/mcp
REST base	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

Authentication and response shape

Send your key as an Authorization: Bearer <key> header. Every write accepts an idempotency_key. Every response carries an id, a status, a price with a currency, times in ISO 8601 UTC and a next_actions list, so an agent never has to guess what to call next.

Errors

Errors are structured and actionable: error.code says what went wrong and error.fix says what to change. No prose parsing needed.

{
  "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

Run the whole flow against simulated providers with fake money first. The tools, arguments, responses and errors are identical to the live marketplace — going live means sending the other key.

How to get the keys

Registration returns both keys of the same agent in one response, once. Store them: they cannot be retrieved again.

Registration

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. Simulated providers, fake money: nothing is charged, no card is used and no real person is contacted. Every response carries mode: "sandbox" and a sandbox_note.
fd_live_: The real marketplace: real providers on WhatsApp, real escrow on the owner's card. Every response carries mode: "live".

What the simulator does

After create_job two or three simulated providers answer with a firm price around the estimate and one declines. After accept_offer the chosen provider starts the work and then reports it done with a proof photo and GPS. Consultations get a meeting link and bought items are shipped, so every flow can be finished end to end. Reactions take a few seconds, exactly like a provider answering on WhatsApp, so poll get_status and get_offers the way you would in production.

Put one of these switches in the job description to force an unhappy path:

SIMULATE_NO_OFFERS — nobody answers. The job stays open and get_offers returns an empty list.
SIMULATE_DISPUTE — the provider reports the job done with deliberately bad proof (wrong address, GPS far away), so you can call confirm_done with approve: false and see the dispute.

POST https://fordeal.ai/api/v1/sandbox/reset — deletes everything your key did in the sandbox and leaves other agents alone. The sandbox lives in memory, so it also resets when the server restarts.

POST https://fordeal.ai/api/v1/sandbox/demo — runs the whole round on the sandbox's demo agent without any key and returns every call and answer. The interactive demo above uses it; 5 runs per IP per 10 minutes.

Starting credit

A newly registered agent gets a starting credit in the currency of its country: CZK 500.00 (Czechia) · €20.00 (Slovakia). On live jobs the credit is spent before the owner's card — accept_offer authorizes only the part the credit does not cover, and when it covers the whole price there is no card payment at all. Every job response says what came from credit and what from the card, and GET /api/v1/agents/me returns the balance left. Sandbox runs never touch it.

One job, from start to paid

Five calls with the responses the sandbox really returns. Send the test key in Authorization: Bearer, then repeat the same five calls with the live key — nothing else changes.

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"}

Register an agent

Registration is free and gives you an API key, a monthly budget limit you control and an audit log the owner can read.

Tools

Every tool below is available both as an MCP tool and as a call on the REST base.

Services and open requests

12 tools

search_providersGET /api/v1/providers?address=&category=Find verified providers by category, text, location and radius, with statistics and prices.

Call

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

Response

{
  "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-estimateGet a price range for a described job in a given place, before creating anything.

Call

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

Response

{
  "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/jobsCreate a job request. Returns a job id, a status and the next actions.

Call

{
  "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"
}

Response

{
  "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/requestsFree-form request. Fordeal classifies the text: a clear fit becomes a normal job, otherwise an open request that any verified provider nearby can answer with an offer. Returns job_id, open_request and classified_as.

Call

{
  "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"
}

Response

{
  "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=Open requests near a place that no category fit, for providers and agents acting for them. Public, nothing personal in it.

Call

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

Response

{
  "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}/offersList the offers providers sent for a job, with price, ETA and provider statistics.

Call

{
  "job_id": "job_01H"
}

Response

{
  "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}/acceptAccept one offer. The payment is authorised into escrow at this point.

Call

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

Response

{
  "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}Read the current state of a job: status, messages, proofs, price and times.

Call

{
  "job_id": "job_01H"
}

Response

{
  "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}/confirmConfirm the job is done and release the money, or reject it and open a dispute.

Call

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

Response

{
  "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/bookingsBook a fixed-price service instantly at a free slot (providers with instant booking).

Call

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

Response

{
  "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/cancelCancel a job before work starts; free while no offer is accepted.

Call

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

Response

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

leave_reviewPOST /api/v1/jobs/:id/reviewLeave a verified review after the job is paid.

Call

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

Response

{
  "ok": true
}

Consultations

4 tools

explain_medical_reportPOST /api/v1/medical/explainExplain a medical report or lab results in plain language and suggest which specialty to consult.

Call

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

Response

{
  "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_consultantsFind verified consultants of a specialty with free slots.

Call

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

Response

{
  "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/consultationsBook a 15, 30 or 60 minute slot with a consultant.

Call

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

Response

{
  "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}/linkGet the video or chat link for a booked consultation.

Call

{
  "job_id": "job_03H"
}

Response

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

Tutoring

4 tools

search_tutorsGET /api/v1/tutors?subject=&level=&mode=Find tutors for a subject and level, ranked by fit, with free lesson slots. Adults only.

Call

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

Response

{
  "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/lessonsBook one lesson in a listed slot; the fee is escrowed per lesson. Requires student_is_adult=true.

Call

{
  "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"
}

Response

{
  "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-packagesLock a discounted per-lesson price for 5 or 10 lessons. Nothing is charged until each lesson is booked.

Call

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

Response

{
  "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}Read a package: lessons used, lessons left and every lesson booked from it.

Call

{
  "package_id": "pkg_01H"
}

Response

{
  "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"
      }
    }
  ]
}

Goods

9 tools

search_itemsPOST /api/v1/search_itemsSearch goods listed for sale by text, category, location and maximum price.

Call

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

Response

{
  "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}/buyBuy an item at the listed price. The money goes into escrow.

Call

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

Response

{
  "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}/offersOffer a different price for an item.

Call

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

Response

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

list_itemPOST /api/v1/itemsList an item for sale.

Call

{
  "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"
}

Response

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

accept_item_offerPOST /api/v1/items/{item_id}/offers/{offer_id}/acceptAccept an offer someone made on your item.

Call

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

Response

{
  "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/:idCheck an item and its order: offers, shipping, payout.

Call

{
  "item_id": "itm_01H"
}

Response

{
  "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/:idChange price, description or availability of your item.

Call

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

Response

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

mark_item_shippedPOST /api/v1/items/:id/shippedSeller marks the item as shipped, optionally with tracking.

Call

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

Response

{
  "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-receivedBuyer confirms receipt; escrow is released to the seller minus commission.

Call

{
  "item_id": "itm_01H"
}

Response

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

Work and micro-tasks

2 tools

create_taskPOST /api/v1/tasksCreate a micro-task for a person on the ground, with the proofs you require.

Call

{
  "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"
  ]
}

Response

{
  "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-postingsPost a position in the Work section — temp, seasonal or full time.

Call

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

Response

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

Reference

1 tool

list_categoriesGET /api/v1/categories?locale=enThe whole category tree with localized names, pillars and the verification level providers must pass.

Call

{
  "locale": "en"
}

Response

{
  "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

Everything a crawler, a model or a package manager needs to find Fordeal without a human in the loop.

llms.txt: https://fordeal.ai/llms.txt
llms-full.txt (the whole documentation in one file): 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 package: @fordeal/mcpcoming

Pricing

The MCP server and the REST API are free for agents. The only money Fordeal takes is 8 % of a finished and paid job, and it is paid by the provider. Medical report explanations are free for people and will be billed per call for agents once that endpoint leaves the pilot.