RSE API Documentation

⚡ Integration Test Suite

Runs 31 end-to-end matching tests directly from this page against rse-api.com:5003. Each test posts a bid then verifies the LLM matching engine correctly accepts matching providers and rejects mismatched ones. All test data is labelled TEST: and cleaned up on completion.

Authentication

All endpoints (except /ping, /health, /stats, /register, /login) require authentication via Bearer token.

Authorization: Bearer <access_token>

Tokens are obtained from /login and expire after 24 hours. Use the Try It panels below — after a successful login, your token is automatically used for all authenticated requests.

RSE Seat NFTs

Provider access to /grab_job is gated by ERC-721 NFT ownership on Base (Ethereum L2).

Contract: 
                            0x151fEB62F0D3085617a086130cc67f7f18Ce33CE
                        
Network: Base mainnet (chain 8453)
OpenSea: 
                            opensea.io/collection/rse-seat
                        

Seat Types

Type	Purpose	Supply	Rate Limit
SEAT	Robot operator access (permanent)	100 minted	1/15 min

                        // How it works

                        The API calls isValidSeat(address) on the contract — a Solidity view function. This is a free read-only eth_call. No ETH is ever spent per request, no gas, no transaction. Results are cached for 15 minutes (matching the /grab_job rate limit), so the RPC is only hit once per rate-limit window per wallet.

                        Suppliers set their wallet address once via POST /set_wallet and never touch it again. They don't need a private key, don't sign anything, and don't pay gas. The wallet is just an address used to look up NFT ownership.

To get a seat: email mickeyshaughnessy@gmail.com with your wallet address. After receiving a seat, link it once with POST /set_wallet.

GET/ping

Check if the API is operational. No authentication required.

curl https://rse-api.com:5003/ping

{ "message": "Service Exchange API is operational" }

// Try It

GET/health

Detailed system health check including version and timestamp.

{ "status": "healthy", "timestamp": 1703001600, "service": "Service Exchange API", "version": "1.0.0" }

// Try It

GET/metrics

System performance metrics and request statistics.

{ "total_requests": 1542, "total_errors": 12, "endpoint_stats": { ... } }

// Try It

GET/stats

Public platform statistics. No authentication required.

{ "demand_signups": 42, "supply_signups": 18, "total_users": 60, "active_requests": 15, "completed_jobs": 127 }

// Try It

POST/register Step 1

Create a new user account. Choose demand (buyer) or supply (robot operator/provider).

Parameter	Type	Required	Description
`username`	string	Yes	Unique username (3-20 chars)
`password`	string	Yes	Min 8 characters
`user_type`	string	Yes	`"demand"` (buyer) or `"supply"` (provider)

curl -X POST https://rse-api.com:5003/register \
  -H "Content-Type: application/json" \
  -d '{"username": "robot_buyer_1", "password": "securepass123", "user_type": "demand"}'

// Try It — Register User

POST/login Step 2

Authenticate and receive an access token. The token is automatically stored for all authenticated requests.

Parameter	Type	Description
`username`	string	Your username
`password`	string	Your password

{ "access_token": "550e8400-e29b-41d4-a716-446655440000", "username": "robot_buyer_1" }

// Try It — Login

GET/account AUTH

Get account information, reputation score, and NFT seat status. Requires authentication.

{
  "username": "robot_operator_1",
  "stars": 4.5,
  "total_ratings": 12,
  "completed_jobs": 10,
  "reputation_score": 4.1,
  "wallet_address": "0x6B2D765cfB33Aa5736e96231eD078f9D01917A03",
  "seat_status": "valid",
  "seat_token_id": 7
}

Field	Values	Description
`wallet_address`	string or null	Linked Ethereum address
`seat_status`	"valid" \| "revoked" \| "no_seat" \| "no_wallet"	Current NFT seat state
`seat_token_id`	integer or null	Token ID of the active seat

// Try It

POST/set_wallet AUTH

Link an Ethereum/Base wallet address to your account. Required before /grab_job can verify your RSE Seat NFT. Supply-side users only. You only need to do this once.

Parameter	Type	Required	Description
`wallet_address`	string	Yes	Your Ethereum address (0x + 40 hex chars)

curl -X POST https://rse-api.com:5003/set_wallet \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"wallet_address": "0x6B2D765cfB33Aa5736e96231eD078f9D01917A03"}'

{ "message": "Wallet address linked", "wallet_address": "0x6B2D765cfB33Aa5736e96231eD078f9D01917A03" }

// Try It — Link Wallet

GET/my_bids AUTH

Get your outstanding (active) service requests.

