# External integrations

> Raw calls outside the REST client: the DexScreener profile order and the pump.fun charity directory.

These calls do not go through the `Proxima` REST client and therefore skip its 2FA and session handling.

- The DexScreener order is a raw `fetch` to the main API host.
- The charity directory is a Proxima-hosted lookup at `https://charities.proxima.tools`, used when a creator routes fee shares to a pump.fun charity.

The X tracker also loads third-party images through `https://wsrv.nl/?url=...&w=1024&we` (a public CORS image proxy) and avatars from `https://unavatar.io/x/{handle}`. Those are public services, not Proxima APIs, and are not documented here.

Base URL: `https://api-mig.proxima.tools`

## Endpoints

- `POST https://api-mig.proxima.tools/evm/dexscreener/create-order`: Create a DexScreener order
- `GET https://charities.proxima.tools/`: Search charities
- `GET https://charities.proxima.tools/charities/{charity_id}`: Retrieve a charity

### Create a DexScreener order

`POST https://api-mig.proxima.tools/evm/dexscreener/create-order`

Submits a token profile update to DexScreener and returns a payment link. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Do not retry blindly. Each call creates a new order with its own payment link, and no endpoint lists existing orders. Retry only when the first call surely did not reach the server.

Sent from the "Update DexScreener" modal of a live launch. The web client opens the returned `paymentLink` in a new tab.

Unlike the REST client, this call sends the session JWT **without** the `Bearer ` prefix (`Authorization: <JWT>`); the API's auth middleware accepts both forms. Any non-2xx is shown as "Failed to update token on Dex Screener". The host is the main API.

#### Headers

- `Authorization` (string, required): The bare Proxima session JWT.
- `X-Sent-At` (string, optional): Client send time in epoch milliseconds.

#### Form fields

- `tokenImage` (file, required): Square token image (the modal crops to 1:1).
- `tokenHeader` (file, optional): Header banner image.
- `data` (string, required): JSON-encoded profile.
  - `chainId` (string, required): DexScreener chain id. The web client always sends `solana`.
  - `tokenAddress` (string, required): Token mint.
  - `description` (string, optional): Token description.
  - `socials` (array<object>, optional): `{ type: "telegram" | "x" | "discord", url }` entries.
  - `websites` (array<object>, optional): `{ label, url }` entries (`Website`, `Docs`, then any extra links).

#### Returns 200 OK

- `paymentLink` (string): URL where the user pays for the DexScreener order.

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/evm/dexscreener/create-order" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -F "tokenImage=@./image.png" \
  -F "tokenHeader=@./image.png" \
  -F "data=<data>"
```

#### Example response

```json
{
  "paymentLink": "https://checkout.example.com/pay/9f8e7d6c-5b4a-4321-8765-0fedcba98765"
}
```

### Search charities

`GET https://charities.proxima.tools/`

Searches the pump.fun charity directory by name. (No auth)

- Token: None. This endpoint is public.
- Retry: Safe to retry.

Called from the charity picker when a creator assigns a fee share to a charity. Any non-2xx is thrown as "pump.fun charity search failed".

#### Query parameters

- `term` (string, required): Search text.
- `limit` (integer, optional, default "50"): Maximum results.

#### Headers

- `Accept` (string, optional): `application/json`.
- `X-Sent-At` (string, optional): Client send time in epoch milliseconds.

#### Returns 200 OK

- `pageKey` (string | null): Pagination key. The web client does not page.
- `response` (array<object>): Matching charities (see Retrieve a charity).

#### Example request

```bash
curl "https://charities.proxima.tools/?term=water"
```

#### Example response

```json
{
  "pageKey": null,
  "response": [
    {
      "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "name": "Clean Water Fund",
      "slug": "clean-water-fund",
      "logo": "https://charities.example.org/logo.png",
      "website": "https://cleanwater.example.org",
      "country": "US",
      "isVerified": true,
      "isEnabled": true
    }
  ]
}
```

### Retrieve a charity

`GET https://charities.proxima.tools/charities/{charity_id}`

Returns one charity from the pump.fun directory. (No auth)

- Token: None. This endpoint is public.
- Retry: Safe to retry.

Used to resolve charity names on creator fee shares that only carry a `charity_id`. Names are cached in memory for the session.

#### Path parameters

- `charity_id` (string, required): Charity ID.

#### Headers

- `Accept` (string, optional): `application/json`.
- `X-Sent-At` (string, optional): Client send time in epoch milliseconds.

#### Returns 200 OK

- `id` (string): Charity ID.
- `name` (string): Display name.
- `slug` (string): URL slug.
- `logo` (string): Logo URL.
- `website` (string): Website URL.
- `address` (string): Street address.
- `city` (string): City.
- `state` (string): State or region.
- `country` (string): Country.
- `zipCode` (string): Postal code.
- `taxId` (string): Tax identifier.
- `isVerified` (boolean): Verified by the directory.
- `isEnabled` (boolean): Accepting donations.
- `socials` (object): Optional `twitter`, `facebook`, `instagram`, `linkedin`, `youtube`, `blog` URLs.

#### Example request

```bash
curl "https://charities.proxima.tools/charities/b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
```

#### Example response

```json
{
  "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
  "name": "Clean Water Fund",
  "slug": "clean-water-fund",
  "logo": "https://charities.example.org/logo.png",
  "website": "https://cleanwater.example.org",
  "city": "Austin",
  "state": "TX",
  "country": "US",
  "isVerified": true,
  "isEnabled": true,
  "socials": {
    "twitter": "https://x.com/cleanwaterfund"
  }
}
```
