Creating a Contract

This guide explains how to create a contract for a Rider or Operator. A contract is an agreement to provide a service for a price specified by a value function. Contracts are sold at auction by their creator to the highest bidder, thus maximizing the value to the contract creator. Contracts can be traded. They can also be cancelled by their creator for a specified cancellation cost.

📚 Full API Documentation: For all endpoints, see https://api.opteverything.com/docs

Prerequisites

• You have created a user and are authenticated (see User Creation Guide)
• You have your authentication token
• You have a value function ID

Step 1: Create a Contract

A contract is an agreement to provide a service for a price specified by a value function. Contracts are sold at auction by their creator to the highest bidder, thus maximizing the value to the contract creator. Contracts can be traded. They can also be cancelled by their creator for a specified cancellation cost.

Endpoint

POST /ride-contract/contracts

Description

Create a ride service contract specifying origin/destination, value function, and cancellation costs. The contract is auctioned to operators; cancellation costs apply depending on when it’s cancelled (pre-start, purchased, or after trip start).

Required Information

Name	Type	Required	Description	Default
name	string	Yes	Name of the contract	—
contract_type	string	Yes	Type of contract (currently only RideShare is supported)	RideShare
value_function_id	integer	Yes	ID of the value function to use for pricing	—
start_position	object	Yes	Starting position coordinates (latitude, longitude)	—
end_position	object	Yes	Ending position coordinates (latitude, longitude)	—
max_cancellation_cost	float	Yes	Cancellation cost if cancelled after trip starts	—
pre_start_cancellation_cost	float	Yes	Cancellation cost if cancelled after assignment but before trip starts	—
contract_purchased_cancellation_cost	float	Yes	Cancellation cost if cancelled after purchase but before trip starts	—

Optional Information

Name	Type	Required	Description	Default
additional_details	object	No	Additional contract details	—
earliest_departure_time	datetime	No	Earliest departure time	—
latest_arrival_time	datetime	No	Latest arrival time	—

Example Request

curl -X POST "https://api.opteverything.com/ride-contract/contracts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -d '{
    "name": "Downtown Ride Share Contract",
    "contract_type": "RideShare",
    "value_function_id": 1,
    "start_position": {
      "latitude": 40.7128,
      "longitude": -74.0060
    },
    "end_position": {
      "latitude": 40.7589,
      "longitude": -73.9851
    },
    "max_cancellation_cost": 50.00,
    "pre_start_cancellation_cost": 25.00,
    "contract_purchased_cancellation_cost": 10.00,
    "earliest_departure_time": "2024-06-01T10:00:00Z",
    "latest_arrival_time": "2024-06-01T11:00:00Z",
    "additional_details": {
      "vehicle_type": "sedan",
      "accessibility": "wheelchair_accessible"
    }
  }'

Responses

Success (201 Created)

Status Code: 201 Created

{
  "contract_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "cargo_id": 0,
  "start_position_id": 0,
  "end_position_id": 0
}

Field	Type	Description
contract_id	string	Unique identifier for the newly created contract
cargo_id	integer	ID of the cargo associated with this contract
start_position_id	integer	ID of the starting position
end_position_id	integer	ID of the ending position

Error (400 Bad Request)

Status Code: 400 Bad Request

{
  "success": false,
  "error_code": "MISSING_REQUIRED_FIELD",
  "message": "name is a required field"
}

Field	Type	Description
success	boolean	Always false on error
error_code	string	Machine-readable error identifier
message	string	Human-readable error explanation

Contract Types

• RideShare: Standard ride-sharing service
• Delivery: Package delivery service
• Other: Custom contract types as defined in the system

Cancellation Costs

The contract defines three different cancellation costs:

1. max_cancellation_cost: Highest cost, applies when cancelling after trip has started
2. pre_start_cancellation_cost: Medium cost, applies when cancelling after assignment but before trip starts
3. contract_purchased_cancellation_cost: Lowest cost, applies when cancelling after purchase but before trip starts

Next Steps

Continue to the next guide: Order Creation

Or see the full API documentation.