{ "bids": [ { "bid_id": "b1234...", "service": "Autonomous lawn mowing, 0.5 acre lot", "price": 75, "status": "active" } ] }

// Try It

GET/my_jobs AUTH

Get your job history — completed and active jobs.

Field	Type	Description
`completed_jobs`	array	Last 10 completed jobs
`active_jobs`	array	Currently active jobs
`role`	string	"buyer" or "provider" for each job
`counterparty`	string	Username of the other party

// Try It

POST/submit_bid AUTH Step 3

Submit a robot service request as a buyer. Requires authentication.

Parameter	Type	Description
`service`	string or object	Robot task description or structured JSON
`price`	number	Price willing to pay
`currency`	string	"USD", "EUR", "BTC", etc.
`end_time`	integer	Unix timestamp when bid expires
`location_type`	string	"physical", "remote", or "hybrid"
`address`	string	Service location (for physical)

// Try It — Submit Robot Service Request

POST/grab_job SEAT Step 4

                        NFT Seat Required — when seat verification is enabled, your account must have a linked wallet (via /set_wallet) holding a valid, unrevoked RSE Seat NFT on Base. The API calls isValidSeat(address) on-chain before each match. If the Base RPC is unreachable, the check fails open (request proceeds).
                    

Match a robot operator with the best available job. Uses AI capability matching and reputation alignment. Rate-limited to 1/15min per seat.

Parameter	Type	Required	Description
`capabilities`	string	Yes	Robot capabilities offered
`location_type`	string	No	"physical", "remote", or "hybrid"
`address`	string	Conditional	Robot location (physical services)
`max_distance`	number	No	Max travel distance in miles (default: 10)

// Try It — Grab Robot Job

POST/reject_job AUTH

Reject a job assigned via /grab_job. Call immediately after receiving a match.

Parameter	Type	Description
`job_id`	string	ID of the job to reject
`reason`	string	Optional reason for rejection

// Try It

POST/sign_job AUTH Step 5

Complete and rate a job. Both buyer and provider must sign to mark complete.

Parameter	Type	Description
`job_id`	string	ID of the job to sign
`star_rating`	integer	Rating for the other party (1-5)

// Try It

POST/cancel_bid AUTH

Cancel a pending bid. Only the bid creator can cancel.

Parameter	Type	Description
`bid_id`	string	ID of the bid to cancel

// Try It

POST/nearby AUTH

Find robot service requests near a location.

Parameter	Type	Description
`address`	string	Search center location
`lat`	number	Latitude (alternative to address)
`lon`	number	Longitude (alternative to address)
`radius`	number	Search radius in miles (default: 10)

// Try It

GET/exchange_data AUTH Step 6

Comprehensive view of all public exchange data — bids, completed jobs, market stats.

Query Param	Type	Description
`category`	string	Filter by service category
`location`	string	Filter by location
`limit`	integer	Max results (default: 50, max: 200)
`include_completed`	boolean	Include completed jobs

// Try It

POST/chat AUTH

Send a direct message to another user. Optionally reference a job.

Parameter	Type	Description
`recipient`	string	Username of recipient
`message`	string	Message content
`job_id`	string	Optional: reference to related job

// Try It

POST/bulletin AUTH

Post a public message to the community bulletin board.

Parameter	Type	Description
`title`	string	Post title
`content`	string	Post content
`category`	string	"announcement", "question", "offer", "general"

// Try It

Error Responses

All errors use a consistent format:

{ "error": "Error message describing what went wrong" }

Code	Description
`200`	Success
`201`	Created (successful registration)
`204`	No Content (no matching jobs available)
`400`	Bad Request
`401`	Unauthorized (invalid or missing token)
`403`	Forbidden (seat verification failure)
`404`	Not Found
`500`	Internal Server Error

Rate Limiting

Most endpoints: 60 requests/minute per IP. /grab_job with seats: 1 request/15 min per seat.

// Navigation

⚡ Integration Test Suite

Authentication

RSE Seat NFTs

Seat Types

GET/ping

GET/health

GET/metrics

GET/stats

POST/register Step 1

POST/login Step 2

GET/account AUTH

POST/set_wallet AUTH

GET/my_bids AUTH

GET/my_jobs AUTH

POST/submit_bid AUTH Step 3

POST/grab_job SEAT Step 4

POST/reject_job AUTH

POST/sign_job AUTH Step 5

POST/cancel_bid AUTH

POST/nearby AUTH

GET/exchange_data AUTH Step 6

POST/chat AUTH

POST/bulletin AUTH

Error Responses

Rate Limiting

Get Started

💬 Inbox

Conversations

Select a conversation

New Message

📢 Community Bulletin

Recent Posts

Create New Post