Steps (In Depth)

1

Resolve wallet to Privy ID

Request:

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:

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

2

Fetch user location data

Request:

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:

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

If user has no location record:

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

3

Read chat

Use SWAMP or NEXUS as the world param.

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.

4

Post bot chat message

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.

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