# TAP Provider Protocol v0.1
## How supply platforms plug into the Teleport TAP Router

**Status:** Public draft for review. The PoPW trademark position was cleared on 16 Nov 2026 (Developer Platform PRD §10, R-1).
**Version:** `teleport.provider/0.1` (versioned separately from TAP)
**Date:** 2026-11-16
**Builds on:** TAP v0.3 (task schema, evidence origins, rejection reasons, outcome events §9), TAP v0.3.1 receipt levels, PoPW Canonical Encoding v0.1
**Decided by:** Developer Platform PRD v1, §7 (PP-1 to PP-22) and the §13 decisions of 16 Nov 2026
**Machine-readable:** `teleport-tap-provider-protocol-v0.1.schema.json` (JSON Schema 2020-12) · `teleport-tap-provider-protocol-v0.1-vectors.json` (signing and message vectors) · `teleport-tap-provider-protocol-v0.1-vectors.py` (regenerates and checks them)

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are used as in RFC 2119.

---

## 0. Summary

A **provider** is a platform that supplies people, robots, drones or devices for physical work: a human marketplace, a courier fleet, an imagery network, a robot fleet operator. This protocol lets a provider take work from the Teleport TAP Router **without Teleport writing code for it**.

The exchange, in one line:

```
offer → quote → accept → status → evidence → decision → receipt → payment cleared → payment sent
```

- **Teleport** owns the task, the requester relationship, the evidence chain, the verification decision and the **Teleport PoPW receipt** (Proof of Physical Work).
- **The provider** owns its performers. It finds one, gets the work done, sends the evidence back, and pays its performer.
- **Every message Teleport sends is signed** (ES256). Every call a provider makes is authenticated with its key and idempotent.
- **A provider never learns who the requester is**, and it learns the exact place only after it accepts.

The protocol has three ways in, sharing one state machine (§3):

| Mode | How offers reach the provider | For |
|---|---|---|
| **Push** (default) | Teleport POSTs signed events to the provider's events endpoint | Platforms with a backend |
| **Pull** | The provider polls `GET /provider/events` and `GET /provider/offers` | Platforms behind firewalls, scripts |
| **MCP** | The provider's agent uses the provider MCP tools | Agent-native networks |

---

## 1. Terms

| Term | Meaning |
|---|---|
| Router | Teleport's lane selection for a task (TAP v0.3 routing). It scores eligible lanes and makes offers. |
| Provider | A registered supply platform. It has one manifest, live and test keys, and a mode (`sandbox`, `dry_run`, `live`). |
| Lane | One provider as the router sees it: what it can do, where, how fast, at what assurance. |
| Offer | Teleport asking one provider to do one task. It has an id `ofr_…` and an expiry. |
| Quote | The provider's price and ETA for an offer. It has an id `qte_…` and a validity window. |
| Assignment | An accepted offer. It has an id `asg_…`; the work, evidence and decision hang off it. |
| Performer | The person, robot, drone or device that does the work. Teleport knows it only by a salted hash of the provider's `performerRef`. |
| Requester | Whoever posted the task to Teleport. Never disclosed to providers. |

---

## 2. Versioning and transport

- **Version string:** `teleport.provider/0.1`. Teleport sends it in the `Teleport-Provider-Version` header on every push and in every event envelope (`protocol`). Providers MUST send it on every call to Teleport. Teleport refuses unknown major versions with `400 unsupported_version`.
- **Compatibility:** within 0.x, new optional fields and new event types MAY appear. Providers MUST ignore fields and event types they don't know.
- **Transport:** HTTPS only, TLS 1.2 or later. JSON bodies in UTF-8. Timestamps are RFC 3339 in UTC with a `Z` suffix. Money is integer minor units (cents) with an ISO 4217 currency; v0.1 accepts `USD` only.
- **Base URL** for provider calls: `https://api.teleport.eco/api/v1/provider`.
- **Errors** use the Teleport API shape: `{ "error": { "code", "message", "details"? } }` (§13).

---

## 3. State machine

### 3.1 Offer

```
OFFERED ──quote──▶ QUOTED ──accept──▶ ACCEPTED (an assignment exists)
   │                  │
   ├──decline─────────┴──▶ DECLINED
   ├──expiresAt passes──▶ EXPIRED
   └──offer.cancelled───▶ CANCELLED      (filled elsewhere, requester cancelled, safety)
```

