How it works

The world in plain words: who the dealers and the drivers are, how they decide, and where your margin comes from.

Read this to understand the game and to find your strategy. Your agent reads the rules and the handbook, which have every detail for your code. Where this page and the rules differ, the rules are correct.

The week

A game is one simulated week of car deliveries in Finland, from Monday to the next Monday.

Dealers send about 1,000 price requests, from Monday 08:00 to Friday 18:00.
Cars move between 30 towns, from Helsinki to Rovaniemi. Drive times are real: Helsinki to Tampere takes about 2 hours, Helsinki to Oulu about 6.5.
Every deadline is at 20:00 on a business day. Dealer sites open for short hours on Saturday and close on Sunday.
The next Monday is the last business day. The world then runs on to Wednesday 22:00, so late cars can still arrive.
Each week draws its own drivers and prices. Up to level 6, a week has up to 20% fewer or more drivers than average, and a competitor up to 10% cheaper or dearer. Levels 7 and 8 have far fewer drivers and a dearer competitor (Eight levels).

Dealers and prices

A dealer asks you for a price for one car, or for two in a trade-in. You have 15 minutes to answer.

A request is one car from a pickup to a delivery. When a customer trades in their old car, it is two cars for one price: the new car out and the old car back.
A request offers up to three delivery options: the same day, the next business day, or within three business days. Each option has a deadline and a list price, a public price by distance.
You quote a price for each option you want to sell. The dealer chooses one option or buys from the competitor.
A request also shows a typical fee: about what a driver is usually paid for this work. Some drivers take less, and some need more.
You do not have to win every car. A quote that loses costs nothing. To decline a car, quote a very high price. A request that you do not answer makes that dealer a little less willing to accept your prices.

The competitor

Another transport company quotes on every request. The dealer buys from whichever of you offers the better deal.

The dealer compares the price of each option with the competitor’s price and with what the speed of that option is worth to it.
Up to level 6, the competitor’s prices are near the list price. At levels 7 and 8 they are about 25% and 40% above it. They differ by lane and by day, and they change during the week.
The competitor reacts to you. When you win most of a dealer’s orders, it lowers its prices for that dealer.
Dealers remember you. A late or undelivered car makes a dealer accept only lower prices from you. Each car you deliver on time wins back a little.
You never see the competitor’s prices. You learn them from the quotes you win and lose.

Drivers and fees

You do not employ drivers. You post a gig with a fee, and a freelance driver takes it when the fee is worth their time.

Drivers live in towns across Finland. Not every driver works every day, and you cannot see who does.
A gig costs a driver their time on the road, the trip to the pickup, and the trip home by public transport. Thus the same car costs a driver who lives near the delivery much less than one who lives far away.
Evening, weekend and private-address work needs a higher fee. A far morning pickup can need a night away, and the driver wants that paid too.
You set a fee schedule: the opening fee and how it rises while nobody takes the gig. You can change it or withdraw the gig until a driver books it.
Drivers learn how your fees rise. If your gigs always rise, drivers wait for the raise. Close to the pickup they wait less, because another driver may take the gig.
A driver gets a notification for a new gig near their home. Most views come in the first minutes after you post.
A driver can drop a booking, most often when the fee only just paid them. The gig is then open again. You can also release a booked driver before they leave, for a fee.

On time

An order is on time when every car in it arrives by its deadline. If fewer than 90% of your orders are on time, you are not ranked. A team that wins no order is not ranked.

A driver books a gig only when they can reach every stop in time. A car with a 7-hour drive whose delivery window ends at 20:00 gets no driver after 13:00.
Drivers need time to see a gig and to reach the pickup. A high fee shortly before the pickup usually finds nobody, so raise the fee early.
When a car still has no driver 3 hours before its last possible pickup, your system gets a warning. After that, only a higher fee or a direct offer finds a driver.
A late car must still arrive, and the dealer gets part of the price back (The money).

Notes and changes

Many requests carry a note from the dealer, in Finnish, Swedish or English. Some notes change when or how a car can move.

A note can say that the car is ready only at 14:00, that the site closes early, or that the car needs plates. The world follows the note whether your system reads it or not.
When a driver arrives before the car is ready, or without what the car needs, the visit fails. You pay at least €25 and post the car again.
Some cars have their own needs. A premium car needs an experienced driver, and a manual car a driver with that licence. An electric car with low charge needs a charging stop.
After you win an order, the dealer can send the car to another place or cancel the order.

Two cars, one driver

The cheapest driver for a car is often one who already drives another of your cars nearby.

One gig can hold several cars, in a fixed order of stops, with up to 12 hours of driving. For a driver who already has one of your cars, a second car costs only the extra time and tickets.
A direct offer sends a gig to one driver for 10 minutes, at a fee you choose. A driver who reads it takes it when the fee pays for the work. In the app, the same driver might wait for a raise.
Each driver gets at most three offers a day. No driver reads an offer between 23:00 and 07:00.

The money

Your score is your gross margin: what dealers pay for the cars you deliver, less what you pay drivers, refunds and other costs.

A late car gives part of its price back to the dealer:

Up to 2 hours late: 10% back
2 to 24 hours late: 25% back
Up to two business days late: 50% back
Later: The whole price back, and the car must still arrive
Not delivered at the end: No price, and a penalty of twice the price

A failed visit costs at least €25. A premium car with a driver who is not experienced costs a €150 fine. An electric car without a needed charging stop costs a €100 fine. All amounts are game euros.

Eight levels

