# GeekAgent: parts from China, ordered by your agent

> A service for AI agents. You send a list of parts (electronic components, mechanical parts, modules), we source them in China, consolidate, and ship worldwide to your human's address. You get a quote with prices and delivery dates as JSON, place the order, and your human pays the invoice by a link.

Base URL: https://geekagent.ai
Format: JSON over HTTPS. Every response has a `next_step` field that tells you what to do next. Errors come as `{"error": "...", "details": [...]}`.

**Test mode.** The service is in its first stage: prices and delivery dates are placeholders, no payment is collected and nothing is shipped. The whole flow already works, so you can integrate now.

**No account is needed to get a price.** Send a parts list and you get a quote right away. You sign in only when your human decides to order.

## 1. Send the parts list, get a quote (no account needed)

    curl -X POST https://geekagent.ai/api/v1/quotes -H "Content-Type: application/json" -d '{
      "destination_country": "DE",
      "shipping_method": "standard",
      "items": [
        {"mpn": "STM32F103C8T6", "manufacturer": "STMicroelectronics", "qty": 50, "package": "LQFP-48"},
        {"mpn": "GRM188R71H104KA93D", "qty": 1000, "description": "0.1uF 50V X7R 0603", "allow_substitutes": true},
        {"mpn": "NEMA17-42x48", "qty": 4, "description": "Stepper motor 1.8deg 2A", "link": "https://example.com/item/123", "max_unit_price_usd": 9.5}
      ]
    }'

### Parts list format

`items` is a list of 1 to 500 objects, one per part:

| field | type | required | meaning |
|---|---|---|---|
| `mpn` | string | yes | Manufacturer part number, or the most exact name you have |
| `qty` | integer | yes | Pieces, 1 to 1000000 |
| `manufacturer` | string | no | Maker or brand |
| `description` | string | no | Key parameters in words: value, voltage, size, material |
| `package` | string | no | Package or footprint, for example `0603`, `LQFP-48` |
| `link` | string | no | A reference page for exactly this part (datasheet, marketplace listing) |
| `max_unit_price_usd` | number | no | Your price ceiling per piece; lines above it are flagged `over_max_unit_price` |
| `allow_substitutes` | boolean | no | `true` if an equivalent part is acceptable. Default `false` |
| `note` | string | no | Anything else a buyer should know |

Unknown fields are rejected, so a typo never silently drops data. One line per distinct part: merge duplicates and add up `qty` yourself.

Other request fields: `destination_country` is the ISO 3166-1 alpha-2 code of the country to ship to (required). `shipping_method` is `express`, `standard` (default) or `economy`.

### The quote

    {
      "id": "q_Zk3...", "test_mode": true, "currency": "USD", "valid_until": "2026-11-17",
      "items": [{"line": 1, "mpn": "STM32F103C8T6", "qty": 50, "unit_price_usd": 1.9, "line_total_usd": 95.0,
                 "availability": "in_stock", "sourcing_days": [2, 4]}],
      "subtotal_usd": 95.0, "service_fee_usd": 9.5,
      "shipping": {"method": "standard", "cost_usd": 16.4, "est_weight_kg": 0.18},
      "total_usd": 120.9,
      "lead_time": {"sourcing_days": [4, 6], "transit_days": [9, 16], "total_days": [13, 22],
                    "estimated_delivery": {"earliest": "2026-11-23", "latest": "2026-12-02"}},
      "shipping_options": [{"method": "express", "cost_usd": 27.2, "total_days": [8, 14], "estimated_delivery": {...}}, ...]
    }

`lead_time.sourcing_days` covers buying, quality check and consolidation; `transit_days` is the carrier. Ranges are `[min, max]` calendar days. `shipping_options` shows the cost and dates of every method, so you can compare without asking again. A quote is valid for 7 days; `GET /api/v1/quotes/{id}` returns it again. Keep the `id`: it is how you order later, and anyone who has it can read the quote.

Show the total and the delivery dates to your human. Go on to the next steps only when they want to order.

## 2. Ordering? Sign in with your human's email

An account is needed only from here on. There are no passwords: an account is an email address, confirmed with a code.

    curl -X POST https://geekagent.ai/api/v1/auth/code -H "Content-Type: application/json" -d '{"email": "human@example.com"}'

We email a 6-digit code to that address. Use the email of the human who pays and receives the parts: invoices go there. Ask your human for the code (valid 15 minutes, 5 attempts), then:

    curl -X POST https://geekagent.ai/api/v1/auth/verify -H "Content-Type: application/json" -d '{"email": "human@example.com", "code": "123456"}'

The response has `api_key`. It is shown once: store it. Send it with every other request as `Authorization: Bearer <api-key>`. The first verification creates the account; repeating the two calls later signs in to the same account and gives a new key (old keys keep working).

## 3. Tell us who and where

    curl -X PUT https://geekagent.ai/api/v1/account -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{
      "name": "Jane Doe",
      "company": "Acme Robotics",
      "delivery_address": {
        "recipient": "Jane Doe",
        "phone": "+49 30 1234567",
        "country": "DE",
        "state": "Berlin",
        "city": "Berlin",
        "postal_code": "10115",
        "line1": "Invalidenstrasse 1",
        "line2": "c/o Acme Robotics"
      }
    }'

Required in `delivery_address`: `recipient`, `phone`, `country` (ISO 3166-1 alpha-2), `city`, `postal_code`, `line1`. Optional: `state`, `line2`. `name` and `company` are optional and appear on invoices. Ask your human; do not guess an address. `GET /api/v1/account` returns what is saved.

## 4. Order and invoice

    curl -X POST https://geekagent.ai/api/v1/orders -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"quote_id": "q_Zk3..."}'

Pass the `id` of the quote your human approved. This needs a saved delivery address in the same country the quote was calculated for. The response is the order with an invoice:

    "invoice": {"number": "GA-000042", "url": "https://geekagent.ai/invoice/...", "total_usd": 120.9, "status": "unpaid", "due": "2026-11-17", "emailed_to": "human@example.com"}

The invoice is emailed to the account address, and `invoice.url` is the same invoice as a web page. Give the link to your human. **A human always pays by the link; an agent never moves money.** One quote makes one order.

Then poll `GET /api/v1/orders/{id}` until `status` changes. `GET /api/v1/orders` lists all orders.

## Statuses

Order: `awaiting_payment` (the invoice is waiting for your human) → `paid`. Sourcing, shipping and tracking statuses arrive with the next stage.

## All endpoints

No key needed:

- `POST /api/v1/quotes`: `items`, `destination_country`, `shipping_method` · `GET /api/v1/quotes/{id}`
- `POST /api/v1/auth/code`: `{"email"}`, emails a code
- `POST /api/v1/auth/verify`: `{"email", "code"}`, returns `api_key`

With `Authorization: Bearer <api-key>`:

- `GET  /api/v1/account` · `PUT /api/v1/account`: `name`, `company`, `delivery_address`
- `POST /api/v1/orders`: `{"quote_id"}` · `GET /api/v1/orders` · `GET /api/v1/orders/{id}`

## Rules of the road

- Up to 60 quotes per hour from one IP address. One code request per email per minute, five per hour. If a request returns 429, wait as the message says.
- On 502, 503 or a network error we are restarting: wait a few seconds and repeat the same request.
- We do not source weapons, controlled or export-restricted items, or counterfeit parts.