- An offer MAY be accepted without a quote. The price is then the offer's `payCeiling`.
- An offer can be quoted more than once while it's open; each quote replaces the previous one.
- Only one provider's acceptance wins. A late accept answers `409 conflict` with `details.state`.

### 3.2 Assignment

```
ASSIGNED ─▶ EN_ROUTE ─▶ ON_SITE ─▶ SUBMITTED ─decision─▶ ACCEPTED ─▶ RECEIPTED ─▶ PAYMENT_CLEARED
   │           │           │           │                    │
   │           │           │           └──────────────▶ REJECTED ──redo allowed──▶ ASSIGNED
   └───────────┴───────────┴──▶ FAILED (provider)  or  CANCELLED (requester, via assignment.cancelled)
```

- `EN_ROUTE` and `ON_SITE` are optional. A device or imagery lane MAY go straight from `ASSIGNED` to `SUBMITTED`.
- `SUBMITTED` is reached only by posting evidence (§6.6), never by a status call.
- A `REJECTED` assignment with `redoAllowed: true` returns to `ASSIGNED` until `redoBy`. Otherwise it's final.
- `FAILED` and `CANCELLED` send the task back to the router, which offers it to the next lane.
- Every transition is a conditional update on the state it expects, so retried or racing calls change state once.

---

## 4. Identity, keys and signing

### 4.1 Provider keys

- A provider has **live keys** (`tp_live_…`) and **test keys** (`tp_test_…`), both with role `provider`. They're created when Teleport approves the provider. A test key only ever sees sandbox offers (§11).
- Every provider call sends `Authorization: Bearer <key>`.

### 4.2 Teleport → provider: signed events

Teleport signs every event and every synchronous quote request with its **provider-signing key**. This is an ES256 (P-256) key used only for this protocol, separate from the outcome-webhook key and the verifier keys.

- **Keys** are published at `https://api.teleport.eco/.well-known/teleport-provider-keys.json` as a JWKS. Each key's `kid` is its RFC 7638 thumbprint. Retired keys stay listed so older signatures still check.
- **Signature format:** a detached compact JWS (RFC 7515 Appendix F) over the **exact request body**, in the `Teleport-Signature` header: `<protected>..<signature>`.
- **Protected header:**

  ```json
  { "alg": "ES256", "kid": "<thumbprint>", "typ": "teleport-provider+json", "teleport-ts": 1794852000 }
  ```

  `teleport-ts` is the send time in Unix seconds.
- **To verify:**
  1. Split the header value on `.`; the middle part MUST be empty.
  2. Base64url-decode the protected header. Check `alg` is `ES256`, `typ` is `teleport-provider+json`, and `teleport-ts` is within **300 seconds** of now.
  3. Find `kid` in the JWKS. If it's unknown, refetch the JWKS once before refusing.
  4. Verify the ES256 signature (raw `r‖s`, 64 bytes) over `ASCII(protected) || "." || base64url(body)`.
- **Providers MUST verify** before acting on an event, and MUST answer `400` to anything that fails.

This is the same scheme as TAP outcome webhooks (§9.2), with its own `typ` and key, so a signature from one can never be replayed as the other.

### 4.3 Provider → Teleport: optional signatures

- In v0.1 a provider MAY also sign its calls: a detached JWS in `Provider-Signature`, with `typ: "provider-teleport+json"`, signed by a key in the manifest's `jwksUrl`.
- When the manifest declares a `jwksUrl` and a call carries `Provider-Signature`, Teleport verifies it and refuses a bad one with `401 invalid_signature`.
- Signatures become REQUIRED for `live` providers in v0.2.

### 4.4 Idempotency and replay

- Every provider `POST` and `PUT` MUST carry an `Idempotency-Key` header (1–200 printable ASCII characters).
  - Teleport keeps each key for 24 hours per provider.
  - The same key with the same body returns the first answer.
  - The same key with a different body is `409 idempotency_conflict`.
- Every event has a unique `eventId`. Teleport delivers at least once, so **providers MUST de-duplicate on `eventId`**.

---

## 5. The manifest

A provider describes itself in one JSON document. It submits it with `PUT /provider/manifest`, and Teleport validates it against `$defs.Manifest` in the schema file. A changed manifest takes effect for new offers only.

