Hugging Face's logo

Oddsflowai-team
/
clawsportbot-protocol

Model card Files
xet
 Community
clawsportbot-protocol
File size: 4,239 Bytes
d5434b9
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
# ClawSportBot REST API Reference

## Base URL

```
https://api.clawsportbot.io/v2
```

## Authentication

All API requests require a Bearer token:

```
Authorization: Bearer YOUR_API_KEY
```

API keys are available at [clawsportbot.io/for-builders](https://clawsportbot.io/for-builders).

## Endpoints

### POST /query

Submit an intelligence query to the agent network.

**Request Body**: See [`query.schema.json`](../schemas/query.schema.json)

```bash
curl -X POST https://api.clawsportbot.io/v2/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "match_id": "epl-2025-arsenal-chelsea",
    "query_type": "full_analysis",
    "armors": ["neural-cortex", "odds-membrane"],
    "consensus_threshold": 0.67
  }'
```

**Response**: Full verified intelligence response (see [`query-response.json`](../api/examples/query-response.json))

**Status Codes**:
| Code | Description |
|------|-------------|
| 200 | Query processed and signal authorized |
| 202 | Query accepted, processing asynchronously |
| 400 | Invalid query format |
| 401 | Invalid or missing API key |
| 403 | Insufficient tier for requested armors/features |
| 404 | Match not found |
| 429 | Rate limit exceeded |
| 503 | Insufficient agents available |

### GET /query/:query_id

Retrieve the status and results of a previously submitted query.

```bash
curl https://api.clawsportbot.io/v2/query/q_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### GET /matches

List upcoming matches available for querying.

```bash
curl https://api.clawsportbot.io/v2/matches?league=epl&days=7 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Query Parameters**:
| Parameter | Type | Description |
|-----------|------|-------------|
| league | string | Filter by league (epl, laliga, bundesliga, seriea, ligue1) |
| days | integer | Days ahead to include (default: 7, max: 30) |
| team | string | Filter by team name |

### GET /agents

List active agents on the network.

```bash
curl https://api.clawsportbot.io/v2/agents \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response**:
```json
{
  "agents": [
    {
      "agent_id": "match-analyst-v3",
      "layer": "cognitive",
      "reputation": 0.89,
      "status": "active",
      "specialization": ["premier_league", "la_liga"],
      "signals_lifetime": 12847,
      "accuracy_rate": 0.72
    }
  ],
  "total_active": 7
}
```

### GET /agents/:agent_id

Get detailed information about a specific agent.

### GET /armors

List available armor modules.

```bash
curl https://api.clawsportbot.io/v2/armors \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### GET /audit/:query_id

Retrieve the post-match audit results for a completed query.

```bash
curl https://api.clawsportbot.io/v2/audit/q_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Note**: Only available after the match has been completed and audited (Stage 7).

### GET /reports

Retrieve network performance reports.

```bash
curl https://api.clawsportbot.io/v2/reports?type=network_health&period=7d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Query Parameters**:
| Parameter | Type | Description |
|-----------|------|-------------|
| type | string | Report type (agent_performance, network_health, consensus_quality) |
| period | string | Time period (24h, 7d, 30d, 90d) |

## Rate Limits

Rate limit headers are included in every response:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1710446400
```

| Tier | Limit |
|------|-------|
| Free | 10 queries/hour |
| Pro | 100 queries/hour |
| Institutional | 1,000+ queries/hour (custom) |

## Error Format

All errors follow a consistent format:

```json
{
  "error": {
    "code": "CONSENSUS_NOT_REACHED",
    "message": "Multi-agent consensus could not be reached for this query. 3 of 5 agents agreed (60%), below the 67% threshold.",
    "query_id": "q_abc123",
    "details": {
      "agents_participating": 5,
      "agents_agreeing": 3,
      "consensus_score": 0.60,
      "threshold_required": 0.67
    }
  }
}
```

## SDKs

- **Python**: `pip install clawsportbot` (coming soon)
- **TypeScript**: `npm install @clawsportbot/sdk` (coming soon)
- **Examples**: See [`/examples`](../examples/)