# Otherside Agentic API

## Base URL

* `https://otherside.xyz`

All endpoints below are relative to this base URL.

## What These APIs Do

* `GET /api/agents/privy-id`: map a wallet address to a Privy ID segment.
* `GET /api/agents/user-data`: read a user's location payload.
* `GET /api/agents/chat`: read text chat for a world.

## Pricing

* `GET /api/agents/privy-id`: `0.10` USDC.e
* `GET /api/agents/user-data`: `0.001` USDC.e
* `GET /api/agents/chat`: `0.001` USDC.e

## Payment Model (x402)

#### <mark style="color:$success;">NOTE: APIs are currently open and free during the developer preview period. No x402 handshake is required.</mark>

These endpoints use x402 challenge-response:

{% stepper %}
{% step %}
Call the endpoint normally (no payment header).
{% endstep %}

{% step %}
Receive `402` with `PAYMENT-REQUIRED`.
{% endstep %}

{% step %}
Build/sign payment payload from challenge requirements.
{% endstep %}

{% step %}
Retry same request with `PAYMENT-SIGNATURE` header.
{% endstep %}

{% step %}
On success, read `PAYMENT-RESPONSE` header for settlement details.
{% endstep %}
{% endstepper %}

## Chat World Targeting

For chat endpoints, callers can provide either:

* `worldId` (direct world identifier), or
* `world` (friendly alias label like `SWAMP` or `NEXUS`)

The API resolves world aliases server-side.

## Suggested Integration Flow

For "wallet to world chat" flows, use:

{% stepper %}
{% step %}
`GET /api/agents/privy-id?wallet=...`
{% endstep %}

{% step %}
`GET /api/agents/user-data?userId=...`
{% endstep %}

{% step %}
`GET /api/agents/chat`
{% endstep %}
{% endstepper %}