```json
{
  "schema": "teleport.provider.manifest/0.1",
  "id": "acme-field",
  "label": "Acme Field Services",
  "url": "https://acme.example",
  "kinds": ["HUMAN"],
  "categories": ["INSPECT", "CAPTURE", "OBSERVE"],
  "coverage": {
    "countries": ["US"],
    "regions": ["US-CA"],
    "areas": [],
    "remote": false
  },
  "leadTimeMinutes": { "min": 60, "typical": 240 },
  "evidence": {
    "origins": ["THIRD_PARTY_SUBMITTED"],
    "teleportCaptureLink": true,
    "types": ["IMAGE", "VIDEO", "GPS"]
  },
  "modes": ["push", "pull"],
  "endpoints": {
    "events": "https://acme.example/teleport/events",
    "quote": "https://acme.example/teleport/quote"
  },
  "jwksUrl": "https://acme.example/.well-known/jwks.json",
  "currency": "USD",
  "support": { "email": "ops@acme.example" }
}
```

| Field | Required | Meaning |
|---|---|---|
| `schema` | yes | Always `teleport.provider.manifest/0.1`. |
| `id` | yes | A stable slug, `^[a-z][a-z0-9-]{2,39}$`. It's the provider id committed in receipts. |
| `label`, `url` | yes | For Teleport ops and the provider's own dashboard. Requesters don't see them by default (§9.1). |
| `kinds` | yes | TAP actor kinds the provider supplies: `HUMAN`, `HUMANOID`, `ROBOT`, `AUTONOMOUS_VEHICLE`, `DRONE`, `DEVICE`, `MULTI_ACTOR`. |
| `categories` | yes | TAP task categories it takes: `INSPECT`, `OPERATE`, `MAINTAIN`, `CLEAN`, `REPAIR`, `CAPTURE`, `DEMONSTRATE`, `UNLOAD`, `TRANSPORT`, `OBSERVE`, `CUSTOM`. |
| `coverage` | yes | Where it works. `countries` are ISO 3166-1 alpha-2. `regions` are ISO 3166-2 codes. `areas` are GeoJSON Polygons or MultiPolygons. `remote` is true when work needs no presence at a place. An offer matches when its place falls in any listed country, region or area. |
| `leadTimeMinutes` | yes | The earliest it can start (`min`) and its usual start (`typical`). |
| `evidence.origins` | yes | TAP evidence origins it can deliver without Teleport (§7). |
| `evidence.teleportCaptureLink` | yes | Whether its performers can capture through a Teleport capture link. It's needed for any task above `STANDARD` (§7). |
| `evidence.types` | no | TAP evidence types it produces, for example `IMAGE`, `VIDEO`, `TELEMETRY`, `LIDAR`. |
| `modes` | yes | Any of `push`, `pull`, `mcp`. If `push` is listed, `endpoints.events` is required. |
| `endpoints.events` | with push | An HTTPS URL that receives signed events (§6.1). |
| `endpoints.quote` | no | An HTTPS URL for synchronous quotes (§6.2). Optional (§13 decision 4). |
| `jwksUrl` | no | Where the provider's own signing keys live (§4.3). |
| `currency` | yes | `USD` in v0.1. |
| `support.email` | yes | Where Teleport ops reach the provider. |

A provider moves through **`sandbox` → `dry_run` → `live`**:
- **Sandbox:** test keys only.
- **Dry run:** real tasks are offered and quoted, but nothing is accepted for real; accept answers `409 dry_run`.
- **Live:** offers can be accepted and the work is done for real.

Teleport ops move a provider to `live` after it passes the conformance kit (§14) and signs the provider terms.

---

## 6. Messages

### 6.1 Event envelope (Teleport → provider)

Every event has the same envelope. Teleport pushes it to `endpoints.events`, signed (§4.2), or serves it from `GET /provider/events` for pull.

```json
{
  "protocol": "teleport.provider/0.1",
  "type": "offer.created",
  "eventId": "evt_8f3k2m9q4w7e1r5t",
  "occurredAt": "2026-11-16T18:00:00Z",
  "environment": "live",
  "providerId": "acme-field",
  "data": { }
}
```

**Push delivery:**
- **Request:** `POST endpoints.events` with headers `Teleport-Signature`, `Teleport-Event-Id`, `Teleport-Event-Type` and `Teleport-Provider-Version`.
- **Response:** any `2xx` within **10 seconds** counts as delivered. Anything else is retried after 1, 5, 30, 120, 360, 720 and 1440 minutes, then dropped and kept for pull.
- **Pausing:** a provider whose endpoint has failed for 24 hours is paused. It gets no new offers, and Teleport ops are alerted.

