sidequestpays 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,6 @@
1
+ from .client import SideQuest, SideQuestError
2
+ from .tools import TOOLS, run_tool
3
+ from .webhooks import verify_webhook
4
+
5
+ __all__ = ["SideQuest", "SideQuestError", "TOOLS", "run_tool", "verify_webhook"]
6
+ __version__ = "0.1.0"
@@ -0,0 +1,125 @@
1
+ import json
2
+ import os
3
+ import time
4
+ import urllib.error
5
+ import urllib.parse
6
+ import urllib.request
7
+ from typing import Any, Dict, List, Optional
8
+
9
+ DEFAULT_BASE_URL = "https://sidequestpays.com"
10
+ USER_AGENT = "sidequestpays-python/0.1.0"
11
+ TERMINAL_STATUSES = {"submitted", "approved", "paid", "disputed", "cancelled", "refunded"}
12
+
13
+
14
+ class SideQuestError(Exception):
15
+ def __init__(self, status: int, code: str, message: str):
16
+ super().__init__(f"{code}: {message}")
17
+ self.status = status
18
+ self.code = code
19
+ self.message = message
20
+
21
+
22
+ class SideQuest:
23
+ """Client for the SideQuest API.
24
+
25
+ Reads the key from the SIDEQUEST_API_KEY environment variable when api_key is not given.
26
+ """
27
+
28
+ def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, timeout: float = 30.0):
29
+ self.api_key = api_key or os.environ.get("SIDEQUEST_API_KEY")
30
+ self.base_url = (base_url or os.environ.get("SIDEQUEST_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
31
+ self.timeout = timeout
32
+
33
+ def _request(self, method: str, path: str, body: Optional[Dict[str, Any]] = None, query: Optional[Dict[str, Any]] = None, auth: bool = True) -> Any:
34
+ url = self.base_url + path
35
+ if query:
36
+ clean = {k: v for k, v in query.items() if v is not None}
37
+ if clean:
38
+ url += "?" + urllib.parse.urlencode(clean)
39
+ headers = {"accept": "application/json", "user-agent": USER_AGENT}
40
+ data = None
41
+ if body is not None:
42
+ data = json.dumps({k: v for k, v in body.items() if v is not None}).encode()
43
+ headers["content-type"] = "application/json"
44
+ if auth:
45
+ if not self.api_key:
46
+ raise SideQuestError(401, "missing_api_key", "Set SIDEQUEST_API_KEY or pass api_key. Get one with SideQuest.signup().")
47
+ headers["x-api-key"] = self.api_key
48
+ req = urllib.request.Request(url, data=data, headers=headers, method=method)
49
+ try:
50
+ with urllib.request.urlopen(req, timeout=self.timeout) as res:
51
+ raw = res.read()
52
+ return json.loads(raw) if raw else None
53
+ except urllib.error.HTTPError as e:
54
+ try:
55
+ err = json.loads(e.read()).get("error", {})
56
+ except Exception:
57
+ err = {}
58
+ raise SideQuestError(e.code, err.get("code", "http_error"), err.get("message", str(e))) from None
59
+ except urllib.error.URLError as e:
60
+ raise SideQuestError(0, "network_error", str(e.reason)) from None
61
+
62
+ @classmethod
63
+ def signup(cls, company: str, email: str, base_url: Optional[str] = None) -> Dict[str, Any]:
64
+ """Create a requester account. The returned api_key is shown once."""
65
+ return cls(api_key="", base_url=base_url)._request("POST", "/v1/requesters", {"company": company, "email": email}, auth=False)
66
+
67
+ def templates(self) -> List[Dict[str, Any]]:
68
+ return self._request("GET", "/v1/templates", auth=False)
69
+
70
+ def balance(self) -> Dict[str, Any]:
71
+ return self._request("GET", "/v1/balance")
72
+
73
+ def top_up(self, amount_usd: float) -> Dict[str, Any]:
74
+ """Owner key only. Returns a checkout_url a person pays to add prepaid balance."""
75
+ return self._request("POST", "/v1/balance/topup", {"amount_usd": amount_usd})
76
+
77
+ def create_quest(
78
+ self,
79
+ template: str,
80
+ title: str,
81
+ reward_usd: float,
82
+ details: Optional[Dict[str, Any]] = None,
83
+ lat: Optional[float] = None,
84
+ lng: Optional[float] = None,
85
+ zip: Optional[str] = None,
86
+ country: Optional[str] = None,
87
+ language: Optional[str] = None,
88
+ funding: Optional[str] = None,
89
+ success_url: Optional[str] = None,
90
+ cancel_url: Optional[str] = None,
91
+ ) -> Dict[str, Any]:
92
+ """Post a paid quest. Returns {quest, ...}; includes checkout_url when a person must pay first."""
93
+ return self._request("POST", "/v1/quests", {
94
+ "template": template, "title": title, "reward_usd": reward_usd, "details": details,
95
+ "lat": lat, "lng": lng, "zip": zip, "country": country, "language": language,
96
+ "funding": funding, "success_url": success_url, "cancel_url": cancel_url,
97
+ })
98
+
99
+ def get_quest(self, quest_id: str) -> Dict[str, Any]:
100
+ return self._request("GET", f"/v1/quests/{urllib.parse.quote(quest_id)}")
101
+
102
+ def list_quests(self, status: Optional[str] = None, limit: Optional[int] = None) -> List[Dict[str, Any]]:
103
+ return self._request("GET", "/v1/quests", query={"status": status, "limit": limit})
104
+
105
+ def approve_quest(self, quest_id: str, rating: Optional[int] = None) -> Dict[str, Any]:
106
+ return self._request("POST", f"/v1/quests/{urllib.parse.quote(quest_id)}/approve", {"rating": rating})
107
+
108
+ def dispute_quest(self, quest_id: str, reason: str) -> Dict[str, Any]:
109
+ return self._request("POST", f"/v1/quests/{urllib.parse.quote(quest_id)}/dispute", {"reason": reason})
110
+
111
+ def cancel_quest(self, quest_id: str) -> Dict[str, Any]:
112
+ return self._request("POST", f"/v1/quests/{urllib.parse.quote(quest_id)}/cancel", {})
113
+
114
+ def set_webhook(self, url: str) -> Dict[str, Any]:
115
+ """Returns a signing secret once. Verify deliveries with sidequestpays.verify_webhook."""
116
+ return self._request("PUT", "/v1/webhook", {"url": url})
117
+
118
+ def wait_for_quest(self, quest_id: str, timeout: float = 86400, poll_every: float = 60) -> Dict[str, Any]:
119
+ """Poll until the quest has proof or reaches a final state. Webhooks are better for long waits."""
120
+ deadline = time.monotonic() + timeout
121
+ while True:
122
+ q = self.get_quest(quest_id)
123
+ if q.get("status") in TERMINAL_STATUSES or time.monotonic() >= deadline:
124
+ return q
125
+ time.sleep(poll_every)
File without changes
@@ -0,0 +1,53 @@
1
+ from typing import Any, Dict, List, Optional, Tuple, Type
2
+
3
+ from ..client import SideQuest
4
+ from ..tools import TOOLS, run_tool
5
+
6
+ _TYPES: Dict[str, Any] = {"string": str, "number": float, "integer": int, "boolean": bool, "object": dict, "array": list}
7
+
8
+
9
+ def _model(name: str, schema: Dict[str, Any]) -> Type[Any]:
10
+ from pydantic import Field, create_model
11
+
12
+ required = set(schema.get("required", []))
13
+ fields: Dict[str, Tuple[Any, Any]] = {}
14
+ for key, prop in schema.get("properties", {}).items():
15
+ typ = _TYPES.get(prop.get("type", "string"), str)
16
+ desc = prop.get("description", "")
17
+ if prop.get("enum"):
18
+ desc = (desc + " One of: " + ", ".join(prop["enum"])).strip()
19
+ if key in required:
20
+ fields[key] = (typ, Field(..., description=desc))
21
+ else:
22
+ fields[key] = (Optional[typ], Field(None, description=desc))
23
+ return create_model("".join(p.title() for p in name.split("_")) + "Input", **fields)
24
+
25
+
26
+ def sidequest_tools(client: Optional[SideQuest] = None, read_only: bool = False) -> List[Any]:
27
+ """SideQuest tools for CrewAI: Agent(tools=sidequest_tools())."""
28
+ from crewai.tools import BaseTool
29
+
30
+ sq = client or SideQuest()
31
+ out = []
32
+ for t in TOOLS:
33
+ if read_only and not t["read_only"]:
34
+ continue
35
+ tool_name = t["name"]
36
+
37
+ def _run(self: Any, _name: str = tool_name, **kwargs: Any) -> str:
38
+ return run_tool(sq, _name, {k: v for k, v in kwargs.items() if v is not None})
39
+
40
+ cls = type(
41
+ "".join(p.title() for p in tool_name.split("_")) + "Tool",
42
+ (BaseTool,),
43
+ {
44
+ "__module__": __name__,
45
+ "__annotations__": {"name": str, "description": str, "args_schema": Type[Any]},
46
+ "name": tool_name,
47
+ "description": t["description"],
48
+ "args_schema": _model(tool_name, t["input_schema"]),
49
+ "_run": _run,
50
+ },
51
+ )
52
+ out.append(cls())
53
+ return out
@@ -0,0 +1,27 @@
1
+ from typing import Any, List, Optional
2
+
3
+ from ..client import SideQuest
4
+ from ..tools import TOOLS, run_tool
5
+
6
+
7
+ def sidequest_tools(client: Optional[SideQuest] = None, read_only: bool = False) -> List[Any]:
8
+ """SideQuest tools for LangChain and LangGraph: llm.bind_tools(sidequest_tools())."""
9
+ from langchain_core.tools import StructuredTool
10
+
11
+ sq = client or SideQuest()
12
+ out = []
13
+ for t in TOOLS:
14
+ if read_only and not t["read_only"]:
15
+ continue
16
+
17
+ def call(_name: str = t["name"], **kwargs: Any) -> str:
18
+ return run_tool(sq, _name, kwargs)
19
+
20
+ out.append(StructuredTool.from_function(
21
+ func=call,
22
+ name=t["name"],
23
+ description=t["description"],
24
+ args_schema=t["input_schema"],
25
+ infer_schema=False,
26
+ ))
27
+ return out
@@ -0,0 +1,28 @@
1
+ import json
2
+ from typing import Any, List, Optional
3
+
4
+ from ..client import SideQuest
5
+ from ..tools import TOOLS, run_tool
6
+
7
+
8
+ def sidequest_tools(client: Optional[SideQuest] = None, read_only: bool = False) -> List[Any]:
9
+ """SideQuest tools for the OpenAI Agents SDK: Agent(tools=sidequest_tools())."""
10
+ from agents import FunctionTool
11
+
12
+ sq = client or SideQuest()
13
+ out = []
14
+ for t in TOOLS:
15
+ if read_only and not t["read_only"]:
16
+ continue
17
+
18
+ async def invoke(_ctx: Any, args_json: str, _name: str = t["name"]) -> str:
19
+ return run_tool(sq, _name, json.loads(args_json or "{}"))
20
+
21
+ out.append(FunctionTool(
22
+ name=t["name"],
23
+ description=t["description"],
24
+ params_json_schema=t["input_schema"],
25
+ on_invoke_tool=invoke,
26
+ strict_json_schema=False,
27
+ ))
28
+ return out
@@ -0,0 +1,235 @@
1
+ [
2
+ {
3
+ "name": "list_templates",
4
+ "description": "List the quest types a person can do for you. In person (needs lat/lng): verify_location, photo_proof, pickup_dropoff, inspect_item. Remote (anyone, anywhere, optionally limited to a country): phone_call, translation, check_ai_output. Call this first to pick the right template.",
5
+ "input_schema": {
6
+ "type": "object",
7
+ "properties": {},
8
+ "additionalProperties": false
9
+ },
10
+ "read_only": true
11
+ },
12
+ {
13
+ "name": "create_quest",
14
+ "description": "Post a paid real-world quest for a verified human quester near a location. If your prepaid balance covers the reward plus the 20% fee, it is paid instantly and opens to nearby questers right away. Otherwise it returns a checkout_url a person must pay first (use funding: 'balance' to fail instead). Use for tasks only a person on site can do. Account creation, social media posting, reviews, CAPTCHAs, and anything illegal are rejected.",
15
+ "input_schema": {
16
+ "type": "object",
17
+ "properties": {
18
+ "template": {
19
+ "type": "string",
20
+ "enum": [
21
+ "verify_location",
22
+ "photo_proof",
23
+ "pickup_dropoff",
24
+ "inspect_item",
25
+ "phone_call",
26
+ "translation",
27
+ "check_ai_output"
28
+ ],
29
+ "description": "Quest type from list_templates."
30
+ },
31
+ "title": {
32
+ "type": "string",
33
+ "maxLength": 140,
34
+ "description": "Short, clear instruction, e.g. 'Confirm Joe's Hardware at 12 Main St is open and photograph posted hours'."
35
+ },
36
+ "details": {
37
+ "type": "object",
38
+ "description": "Step-by-step instructions shown to the quester.",
39
+ "properties": {
40
+ "instructions": {
41
+ "type": "string",
42
+ "description": "What to do and what good proof looks like."
43
+ },
44
+ "steps": {
45
+ "type": "array",
46
+ "items": {
47
+ "type": "string"
48
+ },
49
+ "description": "Ordered steps."
50
+ },
51
+ "checklist": {
52
+ "type": "array",
53
+ "items": {
54
+ "type": "string"
55
+ },
56
+ "description": "Yes/no items the quester confirms."
57
+ },
58
+ "address": {
59
+ "type": "string",
60
+ "description": "Street address, if any."
61
+ }
62
+ }
63
+ },
64
+ "lat": {
65
+ "type": "number",
66
+ "description": "Latitude where the quest happens. Required for in-person templates, ignored for remote ones."
67
+ },
68
+ "lng": {
69
+ "type": "number",
70
+ "description": "Longitude where the quest happens. Required for in-person templates, ignored for remote ones."
71
+ },
72
+ "country": {
73
+ "type": "string",
74
+ "description": "Optional 2-letter ISO code. For remote quests, only questers in this country can claim it (for example NG for a quest needing local knowledge of Nigeria)."
75
+ },
76
+ "language": {
77
+ "type": "string",
78
+ "description": "Language needed, like Spanish or Yoruba. Required for translation quests."
79
+ },
80
+ "zip": {
81
+ "type": "string",
82
+ "description": "Optional ZIP or postal code of the quest location."
83
+ },
84
+ "reward_usd": {
85
+ "type": "number",
86
+ "minimum": 5,
87
+ "maximum": 1000,
88
+ "description": "What the quester earns. A 20% platform fee (minimum $2) is added on top."
89
+ },
90
+ "funding": {
91
+ "type": "string",
92
+ "enum": [
93
+ "auto",
94
+ "balance",
95
+ "checkout"
96
+ ],
97
+ "description": "auto (default): use balance if it covers the total, else return a checkout_url. balance: only use balance, error if short. checkout: always return a checkout_url."
98
+ }
99
+ },
100
+ "required": [
101
+ "template",
102
+ "title",
103
+ "reward_usd"
104
+ ],
105
+ "additionalProperties": false
106
+ },
107
+ "read_only": false
108
+ },
109
+ {
110
+ "name": "get_balance",
111
+ "description": "Check your prepaid balance, this key's spend caps, and how much it has spent in the last 24 hours. Call before posting quests to know whether they will be paid instantly.",
112
+ "input_schema": {
113
+ "type": "object",
114
+ "properties": {},
115
+ "additionalProperties": false
116
+ },
117
+ "read_only": true
118
+ },
119
+ {
120
+ "name": "get_quest",
121
+ "description": "Get one of your quests by id, including status and, once submitted, the quester's proof (photo URLs, GPS, timestamp, notes). Photo URLs need the same API key.",
122
+ "input_schema": {
123
+ "type": "object",
124
+ "properties": {
125
+ "quest_id": {
126
+ "type": "string",
127
+ "description": "The quest id returned by create_quest, like q_abc123."
128
+ }
129
+ },
130
+ "required": [
131
+ "quest_id"
132
+ ],
133
+ "additionalProperties": false
134
+ },
135
+ "read_only": true
136
+ },
137
+ {
138
+ "name": "list_quests",
139
+ "description": "List your quests, newest first. Optionally filter by status: draft, open, claimed, submitted, approved, disputed, paid, cancelled, refunded.",
140
+ "input_schema": {
141
+ "type": "object",
142
+ "properties": {
143
+ "status": {
144
+ "type": "string",
145
+ "enum": [
146
+ "draft",
147
+ "open",
148
+ "claimed",
149
+ "submitted",
150
+ "approved",
151
+ "disputed",
152
+ "paid",
153
+ "cancelled",
154
+ "refunded"
155
+ ],
156
+ "description": "Only return quests with this status. Omit for all."
157
+ },
158
+ "limit": {
159
+ "type": "number",
160
+ "minimum": 1,
161
+ "maximum": 200,
162
+ "description": "Maximum quests to return. Default 50."
163
+ }
164
+ },
165
+ "additionalProperties": false
166
+ },
167
+ "read_only": true
168
+ },
169
+ {
170
+ "name": "approve_quest",
171
+ "description": "Approve a submitted quest after checking its proof. This releases the secured reward to the quester. Optionally rate the quester 1 to 5. Submitted quests not approved or disputed within 72 hours are approved automatically.",
172
+ "input_schema": {
173
+ "type": "object",
174
+ "properties": {
175
+ "quest_id": {
176
+ "type": "string",
177
+ "description": "The quest id returned by create_quest, like q_abc123."
178
+ },
179
+ "rating": {
180
+ "type": "number",
181
+ "minimum": 1,
182
+ "maximum": 5,
183
+ "description": "Optional rating of the quester, 1 (poor) to 5 (excellent)."
184
+ }
185
+ },
186
+ "required": [
187
+ "quest_id"
188
+ ],
189
+ "additionalProperties": false
190
+ },
191
+ "read_only": false
192
+ },
193
+ {
194
+ "name": "dispute_quest",
195
+ "description": "Dispute a submitted quest whose proof does not meet the instructions. Funds stay held while a SideQuest reviewer decides. Give a specific reason.",
196
+ "input_schema": {
197
+ "type": "object",
198
+ "properties": {
199
+ "quest_id": {
200
+ "type": "string",
201
+ "description": "The quest id returned by create_quest, like q_abc123."
202
+ },
203
+ "reason": {
204
+ "type": "string",
205
+ "maxLength": 1000,
206
+ "description": "What the proof is missing or got wrong, specific enough for a reviewer to judge."
207
+ }
208
+ },
209
+ "required": [
210
+ "quest_id",
211
+ "reason"
212
+ ],
213
+ "additionalProperties": false
214
+ },
215
+ "read_only": false
216
+ },
217
+ {
218
+ "name": "cancel_quest",
219
+ "description": "Cancel a quest before a quester claims it. Paid quests are refunded in full. Claimed quests cannot be cancelled.",
220
+ "input_schema": {
221
+ "type": "object",
222
+ "properties": {
223
+ "quest_id": {
224
+ "type": "string",
225
+ "description": "The quest id returned by create_quest, like q_abc123."
226
+ }
227
+ },
228
+ "required": [
229
+ "quest_id"
230
+ ],
231
+ "additionalProperties": false
232
+ },
233
+ "read_only": false
234
+ }
235
+ ]
sidequestpays/tools.py ADDED
@@ -0,0 +1,46 @@
1
+ import json
2
+ from importlib import resources
3
+ from typing import Any, Dict, List, Optional
4
+
5
+ from .client import SideQuest, SideQuestError
6
+
7
+ TOOLS: List[Dict[str, Any]] = json.loads(resources.files(__package__).joinpath("tools.json").read_text())
8
+
9
+
10
+ def run_tool(client: SideQuest, name: str, args: Optional[Dict[str, Any]] = None) -> str:
11
+ """Run one SideQuest tool and return a JSON string for the model. Errors come back as text, not exceptions."""
12
+ a = dict(args or {})
13
+ try:
14
+ if name == "list_templates":
15
+ out: Any = client.templates()
16
+ elif name == "create_quest":
17
+ out = client.create_quest(**{k: a.get(k) for k in ("template", "title", "reward_usd", "details", "lat", "lng", "zip", "country", "language", "funding")})
18
+ elif name == "get_balance":
19
+ out = client.balance()
20
+ elif name == "get_quest":
21
+ out = client.get_quest(a["quest_id"])
22
+ elif name == "list_quests":
23
+ out = client.list_quests(a.get("status"), a.get("limit"))
24
+ elif name == "approve_quest":
25
+ out = client.approve_quest(a["quest_id"], a.get("rating"))
26
+ elif name == "dispute_quest":
27
+ out = client.dispute_quest(a["quest_id"], a["reason"])
28
+ elif name == "cancel_quest":
29
+ out = client.cancel_quest(a["quest_id"])
30
+ else:
31
+ return json.dumps({"error": {"code": "unknown_tool", "message": name}})
32
+ return json.dumps(out)
33
+ except SideQuestError as e:
34
+ return json.dumps({"error": {"code": e.code, "message": e.message}})
35
+ except KeyError as e:
36
+ return json.dumps({"error": {"code": "missing_argument", "message": f"{e.args[0]} is required"}})
37
+
38
+
39
+ def openai_tools() -> List[Dict[str, Any]]:
40
+ """Tool definitions for the OpenAI Chat Completions API (tools=[...])."""
41
+ return [{"type": "function", "function": {"name": t["name"], "description": t["description"], "parameters": t["input_schema"]}} for t in TOOLS]
42
+
43
+
44
+ def anthropic_tools() -> List[Dict[str, Any]]:
45
+ """Tool definitions for the Anthropic Messages API (tools=[...])."""
46
+ return [{"name": t["name"], "description": t["description"], "input_schema": t["input_schema"]} for t in TOOLS]
@@ -0,0 +1,19 @@
1
+ import hashlib
2
+ import hmac
3
+ import time
4
+ from typing import Optional, Union
5
+
6
+
7
+ def verify_webhook(raw_body: Union[str, bytes], signature_header: Optional[str], secret: str, tolerance_seconds: int = 300) -> bool:
8
+ """Check the SideQuest-Signature header (t=<unix>,v1=<hex>) against the raw request body."""
9
+ if not signature_header or not secret:
10
+ return False
11
+ parts = dict(p.split("=", 1) for p in signature_header.split(",") if "=" in p)
12
+ t, v1 = parts.get("t"), parts.get("v1")
13
+ if not t or not v1 or not t.isdigit():
14
+ return False
15
+ if abs(int(time.time()) - int(t)) > tolerance_seconds:
16
+ return False
17
+ body = raw_body.decode() if isinstance(raw_body, bytes) else raw_body
18
+ expected = hmac.new(secret.encode(), f"{t}.{body}".encode(), hashlib.sha256).hexdigest()
19
+ return hmac.compare_digest(expected, v1)
@@ -0,0 +1,120 @@
1
+ Metadata-Version: 2.5
2
+ Name: sidequestpays
3
+ Version: 0.1.0
4
+ Summary: Let AI agents hire verified people for real-world tasks. Python client and agent tools for SideQuest.
5
+ Project-URL: Homepage, https://sidequestpays.com
6
+ Project-URL: Documentation, https://github.com/uckhill/Sidequest/tree/main/sdk/python
7
+ Project-URL: Source, https://github.com/uckhill/Sidequest
8
+ Author-email: Crescent Harbor LLC <hello@sidequestpays.com>
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: agent tools,ai agents,crewai,human in the loop,langchain,mcp,openai agents,tasks
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: Software Development :: Libraries
15
+ Requires-Python: >=3.9
16
+ Provides-Extra: crewai
17
+ Requires-Dist: crewai>=0.80; extra == 'crewai'
18
+ Requires-Dist: pydantic>=2; extra == 'crewai'
19
+ Provides-Extra: langchain
20
+ Requires-Dist: langchain-core>=0.3; extra == 'langchain'
21
+ Provides-Extra: openai-agents
22
+ Requires-Dist: openai-agents>=0.2; extra == 'openai-agents'
23
+ Description-Content-Type: text/markdown
24
+
25
+ # sidequestpays
26
+
27
+ Let your AI agent hire a verified person for real-world tasks: confirm a store is open, photograph a shelf, inspect an item, call a business, or translate text. Rewards are paid upfront and held until your agent approves the proof.
28
+
29
+ ```bash
30
+ pip install sidequestpays
31
+ ```
32
+
33
+ ## Get an API key
34
+
35
+ ```python
36
+ from sidequestpays import SideQuest
37
+ print(SideQuest.signup(company="Acme Agents", email="ops@acme.com")) # api_key is shown once
38
+ ```
39
+
40
+ Then `export SIDEQUEST_API_KEY=sq_live_...`. New accounts can post quests up to $25 each and $100 a day until verified.
41
+
42
+ ## Use it directly
43
+
44
+ ```python
45
+ from sidequestpays import SideQuest
46
+
47
+ sq = SideQuest()
48
+ res = sq.create_quest(
49
+ template="phone_call",
50
+ title="Call Joe's Hardware (215-555-0100) and ask if they stock 3/8in brass fittings",
51
+ details={"instructions": "Ask for the price and whether they hold items for pickup."},
52
+ reward_usd=8,
53
+ country="US",
54
+ )
55
+ quest = sq.wait_for_quest(res["quest"]["id"]) # or use a webhook
56
+ print(quest["proof"]["notes"])
57
+ sq.approve_quest(quest["id"], rating=5)
58
+ ```
59
+
60
+ If your prepaid balance covers the reward plus fee, the quest opens instantly. Otherwise the response includes `checkout_url` for a person to pay.
61
+
62
+ ## Agent frameworks
63
+
64
+ Each returns the same 8 tools: list_templates, create_quest, get_balance, get_quest, list_quests, approve_quest, dispute_quest, cancel_quest. Pass `read_only=True` for only the tools that cannot spend money.
65
+
66
+ **OpenAI Agents SDK** (`pip install "sidequestpays[openai-agents]"`)
67
+ ```python
68
+ from agents import Agent, Runner
69
+ from sidequestpays.integrations.openai_agents import sidequest_tools
70
+
71
+ agent = Agent(name="Scout", instructions="Use SideQuest when a task needs a real person.", tools=sidequest_tools())
72
+ print(Runner.run_sync(agent, "Have someone check if Blue Bottle on Market St in SF is open right now.").final_output)
73
+ ```
74
+
75
+ **LangChain / LangGraph** (`pip install "sidequestpays[langchain]"`)
76
+ ```python
77
+ from langgraph.prebuilt import create_react_agent
78
+ from sidequestpays.integrations.langchain import sidequest_tools
79
+
80
+ agent = create_react_agent("anthropic:claude-sonnet-5-5", tools=sidequest_tools())
81
+ ```
82
+
83
+ **CrewAI** (`pip install "sidequestpays[crewai]"`)
84
+ ```python
85
+ from crewai import Agent
86
+ from sidequestpays.integrations.crewai import sidequest_tools
87
+
88
+ scout = Agent(role="Field scout", goal="Verify places in person", backstory="...", tools=sidequest_tools())
89
+ ```
90
+
91
+ **Raw tool calling** (OpenAI Chat Completions or Anthropic Messages)
92
+ ```python
93
+ from sidequestpays import SideQuest, run_tool
94
+ from sidequestpays.tools import openai_tools, anthropic_tools
95
+
96
+ tools = anthropic_tools() # or openai_tools()
97
+ result = run_tool(SideQuest(), tool_call.name, tool_call.input) # returns a JSON string for the model
98
+ ```
99
+
100
+ **MCP**: connect any MCP client to `https://sidequestpays.com/mcp` with header `X-API-Key`.
101
+
102
+ ## Webhooks
103
+
104
+ ```python
105
+ from sidequestpays import SideQuest, verify_webhook
106
+
107
+ secret = SideQuest().set_webhook("https://your.app/sidequest")["secret"] # shown once
108
+
109
+ # in your handler:
110
+ if not verify_webhook(request.body, request.headers["SideQuest-Signature"], secret):
111
+ return 400
112
+ ```
113
+
114
+ Events: quest.opened, quest.claimed, quest.released, quest.submitted, quest.paid, quest.disputed, quest.refunded, quest.cancelled.
115
+
116
+ ## Links
117
+
118
+ - API docs: https://github.com/uckhill/Sidequest/blob/main/docs/API.md
119
+ - llms.txt: https://sidequestpays.com/llms.txt
120
+ - Support: hello@sidequestpays.com
@@ -0,0 +1,13 @@
1
+ sidequestpays/__init__.py,sha256=nf9P3JtuqWigy1_8L4O4X_CKGhuDLlf0pRQddtEnevA,222
2
+ sidequestpays/client.py,sha256=CTQa-yX5TXUqLa5JVYOjKfXC1b4EZ4TWJRaK0ppC0Fw,5850
3
+ sidequestpays/tools.json,sha256=FsS1AV-UlCLYQVTjbeS9PVbAJgzscny56eHOZBufua8,7946
4
+ sidequestpays/tools.py,sha256=EAO5JoX0udF_TYETd0FAfSEHP1HlOjrPwQAA6DoO56o,2211
5
+ sidequestpays/webhooks.py,sha256=51ASZxuq8HTS7YjFaTfgiRGiA8jecLZsBhum9MaX81Q,853
6
+ sidequestpays/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
7
+ sidequestpays/integrations/crewai.py,sha256=4yQQue35nYc8MSTTNT8x0Z9zYzqRkNprvitupxoxR-I,2026
8
+ sidequestpays/integrations/langchain.py,sha256=WfI5rtNrej8_1n9DRwmI9qfguBLVJ3_9WNNM-lDeghk,833
9
+ sidequestpays/integrations/openai_agents.py,sha256=Lva-zq2G5hLRobAa1jsK9senBb1YBPFWnU3NQBOZTg8,876
10
+ sidequestpays-0.1.0.dist-info/METADATA,sha256=ncxES3-63BkypMf-0UCiDCdO1-gVjIZ35rB_kQHOFL8,4504
11
+ sidequestpays-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
12
+ sidequestpays-0.1.0.dist-info/licenses/LICENSE,sha256=RY05UdNGCzqWNZM3bNP6xh8uwsB6Hd9CYUCrR3fc5jY,1076
13
+ sidequestpays-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Crescent Harbor LLC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.