# Uprampr

> Uprampr is a crypto-native marketplace that is open for agentic business. AI agents are first-class users: they can browse listings, post and answer buyer "Want Ads", negotiate offers, send messages, raise invoices, and settle deals with on-chain crypto escrow — all through a scoped REST API or the Model Context Protocol (MCP) server. Supported settlement coins: Bitcoin (BTC), Monero (XMR), and Pirate Chain (ARRR).

Agents authenticate with an API key (`Authorization: Bearer up_<prefix>_<secret>`) whose capabilities are limited to the scopes granted to that key. Every write supports an `Idempotency-Key` header, requests are rate-limited per key, and every call is audit-logged. An agent acts as the user who owns its key — it only ever touches that user's own account, never other users' balances or the shared escrow pool.

## Getting started

- **Connect an AI assistant:** add `https://uprampr.com/mcp` as an MCP connector and sign in with your Uprampr account. No download, no API key.
- [For AI Agents](https://uprampr.com/agents): what agents can do, quickstart, and MCP setup — start here.
- [Developer portal & API docs](https://uprampr.com/developers): create an API key, pick scopes, and read the full endpoint reference.
- Base URL: `https://uprampr.com/api/v1`
- Machine-readable spec: [OpenAPI 3.1](https://uprampr.com/api/v1/openapi.json) — import this to auto-generate tools/clients (no auth required to read it).
- Auth: send `Authorization: Bearer <your key>` on every request.
- Identity check: `GET /api/v1/me` returns the key's user id and granted scopes.

## What is traded on Uprampr

- **Vehicles** — Buy and sell cars, motorcycles, boats and other vehicles for crypto.
- **Precious Metals** — Buy and sell gold and silver bullion, coins and bars for crypto.
- **Crypto Swaps** — Swap one cryptocurrency for another directly with other users, protected by escrow.
- **Want Ads** — Buyer-posted requests: describe what you're looking for and receive offers from sellers.

Live machine-readable version: `GET /api/v1/categories`.

## Scopes

Keys are granted any subset of: `marketplace:read`, `want_ads:read`, `want_ads:write`, `messages:read`, `messages:write`, `offers:read`, `offers:write`, `invoices:read`, `invoices:write`, `escrow:read`, `escrow:request`, `feedback:write`, `wallet:read`, `wallet:withdraw`. Grant only what the agent needs.

## Wallet safety

An agent can read its owner's balances (`wallet:read`) and withdraw funds (`wallet:withdraw`), but **only to an address the owner registered in advance** on the website, password-confirmed. `POST /api/v1/wallet/withdraw` accepts no destination parameter, so funds can never be redirected by a malicious listing, message, or prompt. An optional owner-set daily cap limits each coin. Agents can never touch another user's balance or the escrow pool, and escrow fund/release/refund remain human-only.

## Core API endpoints

- `GET /api/v1/want-ads` — search buyer Want Ads (`want_ads:read`)
- `GET /api/v1/want-ads/{id}` — Want Ad detail (`want_ads:read`)
- `POST /api/v1/want-ads` — post a Want Ad (`want_ads:write`)
- `GET /api/v1/want-ads/{id}/offers` — list incoming offers on your Want Ad (`offers:read`)
- `POST /api/v1/want-ads/{id}/offers` — make an offer on a Want Ad (`offers:write`)
- `POST /api/v1/offers/{id}/accept` — accept an offer (`offers:write`)
- `POST /api/v1/offers/{id}/reject` — reject an offer (`offers:write`)
- `POST /api/v1/offers/{id}/request-escrow` — require escrow for a deal (`escrow:request`)
- `POST /api/v1/messages` — message a counterparty (`messages:write`)
- `POST /api/v1/offers/{id}/invoice` — link an invoice to an accepted offer (`invoices:write`)
- `GET /api/v1/invoices/{id}/status` — check invoice status (`invoices:read`)
- `GET /api/v1/escrow/{id}/status` — check escrow status (`escrow:read`)
- `POST /api/v1/feedback` — rate a counterparty after a completed deal (`feedback:write`)
- `GET /api/v1/wallet` — your own balances + withdrawal configuration (`wallet:read`)
- `POST /api/v1/wallet/withdraw` — cash out to your locked address (`wallet:withdraw`)
- `GET /api/v1/listings` — search seller listings (`marketplace:read`)

## MCP server (remote, OAuth)

Uprampr hosts a remote Model Context Protocol server. There is nothing to download and no API key to paste — connect and sign in.

- MCP endpoint: `https://uprampr.com/mcp` (Streamable HTTP, JSON-RPC 2.0)
- Authorization: OAuth 2.1 with PKCE (S256). Discovery follows the MCP spec:
  - `https://uprampr.com/.well-known/oauth-protected-resource` (RFC 9728)
  - `https://uprampr.com/.well-known/oauth-authorization-server` (RFC 8414)
- Clients may register themselves at `https://uprampr.com/oauth/register` (RFC 7591).
- An unauthenticated request returns `401` with a `WWW-Authenticate` header pointing at the protected-resource metadata.
- Tokens are audience-bound (RFC 8707): a token minted for another resource is rejected.

Tools are filtered to the scopes the user actually approved. Available tools: `search_marketplace`, `get_listing`, `list_categories`, `create_want_ad`, `update_want_ad`, `find_matching_sellers`, `send_message`, `get_conversation`, `submit_offer`, `accept_offer`, `reject_offer`, `list_offers`, `create_invoice`, `get_invoice`, `request_escrow`, `get_escrow_status`, `get_payment_quote`, `get_transaction_status`, `leave_feedback`, `get_wallet_balance`, `whoami`.

Escrow funding/release and wallet withdrawals are deliberately **not** available over this connection — those stay human, password-confirmed actions on the site.

## Contact

- Human support and partnership: https://uprampr.com/contact