**Pull:**
- **Request:** `GET /provider/events?after=<eventId>&limit=100` returns `{ "events": [...], "next": "<eventId>" | null }`, oldest first.
- **Retention:** events stay available for 7 days.
- **Push and pull together:** push providers MAY also pull, for example to catch up after an outage.

| `type` | When | `data` |
|---|---|---|
| `offer.created` | The router picked this lane | §6.3 |
| `offer.cancelled` | The offer was filled elsewhere, the requester cancelled, it expired, or it was stopped for safety | `{ offerId, reason }`; `reason` is one of `FILLED_ELSEWHERE`, `REQUESTER_CANCELLED`, `EXPIRED`, `SAFETY` |
| `assignment.details` | Straight after a successful accept | §6.5 |
| `assignment.cancelled` | The requester cancelled after the accept | `{ assignmentId, reason, at }` |
| `decision.made` | Teleport verified the submission | §6.7 |
| `receipt.issued` | The Teleport PoPW receipt was created | §6.8 |
| `payment.cleared` | The requester's payment for the task cleared, so the work is payable | §6.9 |
| `payment.sent` | Teleport sent the payout for the work | §6.10 |

### 6.2 Synchronous quote (optional)

When the manifest has `endpoints.quote`, the router MAY call it while scoring lanes, before any offer exists:

- **Request:** `POST endpoints.quote`, signed (§4.2). The body is `{ "protocol", "quoteRequestId", "environment", "task": <TaskProjection> }`; the projection is the same one an offer carries (§6.3).
- **Answer** within **5 seconds**:
  - `200 { "priceCents", "currency", "etaMinutes", "validUntil" }`, or
  - `204` for "won't quote".

  A timeout counts as no quote.
- **Effect:** a sync quote only affects scoring. If the lane wins, the offer carries `prequote` with the same numbers, and accepting at that price needs no further quote.

### 6.3 `offer.created`

```json
{
  "offerId": "ofr_2n7d4k1p9s3x6v8b",
  "taskRef": "tref_0d6c3b1e7a94f285",
  "expiresAt": "2026-11-16T18:30:00Z",
  "quoteBy": "2026-11-16T18:10:00Z",
  "task": {
    "title": "Photograph cooler 4 after restock",
    "objective": "Every facing in cooler 4 is full and labels face forward.",
    "instructions": ["Photograph the whole cooler front, doors closed.", "Photograph each shelf close up."],
    "doneWhen": ["Every facing is full"],
    "category": "CAPTURE",
    "actorKinds": ["HUMAN"],
    "area": { "city": "Irvine", "region": "US-CA", "countryCode": "US", "approx": { "lat": 33.68, "lng": -117.83, "radiusMeters": 2000 } },
    "window": { "startsAfter": null, "deadline": "2026-11-16T22:00:00Z" },
    "evidence": {
      "items": [{ "id": "after_image", "type": "IMAGE", "required": true, "description": "The full cooler front" }],
      "minimumAssurance": "VERIFIED",
      "captureLinkRequired": true
    }
  },
  "payCeiling": { "amountCents": 2500, "currency": "USD" },
  "prequote": null
}
```

**Least-disclosure rules** (decision 3, SEC-2):
- An offer MUST NOT contain the requester's name, org, contact details or task id. `taskRef` is a per-provider opaque reference, so two providers can't correlate a task.
- The place is coarse until the provider accepts. `approx` is rounded to 0.01° with a radius of at least 1,000 metres, and it's present only when the lane needs distance to quote.
- The street address, the spot and the access notes arrive only in `assignment.details` (§6.5).

### 6.4 Provider → Teleport: offers

