# NeedsDirt

> The contractor marketplace for dirt, fill, and dump sites. Agent-ready API available.

NeedsDirt is a web-based marketplace where contractors, excavators, landscapers, and construction companies connect over excess fill dirt, dump sites, and excavation material. Listings are sorted by distance from the user's location.

AI agents can create accounts, manage billing, and perform all marketplace actions via the REST API using scoped API keys.

## What NeedsDirt Does

Contractors post one of four listing types:

- **Dirt Available** — Excess fill dirt from excavation that needs to be removed
- **Dump Site Available** — Land that can legally accept clean fill, clay, or topsoil
- **Dirt Needed** — A job site that needs fill material for grading or construction
- **Dump Site Needed** — A contractor who needs a place to legally dump clean excavation material

Each listing shows quantity (cubic yards), price per yard (or free), address, and expiration date. Listings are sorted closest-first based on the viewer's location.

## Pricing

- First 10 users in each ZIP code get full access free — no credit card required
- $25/month subscription for full access after free spots are filled
- Unlimited listing posts included
- Optional in-app Stripe payments: 2.5% platform fee
- Cancel anytime

## Agent API

NeedsDirt has a full REST API for AI agents. No browser needed.

### Getting Started

1. `POST /api/agent/provision` — Request a provisioning token (email required, rate-limited)
2. `POST /api/agent/register` — Create an account using the provisioning token
3. `POST /api/agent/billing/setup` — Get a Stripe SetupIntent to securely add a payment method
4. `POST /api/agent/billing/confirm` — Confirm billing and receive a full-scope API key

### Authentication

All API requests use the `X-Agent-Key` header:
```
X-Agent-Key: nd_your_api_key_here
```

### Scopes

API keys have explicit scopes:
- `READ` — Browse listings, view details
- `WRITE` — Create, edit, delete listings
- `BILLING` — Manage payment methods and subscription

### Endpoints

- `GET /api/listings` — Browse active listings (supports lat/lng/maxMiles/type filters)
- `POST /api/listings` — Create a listing
- `GET /api/listings/{id}` — Get listing details
- `PATCH /api/listings/{id}` — Update a listing
- `DELETE /api/listings/{id}` — Delete a listing
- `GET /api/agent/keys` — List your API keys
- `POST /api/agent/keys` — Create a new API key
- `DELETE /api/agent/keys?id={keyId}` — Revoke a key

### Rate Limits

- 60 requests per minute per API key
- Provisioning endpoint: 3 requests per minute per IP
- Rate limit headers included in responses

### Full API Reference

See [llms-full.txt](https://needsdirt.com/llms-full.txt) for complete request/response schemas.

## Key Pages

- [Homepage](https://needsdirt.com) — Overview, how it works, pricing
- [Browse listings](https://needsdirt.com/browse) — All active listings, distance-sorted
- [Post a listing](https://needsdirt.com/post) — Create a new listing (requires subscription)
- [Subscribe](https://needsdirt.com/subscribe) — Start $25/month plan

## Technical

- Built with Next.js 15, PostgreSQL, Prisma, NextAuth
- Stripe Subscriptions + Stripe Connect for seller payments
- PWA-capable (installable on mobile)
- Agent API with scoped keys, rate limiting, and audit logging

## Contact

- support@needsdirt.com
- needsdirt.com