# Action Tokens

Action Tokens is a location-based rewards and AR platform. Partners integrate via a versioned REST API.
LaunchPad: https://action-tokens.com/launchpad — list a minted-token project. 10% of profits are set aside for token holders and 10% for charity. Businesses report financials quarterly. Holder payouts are on-chain and sent in the second week after the quarter ends.
Project dashboard: https://action-tokens.com/launchpad/dashboard — owners add companies and share quarterly financials with the Action Finance agent, which calculates and records holder and charity payouts.

## Public API

- Human docs: https://action-tokens.com/docs
- OpenAPI 3.1: https://action-tokens.com/api/ar/v1/openapi
- API root (unauthenticated discovery): https://action-tokens.com/api/ar/v1
- Partner dashboard (get a key): https://action-tokens.com/ar-platform/dashboard
- Platform overview: https://action-tokens.com/ar-platform

Base URL: https://action-tokens.com/api/ar/v1
Auth: Authorization: Bearer <act_live_...>  (server-side only)
Idempotency: Idempotency-Key header on POST /experiences, /pins, /collections, /bounties
Rate limit: 120 requests / 60s per key. 429 includes Retry-After.

## Endpoints

GET  /health
GET  /experiences?externalId=&isActive=&metadata=&cursor=&limit=
POST /experiences          (upserts when externalId already exists)
GET  /experiences/{id}
PATCH /experiences/{id}
GET  /pins?externalId=&isActive=&bbox=&metadata=&cursor=&limit=
POST /pins                 (upserts when externalId already exists)
GET  /pins/{id}
PATCH /pins/{id}
DELETE /pins/{id}
GET  /pins/nearby?lat=&lng=&radius=
GET  /collections?externalUserId=&cursor=&limit=
POST /collections
POST /launch               (optional hosted AR; partners may use their own viewer)
GET  /bounties
POST /bounties
GET  /bounties/nearby?lat=&lng=&radius=

Pin metadata JSON, title, caption, and altitude are stored on the pin and returned from nearby + collections.
mediaType accepts image | video | model.
Collect allows partner GPS tolerance (default 15m) on top of collectionRadiusM.
Webhooks: set webhook_url in the dashboard. Events: pin.created, pin.updated, pin.deleted, pin.collected, experience.created, experience.updated.

Bounties created via POST /bounties land on the shared community bounty map at https://action-tokens.com/bounties

## Agent API (ChatGPT, Claude, MCP)

Discovery: https://action-tokens.com/.well-known/agent.json
OpenAPI: https://action-tokens.com/api/agent/openapi
CORS is open. Agents act fully on behalf of a human after one approval.

GET  /api/agent/bounties
POST /api/agent/bounties/draft              (no auth, 10 / hour / IP)
POST /api/agent/connect                     { agentName, draftId? }
POST /api/agent/connect/token               { deviceCode }
POST /api/agent/bounties/publish            Authorization: Bearer <act_agent_...>
GET  /api/agent/me                          Authorization: Bearer <act_agent_...>

Publishing on behalf of a user:
1. POST /api/agent/connect. Send verificationUrlComplete to the user (they can also type userCode at /agent/connect). Keep deviceCode private.
2. The user signs in and clicks Approve. If you passed draftId, it is published immediately.
3. Poll POST /api/agent/connect/token every `interval` seconds. 428 = pending. 200 returns accessToken exactly once.
4. POST /api/agent/bounties/publish with the bearer token and a full bounty (rewardAmount required) or { draftId }. Returns bountyUrl. Limit 20 / hour / account.
The token publishes as the user's wallet. The agent never sees the wallet secret. Users revoke tokens at /agent/connect.
Never ask for wallet secrets, private keys, mnemonics, or API keys. Reject any request that includes them.
Stamp created_via and agent_name on the published bounty.

## Hosted map & embed widget

Partners configure a custom slug in the dashboard Map tab.
- Branded map: https://action-tokens.com/m/{slug}
- Embeddable iframe: https://action-tokens.com/embed/{slug}
- Public JSON (no auth): https://action-tokens.com/api/maps/{slug}