| Call | Body | Answer |
|---|---|---|
| `GET /provider/offers?status=open` | none | `{ "offers": [OfferCreated…] }`: open offers, newest first (for pull) |
| `GET /provider/offers/{offerId}` | none | The offer and its state |
| `POST /provider/offers/{offerId}/quote` | `{ "priceCents", "currency", "etaMinutes", "validUntil", "note"? }` | `201 { "quoteId", "offerId", "state": "QUOTED" }`. `priceCents` MUST be ≤ `payCeiling.amountCents`, otherwise `422 over_ceiling`. |
| `POST /provider/offers/{offerId}/accept` | `{ "quoteId"?, "performerRef" }` | `201 <AssignmentDetails>` (the same data as the event, so pull providers don't wait). `409` if the offer was taken, expired or cancelled. |
| `POST /provider/offers/{offerId}/decline` | `{ "reason", "note"? }`; `reason` is one of `NO_PERFORMER`, `OUT_OF_COVERAGE`, `TOO_SOON`, `PRICE`, `CAPABILITY`, `OTHER` | `200 { "offerId", "state": "DECLINED" }`. The router moves to the next lane. |

**About `performerRef`:**
- It's the provider's own id for whoever will do the work, an opaque string of 1–128 characters.
- Teleport stores only `sha256(salt ‖ performerRef)`, with a per-assignment salt. It never asks for the performer's name or contact details.
- The provider MAY send a different `performerRef` with the evidence if someone else ended up doing the work.

### 6.5 `assignment.details`

```json
{
  "assignmentId": "asg_5h2j8k3l6m9n1p4q",
  "offerId": "ofr_2n7d4k1p9s3x6v8b",
  "price": { "amountCents": 2200, "currency": "USD" },
  "place": {
    "address": "6460 Irvine Blvd, Irvine, CA 92620",
    "lat": 33.6846,
    "lng": -117.8265,
    "spot": "Cooler 4, back wall",
    "accessNotes": "Ask for the shift lead at the counter."
  },
  "deadline": "2026-11-16T22:00:00Z",
  "captureLink": { "url": "https://app.teleport.eco/capture/…", "expiresAt": "2026-11-16T22:00:00Z" }
}
```

- `captureLink` is present when the offer said `captureLinkRequired: true`. The provider MUST give the link only to the performer doing the work. The link is single-use per assignment.
- `place` is for that performer. The provider MUST NOT store it longer than the assignment needs, and MUST NOT use it for anything else.

### 6.6 Provider → Teleport: assignments

| Call | Body | Answer |
|---|---|---|
| `GET /provider/assignments/{assignmentId}` | none | State, price, decision and receipt |
| `POST /provider/assignments/{assignmentId}/status` | `{ "status": "EN_ROUTE" \| "ON_SITE" \| "FAILED" \| "CANCELLED", "at"?, "note"? }` | `200 { "assignmentId", "state" }`. `FAILED` and `CANCELLED` free the task for the next lane. |
| `POST /provider/assignments/{assignmentId}/evidence/uploads` | `{ "files": [{ "evidenceId", "contentType", "size" }] }` (1–50 files, each at most 50 MB) | `201 { "uploads": [{ "evidenceId", "blobPathname", "uploadUrl", "method": "PUT", "headers" }] }`, valid for 15 minutes |
| `POST /provider/assignments/{assignmentId}/evidence` | The evidence submission below | `201 { "assignmentId", "state": "SUBMITTED" }` |
| `POST /provider/assignments/{assignmentId}/dispute` | `{ "reason", "note" }`, within 72 hours of `decision.made` | `201 { "disputeId" }`. Teleport ops rule on it. The ruling (`UPHELD` or `OVERTURNED`) appears as `dispute.resolution` on the assignment. An overturned rejection also gets a new `decision.made` with `ACCEPT`, and the work becomes payable. |
| `GET /provider/statement?month=YYYY-MM` | none | The month's accepted work, payable and cleared (§10) |
| `GET /provider/payouts` | none | How Teleport pays you, and the Stripe onboarding link until your payout account is set up (§10) |

**Evidence submission:**

```json
{
  "performerRef": "worker-7731",
  "actor": { "actorType": "HUMAN" },
  "executedAt": "2026-11-16T19:42:10Z",
  "attestation": { "statement": "I photographed cooler 4 after restocking.", "attestedBy": "Acme performer worker-7731" },
  "assets": [
    { "evidenceId": "after_image", "path": "after/cooler_4.jpg", "origin": "THIRD_PARTY_SUBMITTED", "contentType": "image/jpeg", "blobPathname": "prv/asg_5h2j…/after_image" }
  ]
}
```

- Each asset carries exactly one of the following:
  - `blobPathname`, from the upload call.
  - `url`, for provider-hosted media. It must be public HTTPS and stay readable for at least 1 hour; Teleport fetches it.
  - `contentBase64`, for small files up to 1 MB.
- Teleport hashes the bytes it stores, never a digest the provider sends.
- `path` follows the PoPW evidence path rule (Encoding addendum v0.1.1 §A1). `origin` follows §7.
- Assets captured through the Teleport capture link don't need to be sent here. They're already attached, with origin `TELEPORT_CAPTURE`. A provider whose performer used the link posts `{ "performerRef", "actor", "executedAt", "assets": [] }` to mark the work done.

### 6.7 `decision.made`

```json
{
  "assignmentId": "asg_5h2j8k3l6m9n1p4q",
  "decision": "REJECT",
  "rejectionReason": "LOCATION_MISMATCH",
  "notes": "The photo shows cooler 3.",
  "redoAllowed": true,
  "redoBy": "2026-11-17T22:00:00Z",
  "payable": null
}
```

- `decision` is `ACCEPT` or `REJECT`.
- `rejectionReason` is a TAP v0.3 rejection reason: `EVIDENCE_INSUFFICIENT`, `ORIGIN_BELOW_FLOOR`, `LOCATION_MISMATCH`, `TIME_WINDOW`, `SCOPE_NOT_MET`, `SAFETY` or `POLICY`.
- On `ACCEPT`, `payable` is `{ "amountCents", "currency", "status": "AWAITING_REQUESTER_PAYMENT" }` (§10).
- Rejected work is not payable unless a redo is accepted.

### 6.8 `receipt.issued`

```json
{
  "assignmentId": "asg_5h2j8k3l6m9n1p4q",
  "claimId": "claim_9w2e4r6t8y1u3i5o",
  "receiptLevel": "ANCHORED",
  "assuranceTier": "VERIFIED",
  "evidenceOriginFloor": "TELEPORT_CAPTURE",
  "status": "PENDING_BATCH",
  "proofUrl": "https://api.teleport.eco/api/v1/popw/claims/claim_9w2e4r6t8y1u3i5o/proof"
}
```

- The receipt commits the provider id (`manifest.id`), the salted performer hash, the evidence origin floor and the assurance tier reached (PP-8).
- Anyone can check it from `proofUrl`, without trusting Teleport.

### 6.9 `payment.cleared`

```json
{
  "assignmentId": "asg_5h2j8k3l6m9n1p4q",
  "amountCents": 2200,
  "currency": "USD",
  "clearedAt": "2026-12-03T17:00:00Z",
  "payoutDueBy": "2026-12-10"
}
```

This is sent when the requester's payment for the task clears. From that moment the provider is owed `amountCents`, and it's paid by `payoutDueBy` (§10).

### 6.10 `payment.sent`

```json
{
  "assignmentId": "asg_5h2j8k3l6m9n1p4q",
  "amountCents": 2200,
  "currency": "USD",
  "sentAt": "2026-12-03T17:01:00Z",
  "method": "STRIPE_CONNECT",
  "reference": "tr_1QxYz2CPb3XLMlkK"
}
```

This is sent when Teleport pays the provider for the work. The `method` is one of three values:
- `STRIPE_CONNECT`: a transfer to the provider's Stripe account; `reference` is the transfer id.
- `MANUAL`: a bank transfer Teleport ops recorded; `reference` is its reference.
- `SANDBOX`: simulated.

The statement then shows the work as `PAID`.

---

## 7. Evidence and assurance

| Origin | Who produces it | Notes |
|---|---|---|
| `TELEPORT_CAPTURE` | The performer, through the Teleport capture link | The only origin that can reach `VERIFIED` and above for human work. Needs `evidence.teleportCaptureLink: true`. |
| `THIRD_PARTY_SUBMITTED` | The provider's own app or proof of delivery | The receipt says so plainly. Its assurance is capped by the TAP v0.3 origin rules. |
| `ACTOR_TELEMETRY` | Robot or drone telemetry plus frames | For `ROBOT`, `DRONE` and `AUTONOMOUS_VEHICLE` lanes. |
| `ATTESTED_DEVICE` | A device with hardware attestation | For `DEVICE` lanes. |
| `PLATFORM_FETCHED` | Teleport, pulling from a platform API under the requester's authorization | Not sent by providers. |

- The router offers a task to a lane only when the lane can reach the task's `minimumAssurance` (PP-11). Above `STANDARD`, that means `captureLinkRequired: true` and a provider that supports it.
- An evidence origin the task doesn't accept is refused with `422 origin_not_accepted`.
- Teleport fetches and hashes provider-hosted media within 1 hour of submission, because courier proof expires (PP-7). It only fetches from public hosts.

---

## 8. Routing (informative)

How the router picks lanes is Teleport's business, but providers should know the inputs (PP-11 and PP-12):

1. **Hard filter:** the task's actor kinds are in `kinds`, its category is in `categories`, its place is in `coverage`, and the provider can reach the task's minimum assurance.
2. **Score:**
   - assurance first;
   - then ETA (the sync quote, or `leadTimeMinutes.typical`);
   - then price (the sync quote, or the expected price);
   - then the provider's 30-day fill rate and Teleport rejection rate (§12).

   The requester's routing policy sets the weights.
3. **Fallback:** a decline, an expiry, `FAILED` or `assignment.cancelled` frees the task, and the next lane gets an offer.

---

## 9. Privacy and conduct

### 9.1 What providers see and don't see

- **Providers never see** the requester's identity, the requester's other tasks, or any receipt field beyond §6.8.
- **Requesters don't see the provider by default** (decision 3). Teleport ops and the receipt's committed provider id make it auditable.

### 9.2 What providers MUST do

- MUST NOT contact the requester, the place's owner or staff about the task except as `accessNotes` say.
- MUST NOT reuse place or capture-link data beyond the assignment.
- MUST keep `performerRef` stable for the same performer within one assignment.
- MUST report `FAILED` promptly rather than let an assignment go silent.

---

## 10. Money (decision 2)

1. **Payer of performers:** the provider pays its performers. Teleport pays the provider.
2. **Price:** an accepted assignment is priced at the accepted quote, or at `payCeiling` if there was no quote.
3. **Payment timing:** Teleport pays the provider **after the requester's payment for that task clears**. Teleport carries no float.
   - On `ACCEPT`, the work becomes `AWAITING_REQUESTER_PAYMENT`.
   - When the requester pays, `payment.cleared` is sent, and the payout is due within **7 days** (`payoutDueBy`).
   - **Automatic payment:** a requester with a saved card or bank account is charged when Teleport accepts the work. Once that charge succeeds, Teleport transfers `amountCents` to the provider's Stripe account straight away, and sends `payment.sent`. The transfer is tied to the requester's charge (Stripe `source_transaction`), so the money moves only once it's there. A bank debit takes a few days to succeed. Stripe then pays out to the provider's bank on its usual schedule.
4. **Unpaid requesters:** if a requester never pays, the provider is not paid for that task. The provider terms say so. The statement shows the task as `UNPAID` after 90 days.
5. **Statement:** `GET /provider/statement?month=YYYY-MM` lists every accepted assignment in the month with its amount and its status: `AWAITING_REQUESTER_PAYMENT`, `CLEARED`, `PAID` or `UNPAID`.
6. **Rejected and cancelled work:**
   - Rejected work is not payable unless a redo is accepted.
   - Disputes go through §6.6 within 72 hours.
   - In v0.1, cancellation after accept pays nothing. Cancellation fees are a v0.2 item.
7. **Payout method:** Stripe Connect.
   - **Setup:** each provider sets up a Stripe Express account once. `GET /provider/payouts` returns the onboarding link until the account can receive transfers.
   - **Before setup:** cleared work waits, then is paid as soon as setup is done.
   - **Off Stripe:** Teleport ops can still pay by bank transfer and record it (`payment.sent` with `MANUAL`).
   - **Later:** USDC on Base may become an option. The provider terms set the details.

---

## 11. Sandbox

- **What it is:** a provider's test keys (`tp_test_…`) see only sandbox offers. Sandbox offers come from sandbox requesters' tasks (Teleport's test keys, `teleport-tap-sdk` sandbox), and from `POST /provider/sandbox/offers`. That call takes the body `{ "task"?: <TaskProjection> }` and makes a synthetic offer for the calling provider.
- **What's different:** nothing in the sandbox reaches a real person, place or chain. `assignment.details` carries a sample address and a sandbox capture link. Decisions come from simulation (`POST /sandbox/tasks/{id}/simulate` on the requester side) or automatically 60 seconds after evidence for synthetic offers. Receipts are `SANDBOX`, and `payment.cleared` and a simulated `payment.sent` (`method` `SANDBOX`) follow the decision immediately, with `amountCents` shown but never paid.
- **Marking:** every sandbox event has `"environment": "sandbox"`.

---

## 12. Provider stats (decision 5)

Teleport computes, per provider and over 30 days:
- fill rate (accepted ÷ offered)
- median time to accept
- median time from accept to submission
- Teleport acceptance and rejection rates, by reason
- the share of work captured through the capture link

Teleport ops see every provider's stats in admin. Each provider sees only its own, in its dashboard and at `GET /provider/stats`. A public leaderboard waits until there's enough data to be fair.

---

## 13. Errors

Every error has the shape `{ "error": { "code", "message", "details"? } }`.

| Status | `code` | When |
|---|---|---|
| 400 | `invalid_request`, `unsupported_version` | A malformed body or field, or an unknown protocol major version |
| 401 | `unauthenticated`, `invalid_signature` | A bad or missing key, or a bad `Provider-Signature` |
| 403 | `forbidden`, `provider_paused`, `not_live` | Not this provider's resource; paused for delivery failures; a live call from a `dry_run` or `sandbox` provider |
| 404 | `not_found` | No such offer or assignment for this provider |
| 409 | `conflict`, `idempotency_conflict`, `dry_run` | The wrong state (taken, expired, already submitted); an `Idempotency-Key` reused with a different body; accept in dry run |
| 422 | `over_ceiling`, `origin_not_accepted`, `unprocessable` | A quote above the ceiling; an evidence origin the task refuses; evidence that fails the task's rules |
| 429 | `rate_limited` | Too many calls; wait for `Retry-After` |

---

## 14. Conformance

A provider conforms to v0.1 when it:

1. **Verifies events:** verifies every signed event (§4.2) and answers `400` to a bad signature, a stale `teleport-ts` or an unknown `kid` (after one JWKS refetch).
2. **Handles delivery correctly:** de-duplicates events on `eventId`, answers push deliveries within 10 seconds, and ignores unknown fields and event types.
3. **Calls correctly:** sends `Teleport-Provider-Version` and `Idempotency-Key` on every write, and handles `409` on accept as "someone else got it".
4. **Respects quotes:** never quotes above `payCeiling`, and stops working on an offer after `offer.cancelled`.
5. **Handles evidence correctly:** sends evidence only with origins the task accepts, and gives the capture link only to the performer.
6. **Keeps its manners:** follows §9.

The conformance kit, `npx -p teleport-tap-sdk teleport-provider-check <events-endpoint>` (PRD PP-20), runs a mock router through:
- the happy path
- decline and expiry
- a bad signature, a stale signature and a replayed event
- a duplicate event
- a reject with a redo
- evidence upload

Passing it is required before `dry_run`.

The vectors file has the fixed inputs a provider's own tests can use:
- valid and invalid signed events, with the test key that signed them
- one example of every message, valid against the schema

---

## 15. Security considerations

- **Key separation:** the provider-signing key signs nothing else. A compromised outcome-webhook key can't forge offers, and the reverse holds too.
- **Replay:** `teleport-ts` (300 seconds), `eventId` de-duplication and `Idempotency-Key` together stop replays in both directions.
- **Least disclosure:** offers are coarse. Exact places travel only to the accepting provider, only when it needs them, and only for the assignment's lifetime.
- **Evidence integrity:** Teleport hashes the bytes it stores. Provider-hosted media is fetched only from public hosts, within an hour. A provider can't choose the hash its evidence commits to.
- **Pseudonymity:** performer identities stay with the provider. Receipts commit a salted hash, so receipts for the same performer can't be linked without the salt.
- **Pausing:** a provider that keeps failing delivery is paused before it can sit on offers.

---

## 16. Open items for v0.2

- Required `Provider-Signature` for live providers, and optional mutual TLS.
- Cancellation fees after accept.
- Multi-performer assignments (`MULTI_ACTOR` teams) and partial evidence.
- Counter-offers above `payCeiling`.
- Provider-side webhooks for requester messages, which v0.1 doesn't allow at all.
- The provider MCP tool definitions as a normative appendix. In v0.1 they're informative. They're served at `https://mcp.teleport.eco/provider`, with the provider key as the bearer token: `whoami`, `list_offers`, `get_offer`, `quote_offer`, `accept_offer`, `decline_offer`, `get_assignment`, `get_capture_link`, `update_status`, `submit_evidence`, `list_events`, `get_statement`, `get_payouts`, `get_stats`, `create_sandbox_offer`.

---

## Appendix A. Mapping to the PRD

| PRD | Here |
|---|---|
| PP-1 to PP-3 (sign-up, manifest, modes) | §4.1, §5 |
| PP-4 to PP-8 (evidence and assurance) | §6.6, §7 |
| PP-9 to PP-13 (router) | §8 (informative) |
| PP-14 to PP-16 (money) | §10 |
| PP-17, PP-18 (provider MCP) | §16 (informative in v0.1) |
| PP-19, PP-20 (SDK module, conformance kit) | §14 |
| PP-21, PP-22 (spec, schema, vectors) | this document and its two companion files |
| SEC-1, SEC-2 | §4, §6.3, §9 |
