Skip to content
BlocMarket Docs

Quickstart

Start Services

Section titled “Start Services”
Terminal window
cd bloc_market
docker compose up -d db redis
export DATABASE_URL=postgres://postgres:postgres@localhost:5434/bloc_market
export REDIS_URL=redis://127.0.0.1:6380
export JWT_SECRET="$(openssl rand -base64 48)"
cargo run -p bloc-api

The API listens on http://localhost:8090. Wait for Listening on 0.0.0.0:8090 in the logs.

Verify Health

Section titled “Verify Health”
Terminal window
curl http://localhost:8090/health        # 200, "ok"
curl http://localhost:8090/health/db     # 200, database info
curl http://localhost:8090/health/redis  # 200, "PONG"
curl http://localhost:8090/ready         # 200 (requires DB + Redis)

Register a User

Section titled “Register a User”
Terminal window
curl -X POST http://localhost:8090/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "password": "SecurePass123!",
    "full_name": "Developer"
  }'

Log in to get tokens:

Terminal window
curl -X POST http://localhost:8090/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "dev@example.com", "password": "SecurePass123!" }'

The response returns a flat { "access_token", "refresh_token" }. Save the access token:

Terminal window
TOKEN="<returned-jwt-token>"

Create a Property

Section titled “Create a Property”
Terminal window
curl -X POST http://localhost:8090/api/v1/properties \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "title": "123 Main Street",
    "description": "Detached residential property",
    "latitude": 51.5074,
    "longitude": -0.1278,
    "area_sqm": 150.0,
    "property_type": "residential"
  }'

Responses use a { "data": { ... } } envelope. Note the property id from the response.

Create a Bloc

Section titled “Create a Bloc”
Terminal window
curl -X POST http://localhost:8090/api/v1/blocs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "Riverside Assembly",
    "description": "Mixed-use development bloc"
  }'

Add Property to Bloc

Section titled “Add Property to Bloc”
Terminal window
curl -X POST http://localhost:8090/api/v1/blocs/<bloc_id>/properties \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "property_id": "<property_id>"
  }'

Place a Bid

Section titled “Place a Bid”
Terminal window
curl -X POST http://localhost:8090/api/v1/bids \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "bloc_id": "<bloc_id>",
    "amount": 500000,
    "currency": "GBP"
  }'

Search Properties (Spatial)

Section titled “Search Properties (Spatial)”
Terminal window
curl "http://localhost:8090/api/v1/properties/search?lat=51.5074&lng=-0.1278&radius=1000" \
  -H "Authorization: Bearer $TOKEN"

Paginated endpoints accept page (default 1) and per_page (default 20, max 100).

Explore the API

Section titled “Explore the API”

If Swagger UI is enabled (default in development):

Terminal window
open http://localhost:8090/api-docs/ui/

Next Steps

Section titled “Next Steps”