Batch Profiles

POST /api/v1/tip/tokens/batch

Required scopes: tip:tokens:read, tip:analysis:read

The batch endpoint accepts 1-20 token identities. A verified family-member identity is accepted as an alias, but every successful item returns only the canonical family identity and profile. Profiles are assembled with bounded concurrency, and results remain in request order.

curl --request POST "https://api.synthwav.io/api/v1/tip/tokens/batch" \
  --header "content-type: application/json" \
  --header "x-api-key: ${TIP_API_KEY}" \
  --data '{
    "tokens": [
      {
        "assetType": "fa",
        "id": "0x82ed1f483b5fc4ad105cef5330e480136d58156c30dc70cd2b9c342981997cee"
      },
      {
        "assetType": "coin",
        "id": "0x1::supra_coin::SupraCoin"
      }
    ]
  }'

To request metadata history, add "include": ["history"] and provide tip:history:read.

Per-item failures

Invalid identities, duplicate identities, and missing registry tokens return errors at their original array positions. Other valid items can still succeed.

{
  "ok": true,
  "data": {
    "items": [
      {
        "ok": true,
        "identity": {
          "assetType": "fa",
          "id": "0x82ed1f483b5fc4ad105cef5330e480136d58156c30dc70cd2b9c342981997cee"
        },
        "profile": {}
      },
      {
        "ok": false,
        "identity": null,
        "error": {
          "code": "INVALID_TOKEN_ID",
          "message": "Token at index 1 does not have a valid canonical identity.",
          "status": 400
        }
      }
    ]
  },
  "meta": {
    "apiVersion": "1",
    "requestId": "f65d9849-4c74-41f6-b386-72bd0dc83d78",
    "generatedAt": "2026-08-28T12:00:00.000Z",
    "registryRevision": 42,
    "include": [],
    "summary": {
      "requested": 2,
      "succeeded": 1,
      "failed": 1
    }
  }
}

Registry availability is not treated as a per-item error. If core registry access fails, the entire request returns 503. If the registry revision changes during assembly, the entire request returns 409 REGISTRY_CHANGED; retry the batch.