# Openpeptide API — Agent Skill

You have access to an on-chain product marketplace via a REST API. Use the endpoints below to browse and order products.

## Base URL

`https://openpeptides.ai`

## Endpoints

### `GET /api/list_products`
List all available products. No parameters. Returns an array of product objects.

### `GET /api/list_best_products`
List best-priced products filtered by cheapest supplier with certificate of analysis (COA). No parameters. Prefer this over `list_products`.

### `POST /api/order_product`
Place an order for one or more products. Returns an ETH deposit address, quote, and order ID.

Request body (JSON):
- `product_id` (string, optional) — the `id` of a single product (as a string). Use this or `product_ids`.
- `product_ids` (array of strings, optional) — list of product `id`s to order together. All products must be from the same vendor. Use this or `product_id`.
- `shipping_address` (object, required) — with the following fields:
  - `name` (string, required) — recipient full name
  - `address` (string, required) — full street address including city, state/province, and postal code
  - `country` (string, required) — country name or code
  - `email` (string, required) — contact email address
  - `phone` (string, required) — contact phone number with country code
- `currency` (string, optional) — payment currency: `"eth"` (default), `"usdt"`, `"usdc"`, or `"wbtc"`

Response fields:
- `order_id` — unique identifier for the order (use this for status polling)
- `deposit_address` — Ethereum address to send payment to
- `quote` — amount of currency required
- `currency` — the payment currency
- `product_ids` — list of product IDs in this order
- `token_contract` — (for ERC20 currencies) token contract address
- `token_decimals` — (for ERC20 currencies) token decimal places
- `gas_eth_needed` — (for ERC20 currencies) ETH needed for gas
- `instructions` — (for ERC20 currencies) human-readable deposit instructions

### `GET /api/check_order/{order_id}`
Check order status.

Path parameter:
- `order_id` (string, required) — the `order_id` returned by `order_product`

Response fields:
- `status` — one of: `awaiting_funds`, `submitting_order`, `order_submitted`, `failed`
- `message` — human-readable status message
- `trx_hash` — Ethereum transaction hash (present once submitted)
- `error` — error details (present if failed)

## Workflow

1. Call `GET /api/list_best_products` to show available products to the user. Display them in a readable format (name, quantity, price, supplier).
2. Ask the user which product(s) they want and collect their shipping details: name, full address, country, email, and phone number.
3. Call `POST /api/order_product` with `product_id` (single) or `product_ids` (multiple, same vendor) and the shipping address object.
4. **Print the deposit address and the payment amount clearly to the terminal** so the user can send payment. Example:
   ```
   Deposit address: 0x...
   Amount: 0.0042 ETH
   ```
5. **Poll `GET /api/check_order/{order_id}` every 15–30 seconds** and keep the user updated whenever the status changes:
   - `awaiting_funds` — tell the user funds have not arrived yet
   - `submitting_order` — tell the user the order is being submitted on-chain
   - `order_submitted` — tell the user the order succeeded and show the transaction hash
   - `failed` — tell the user the order failed and show the error message
6. Continue polling until the status reaches `order_submitted` or `failed`. Do not stop at `awaiting_funds` or `submitting_order`.