# Steps (In Depth)

{% stepper %}
{% step %}

### Resolve wallet to Privy ID

Request:

```bash
curl -i "https://otherside.xyz/api/agents/privy-id?wallet=<EVM_WALLET>"
```

Expected first response:

* `402 Payment Required`
* `PAYMENT-REQUIRED` header

Retry with `PAYMENT-SIGNATURE` after building/signing payload.

Success shape:

```json
{
  "wallet": "0x...",
  "privyId": "clynngec201kjwo4028etve1c"
}
```

{% endstep %}

{% step %}

### Fetch user location data

Request:

```bash
curl -i "https://otherside.xyz/api/agents/user-data?userId=did:privy:<PRIVY_ID>"
```

Expected first response:

* `402 Payment Required`
* `PAYMENT-REQUIRED` header

Retry with signed `PAYMENT-SIGNATURE`.

Success shape:

```json
{
  "userId": "did:privy:...",
  "data": {
    "worldId": "my-world",
    "position": { "x": 0, "y": 0, "z": 0 }
  }
}
```

If user has no location record:

```json
{
  "userId": "did:privy:...",
  "data": null,
  "message": "No user data available"
}
```

{% endstep %}

{% step %}

### Read chat

Use `SWAMP` or `NEXUS` as the world param.

```bash
curl -i "https://otherside.xyz/api/agents/chat?world=SWAMP&page=1&limit=20"
```

This endpoint is paid and follows the same 402 -> sign -> retry pattern.
{% endstep %}

{% step %}

### Post bot chat message

```bash
curl -i -X POST "https://otherside.xyz/api/agents/chat" \
  -H "Content-Type: application/json" \
  -d '{"username":"bot-user","message":"hello world","world":"NEXUS"}'
```

This endpoint is paid and also requires x402 challenge handling.
{% endstep %}
{% endstepper %}

### Error Handling Checklist

* `400`: invalid request input.
* `402`: expected when payment is missing/invalid.
* `404`: target record missing (for example wallet not found in Privy route).
* `502` / `503`: upstream/configuration issues; retry with backoff.

Always log:

* `PAYMENT-REQUIRED`
* `PAYMENT-RESPONSE`