Practice weeks come in eight levels. Each level adds one rule, and no level is locked. The final is level 8.

Levels 1 to 3 are the drivers: you set fees, and every quote wins. Levels 4 to 6 add the market: a competitor, dealer notes and events that nobody announces. Levels 7 and 8 are a driver shortage, where you must choose which cars to win. Start low to find a fault in one part, then go up.

PostingOne car per gig, at one fixed fee. Every quote wins.
MarketFees that rise over time. Drivers learn how your fees rise.
NetworkSeveral cars per gig, and offers to one driver.
QuotesThe competitor. From here, you can lose an order on price.
FullDealer notes, changes of plan and weather.
SurprisesEvents that nobody announces. Every week the competitor is down in one region for a working day, and its dealers turn to a dearer backup. Some weeks have a flu among the drivers, or a yard full of cars from one dealer group.
ShortageA third of the drivers, and a dearer competitor. List prices and typical fees stay those of a normal week. You can win more cars than drivers can move on time, so you must choose your cars. Every week has all three events of level 6.
TrustThe shortage of level 7, and some towns lose nearly all of their drivers. The competitor is dearer still, and on one working day each week it quotes far lower everywhere. Nobody announces that day. Each dealer accepts higher prices from a team that delivers to it on time, and a late order undoes much of that.

This list says what each level adds. The rules have every number: how many drivers, how much dearer the competitor is, and what an order on time is worth.

How practice runs

In practice, your system moves the clock. The week waits while your system thinks.

Create a week. Your system asks our server for a practice week at a level, from a seed if you name one.
Move the clock. Your system moves the week to a minute, or to the next event of a kind it names, for example the next price request. The week then stops again.
Read what happened. Each move returns every event since the last move: requests, orders won, bookings, deliveries and money.
Act. Your system sends its quotes, gigs and offers with the next move. The world applies them at the current minute, then moves the clock.
Study the week. At the end, read the score. The reveal shows what a dispatcher learns from the week.

One request is one step. The starter sends 1,000 to 1,450 requests in a level 6 week, and 1,891 in the handbook’s level 8 week. That level 8 week takes about 2 seconds on a quiet server, plus your network’s round trip for each request.
The same seed, level and actions give the same week, to the cent. Thus play two versions of your system on the same seeds to compare them.
A copy of a week at any minute has the same future. Thus you can try two decisions from one moment.
The teams that practise share our server’s speed. A team gets up to 1,000 requests a second, about 170 when 60 teams practise, and 20 while a final or a test final runs.
A team holds at most 8 practice weeks that have not ended. A week that has ended holds no place.
A ranking run is a practice week whose seed our server chooses. You cannot copy or reveal it, and a run that you delete still counts.

How the final runs

In the final, the clock runs by itself. Your system must keep up with it.

Before the start. The final starts on Sunday at 09:00. Start your system with the kit’s --final option at any time before 09:00. From 08:30 the starter gets your copy of the final week and the start time from our server, and waits for the start. Your team page says when your system is connected.
At the start. The clock starts for every team at once. Events come to your system on a live stream, as they happen.
During the week. Your system answers by itself, with quotes, gigs and offers. Nobody can pause, move or copy the week.
At the end. The week ends on the Wednesday at 22:00, about 34 minutes after the start. Our server then plays every team’s week again from its log and checks each score.

A weekday hour from 06:00 to 22:00 takes 18 real seconds, and a night hour 3 seconds. Thus the 15 minutes to answer a request are 4.5 real seconds in the day.
Your system can send 20 actions and 50 reads a second. A request over that limit gets the answer 429, which costs nothing. The kits wait for the next free slot.
When the stream breaks, it connects again from the last event that it received, so it misses no event.
When your system stops, the week goes on without it. Your gigs keep their fees, drivers keep driving, and requests go to the competitor.
Start your system again at once. It reads the week’s state and events, rebuilds what it knows, and goes on. The kit’s starter does this.
When our server restarts, the clock stops while it is down, and the final ends that much later. The kits treat 20 seconds with no answer, or an answer 502, 503 or 504, as a break. The starter then waits 5 seconds and connects again.
Every team plays its own copy of the same week, with the same requests, drivers and random events. Thus only your decisions change your score.
Test finals run the same way, on Saturday at 14:00 and 20:00 and on Sunday at 01:00. The ones at 20:00 and 01:00 play a whole week and take about 34 minutes, as the final does. Use them to check that your system keeps up.

The handbook has the commands and the API for each step.

Where to start

There is no recipe. These facts about the world are worth your time.

Choose your cars: Some cars are cheap to move, for example when a driver lives near the delivery. Some are expensive, for example a same-day car to the far north. Price to win the good ones.
Learn all week: The competitor’s prices change during the week and react to your wins. Learn from your own wins and losses as the week goes on.
Know your drivers: A driver’s cost depends on where they are, where they live and what else they do that day.
Post in time: A fee raised late usually finds nobody. Drivers also wait when they expect the fee to rise.
Combine cars: One gig with two cars can cost less than two gigs.
Read the notes: A note can change when a car is ready or when a site closes.
Test on many weeks: One week is noisy. Compare two versions of your system on the same 10 or 20 weeks.

For your agent

Give your agent one link: llms.txt. It leads to the documents below, in Markdown.

llms.txt: The challenge in one paragraph, and links to everything below
Handbook: The world, the API and the kits, in detail
Rules: Every rule. Where any page differs, the rules are correct
API reference: Every route, event and limit
The kit: The TypeScript and Python kits, with their starters