# poly-service

Use this service through MCP Streamable HTTP or the versioned REST API. The service API key is delivered separately by the operator. Never put the key in a public document or URL.

## Connection

- MCP endpoint: https://poly-service.visionclaw.dev/mcp
- REST base URL: https://poly-service.visionclaw.dev/v1
- OpenAPI document: https://poly-service.visionclaw.dev/openapi.json
- Authentication header: `Authorization: Bearer <poly-service-api-key>`
- Machine-readable guide: https://poly-service.visionclaw.dev/how-to-use.json

## Agent onboarding

1. Read this guide and https://poly-service.visionclaw.dev/how-to-use.json.
2. Ask the operator or user for the service API key.
3. Use MCP at https://poly-service.visionclaw.dev/mcp when you need tool schemas and an agent-oriented workflow.
4. Use REST at https://poly-service.visionclaw.dev/v1 for scripts, jobs, dashboards, or direct HTTP clients.
5. Send the key in the `Authorization` header on every MCP or REST request.
6. Start with read operations. For any write, get explicit confirmation and sign the wallet-dependent payload locally.

## Wallet model

The service is non-custodial. The agent keeps its Ethereum wallet and private key locally. The service receives public wallet addresses and agent-signed payloads when a Polymarket or blockchain operation needs them. A service API key does not replace a wallet signature.

## Common read tools

- `poly_check_geoblock`
- `poly_search_markets`
- `poly_list_markets`
- `poly_get_market`
- `poly_get_order_book`
- `poly_get_price`
- `poly_get_positions`
- `poly_get_activity`
- `poly_get_trades`
- `poly_bridge_supported_assets`
- `poly_bridge_quote`
- `poly_bridge_status`
- `poly_builder_status`

## REST read endpoints

- `GET https://poly-service.visionclaw.dev/v1/markets`
- `GET https://poly-service.visionclaw.dev/v1/markets/search`
- `GET https://poly-service.visionclaw.dev/v1/market?id=...`
- `GET https://poly-service.visionclaw.dev/v1/markets/{id}`
- `GET https://poly-service.visionclaw.dev/v1/order-book/{asset_id}`
- `GET https://poly-service.visionclaw.dev/v1/prices/{asset_id}`
- `GET https://poly-service.visionclaw.dev/v1/positions/{address}`
- `GET https://poly-service.visionclaw.dev/v1/activity/{address}`
- `GET https://poly-service.visionclaw.dev/v1/trades/{address}`
- `GET https://poly-service.visionclaw.dev/v1/bridge/assets`
- `GET https://poly-service.visionclaw.dev/v1/bridge/status/{address}`

## Write tools and REST endpoints

- `poly_clob_auth`
- `poly_submit_signed_order`
- `poly_clob_request`
- `poly_bridge_deposit_addresses`
- `poly_broadcast_signed_transaction`
- `poly_deploy_deposit_wallet`
- `poly_relayer_submit`

REST write endpoints include `POST /v1/orders`, `POST /v1/bridge/quote`, `POST /v1/bridge/deposit-addresses`, `POST /v1/transactions/broadcast`, and the Builder relayer endpoints. Write access is controlled by the operator. The service may require a geoblock check, an explicit confirmation, a write limit, and an agent-signed payload.

## Operator key delivery

The operator generates and revokes keys on the service host with the local CLI. Generate one with `npm run keys -- create <agent-name>`, then deliver only the returned `poly_...` value to the intended agent or user through a separate trusted channel. Revoke it with `npm run keys -- revoke <agent-name>`. There is no public key-minting endpoint.
