1. Create an Account
Sign up at app.rivermarkets.com to create your account.
2. Generate an API Key
- Log in to your dashboard
- Navigate to Settings → API Keys
- Click Create API Key
- Copy and securely store your key — it will only be shown once
3. Install Required Packages
4. Make Your First Request
Test your API key by searching for markets. We support ticker search (Kalshi ticker, Polymarket condition_id/slug, river_id) and fuzzy search (“bitcoin”, “fed rates”).
import requests
API_KEY = "your_api_key"
BASE_URL = "https://api.rivermarkets.com/v1"
headers = {"x-api-key": API_KEY}
# Search for shutdown related markets on Polymarket
response = requests.get(
f"{BASE_URL}/markets/search",
headers=headers,
params={"q": "shutdown", "exchange": "POLYMARKET"}
)
for market in response.json()["results"]:
print(f"River ID: {market['river_id']}, Ticker: {market['slug']}")
5. Set Up a Subaccount
Subaccounts let you organize trading activity into separate containers — useful for segregating strategies, clients, or portfolios.
You can create them via the UI at Settings → Subaccounts or programmatically:
response = requests.post(
f"{BASE_URL}/subaccounts",
headers=headers,
json={"name": "My Trading Account"}
)
subaccount = response.json()
subaccount_id = subaccount["subaccount_id"]
Watch the video walkthrough to see how to create a subaccount, add a Polymarket account, and place your first trade. 6. Add Exchange Credentials
Exchange credentials can be added via the UI under Settings → Subaccounts
We use asymmetric encryption — your credentials are never transferred between services or stored in plain text. Credentials are deleted when you delete a subaccount.
Watch this walkthrough to see how to create a subaccount, add a Polymarket account. 7. Place Your First Order
Use the River ID from your market search to place an order:
response = requests.post(
f"{BASE_URL}/orders",
headers=headers,
json={
"subaccount_id": subaccount_id,
"river_id": 4552150, # From market search
"order_type": "LIMIT", # LIMIT or MARKET
"time_in_force": "GTC", # FOK, GTC, GTD, or IOC
"buy_flag": True, # True=buy, False=sell
"price": 0.50, # Limit price (0-1)
"qty": 10, # Number of contracts
}
)
order = response.json()
print(f"Order placed: {order['river_order_id']}")
8. Check Order Status
order_id = order['river_order_id']
response = requests.get(
f"{BASE_URL}/orders/{order_id}",
headers=headers
)
order_status = response.json()
print(f"Status: {order_status['status']}, Filled: {order_status['traded_qty']}/{order_status['qty']}")
| Status | Description |
|---|
pending_submission | Order received, awaiting processing |
submitted | Order sent to exchange |
partially_filled | Order partially executed |
filled | Order fully executed |
cancelled | Order cancelled |
rejected | Order rejected (see reject_reason) |
9. Cancel an Order
order_id = order['river_order_id']
response = requests.delete(
f"{BASE_URL}/orders/{order_id}",
headers=headers
)
if response.status_code == 202:
print(response.json())
Only orders with status submitted or partially_filled can be cancelled.
Rate Limits
- Standard: 100 requests/minute
- Premium: Contact support for higher limits
