# Marketplace orders

> Reserve wallets with a quote, pay for it, take delivery and review past purchases.

Buying from the Marketplace follows a quote lifecycle. [Create a quote](#create-a-quote) reserves catalog wallets for a short hold and returns a deposit address (`pay_address`) and the amount due. Pay it from one of your funders with [Pay a quote](#pay-a-quote), wait for the quote to settle, then call [Deliver a quote](#deliver-a-quote) to import the wallets into your account.

Every quote is scoped to the account that created it: another account's quote id answers `404`. Settled orders are listed by [List purchases](#list-purchases). Once delivered, a bought wallet's remaining tokens can be inspected and sold in place.

Amounts are integer strings in the chain's smallest unit (lamports on Solana, wei on EVM chains) and timestamps are RFC 3339 strings. Chains use marketplace slugs (`solana`, `ethereum`, `bsc`, `base`, `robinhood`, `arc`).

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

## Endpoints

- `POST /marketplace/quote`: Create a quote
- `GET /marketplace/quote/{quote_id}`: Retrieve a quote
- `GET /marketplace/quotes`: List quotes
- `GET /marketplace/quote/{quote_id}/wallets`: List quote wallets
- `POST /marketplace/quote/{quote_id}/refresh`: Refresh a quote
- `POST /marketplace/quote/{quote_id}/settle`: Settle a quote
- `POST /marketplace/quote/{quote_id}/cancel`: Cancel a quote
- `POST /marketplace/quote/{quote_id}/pay`: Pay a quote
- `POST /marketplace/quote/{quote_id}/deliver`: Deliver a quote
- `GET /marketplace/purchases`: List purchases
- `GET /marketplace/purchases/{purchase_id}/wallets`: List purchase wallets
- `GET /marketplace/wallets/by-pubkey/{pubkey}/tokens`: Retrieve a bought wallet's tokens
- `POST /marketplace/wallets/by-pubkey/{pubkey}/sell-all`: Sell all of a bought wallet's tokens

## The Quote object

A reservation of a lot of catalog wallets, with its price and payment state. The client type also declares seller-side fields (`org_id`, `our_price_total`, `margin_total`, `items[].our_price`); the API removes them from buyer responses.

- `id` (string): Quote id (UUID).
- `chain` (string): Marketplace chain slug the quote is priced and paid in.
- `status` (string): Quote state. Only a `reserved` quote can be paid. The API reports `reserved`, then `paid`, `settling` and `settled` as payment completes; `expired`, `cancelled` and `failed` are terminal.
- `items` (array<object>): Reserved wallets.
  - `wallet_id` (string): Marketplace wallet id.
  - `user_price` (string): Price of this wallet in the chain's smallest unit (lamports on Solana, wei on EVM chains), as an integer string.
  - `balance` (string): Native balance of the wallet in the chain's smallest unit (lamports on Solana, wei on EVM chains), as an integer string.
  - `token_holdings` (array<object> | null): Tokens the wallet holds.
    - `mint` (string): Token mint or contract address.
    - `symbol` (string | null): Token symbol, when known.
    - `decimals` (integer | null): Token decimals.
    - `balance` (string): Raw token balance as an integer string. Divide by `10^decimals` (and apply `ui_multiplier`) for display.
    - `ui_multiplier` (string | null): Display multiplier scaled by 1e18, for tokens whose UI amount differs from the raw amount.
    - `usd_value` (number | null): USD value of the holding.
- `user_price_total` (string): Total price of the lot in the chain's smallest unit (lamports on Solana, wei on EVM chains), as an integer string.
- `buyer_ref` (string | null): Buyer reference. The API sets it to the caller's license when the quote is created; a value sent in the request is ignored.
- `pay_address` (string | null): Deposit address to pay. `null` until the marketplace provisions it.
- `pay_checkout_url` (string | null): Checkout URL for an alternative payment rail, when the marketplace provides one.
- `pay_intent_id` (string | null): Marketplace payment intent id.
- `payment_tx_hash` (string | null): Transaction that funded the deposit, once seen.
- `reserved_until` (string): When the hold lapses and the wallets are released (RFC 3339). The quote can still read `reserved` right up to this time.
- `hard_expiry` (string): Hard deadline of the reservation (RFC 3339).
- `created_at` (string): Creation time (RFC 3339).
- `completed_at` (string | null): Completion time (RFC 3339).
- `received_amount` (string | null): Amount received on the deposit address so far, in the chain's smallest unit (lamports on Solana, wei on EVM chains), as an integer string.
- `expected_amount` (string | null): Amount the deposit must reach for the quote to settle, in the chain's smallest unit (lamports on Solana, wei on EVM chains), as an integer string. The web app falls back to `user_price_total` when it is absent.
- `payment_status` (string | null): Payment state reported by the marketplace.
- `sell_tokens_after_purchase` (boolean): Whether the purchase asked for the wallets' tokens to be sold after purchase.

```json
{
  "id": "96332c18-bc7b-48c7-a6a8-e95cc039a9d3",
  "chain": "solana",
  "status": "reserved",
  "items": [
    {
      "wallet_id": "9fb9b985-594c-42e9-9592-fb986f90badb",
      "user_price": "135000000",
      "balance": "41250000",
      "token_holdings": []
    },
    {
      "wallet_id": "b99b3501-9fbb-49a4-b344-226023503aca",
      "user_price": "128000000",
      "balance": "38900000",
      "token_holdings": []
    }
  ],
  "user_price_total": "263000000",
  "buyer_ref": "DEMOUSER-k3Jd8QwZp2LmX7vRt",
  "pay_address": "NEHongC3s1wu2512RY9PeCSKxSafTewh4LaBtZLUwqYa",
  "pay_checkout_url": null,
  "pay_intent_id": null,
  "payment_tx_hash": null,
  "reserved_until": "2026-11-02T14:05:30Z",
  "hard_expiry": "2026-11-02T14:30:00Z",
  "created_at": "2026-11-02T14:00:30Z",
  "completed_at": null,
  "received_amount": "0",
  "expected_amount": "263000000",
  "payment_status": "awaiting_payment",
  "sell_tokens_after_purchase": true
}
```

## The Purchase object

A settled Marketplace order.

- `id` (string): Purchase id.
- `quote_id` (string): Quote the purchase settled.
- `chain` (string): Marketplace chain slug.
- `user_price_total` (string): Amount paid in the chain's smallest unit (lamports on Solana, wei on EVM chains), as an integer string.
- `wallet_count` (integer): Number of wallets bought.
- `settled_at` (string): Settlement time (RFC 3339).
- `payment_tx_hash` (string | null): Payment transaction, when known.

```json
{
  "id": "dcf7c199-074f-4a38-8ea8-83bcaec48e4a",
  "quote_id": "96332c18-bc7b-48c7-a6a8-e95cc039a9d3",
  "chain": "solana",
  "user_price_total": "263000000",
  "wallet_count": 2,
  "settled_at": "2026-11-02T14:02:11Z",
  "payment_tx_hash": "1hngFymVsG1N5viNWg6uyWcKWmdKjJvqt7DkfhGu5CvARP7QMyk81DTiiPU9EkDA33ohCZxzEQxk3qKYWNhBjk8J"
}
```

### Create a quote

`POST /marketplace/quote`

Reserves a lot of catalog wallets and returns its price and deposit address. (Bearer JWT · beta)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Do not retry blindly. Each call reserves another lot, and a lost response leaves no quote id to look up. No funds move: an unpaid hold lapses at `reserved_until`.

The web app sends the exact lot previewed in the catalog as `wallet_ids`, with `count` set to its length, and remembers the quote id locally so an open checkout can resume after a reload. The other filter fields belong to the request type but the SDK method does not set them.

> Creating a quote holds the wallets but moves no funds. An unpaid hold lapses at `reserved_until`; [cancel the quote](#cancel-a-quote) to release it sooner.

#### Body parameters

- `chain` (enum, required): Marketplace chain slug. Possible values: `solana`, `ethereum`, `bsc`, `base`, `robinhood`, `arc`.
- `count` (integer, optional): Number of wallets to reserve. The web app sends the length of `wallet_ids`.
- `wallet_ids` (array<string> | null, optional): Exact catalog wallet ids to reserve.
- `sell_tokens_after_purchase` (boolean, required): Asks for the wallets' tokens to be sold after purchase. The client type only allows `true`.
- `min_balance` (string | null, optional): Minimum native balance in the chain's smallest unit (lamports on Solana, wei on EVM chains), as an integer string.
- `max_balance` (string | null, optional): Maximum native balance in the chain's smallest unit (lamports on Solana, wei on EVM chains), as an integer string.
- `min_age_days` (integer | null, optional): Minimum wallet age, in days.
- `max_age_days` (integer | null, optional): Maximum wallet age, in days.
- `min_gap_seconds` (integer | null, optional): Minimum spacing between funding timestamps, in seconds.
- `source` (string | null, optional): Funding source to draw from.

#### Returns 200 OK

Returns a [Quote](#object-quote) object.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `body must be a json object` | The body is not a JSON object. | Send the body as a JSON object. |
| 422 | `upstream_failure` | `hushxima api issue: <message>` | The marketplace could not be reached, failed, or sent a body the API could not read. The body also carries `service: "hushxima"`. | Retry after a short wait; the failure is on the marketplace side. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/marketplace/quote" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "chain": "solana",
  "count": 2,
  "wallet_ids": [
    "9fb9b985-594c-42e9-9592-fb986f90badb",
    "b99b3501-9fbb-49a4-b344-226023503aca"
  ],
  "sell_tokens_after_purchase": true
}'
```

#### Example response

```json
{
  "id": "96332c18-bc7b-48c7-a6a8-e95cc039a9d3",
  "chain": "solana",
  "status": "reserved",
  "items": [
    {
      "wallet_id": "9fb9b985-594c-42e9-9592-fb986f90badb",
      "user_price": "135000000",
      "balance": "41250000",
      "token_holdings": []
    },
    {
      "wallet_id": "b99b3501-9fbb-49a4-b344-226023503aca",
      "user_price": "128000000",
      "balance": "38900000",
      "token_holdings": []
    }
  ],
  "user_price_total": "263000000",
  "buyer_ref": "DEMOUSER-k3Jd8QwZp2LmX7vRt",
  "pay_address": "NEHongC3s1wu2512RY9PeCSKxSafTewh4LaBtZLUwqYa",
  "pay_checkout_url": null,
  "pay_intent_id": null,
  "payment_tx_hash": null,
  "reserved_until": "2026-11-02T14:05:30Z",
  "hard_expiry": "2026-11-02T14:30:00Z",
  "created_at": "2026-11-02T14:00:30Z",
  "completed_at": null,
  "received_amount": "0",
  "expected_amount": "263000000",
  "payment_status": "awaiting_payment",
  "sell_tokens_after_purchase": true
}
```

### Retrieve a quote

`GET /marketplace/quote/{quote_id}`

Returns a quote with its items and payment state. (Bearer JWT · beta)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: allowed.
- Retry: Safe to retry.

On load, the Marketplace page re-reads the quote it last held and resumes the checkout if it is still `reserved` and `reserved_until` is in the future. During checkout it is the fallback read when [Settle a quote](#settle-a-quote) fails.

#### Path parameters

- `quote_id` (string, required): Quote id returned by [Create a quote](#create-a-quote).

#### Returns 200 OK

Returns a [Quote](#object-quote) object.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 404 | `not_found` | `quote not found` | The quote does not exist or was created by another account. | Use a quote id that [Create a quote](/reference/marketplace-orders/#create-a-quote) returned to this account. |
| 422 | `upstream_failure` | `hushxima api issue: <message>` | The marketplace could not be reached, failed, or sent a body the API could not read. The body also carries `service: "hushxima"`. | Retry after a short wait; the failure is on the marketplace side. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/marketplace/quote/{quote_id}" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "id": "96332c18-bc7b-48c7-a6a8-e95cc039a9d3",
  "chain": "solana",
  "status": "reserved",
  "items": [
    {
      "wallet_id": "9fb9b985-594c-42e9-9592-fb986f90badb",
      "user_price": "135000000",
      "balance": "41250000",
      "token_holdings": []
    },
    {
      "wallet_id": "b99b3501-9fbb-49a4-b344-226023503aca",
      "user_price": "128000000",
      "balance": "38900000",
      "token_holdings": []
    }
  ],
  "user_price_total": "263000000",
  "buyer_ref": "DEMOUSER-k3Jd8QwZp2LmX7vRt",
  "pay_address": "NEHongC3s1wu2512RY9PeCSKxSafTewh4LaBtZLUwqYa",
  "pay_checkout_url": null,
  "pay_intent_id": null,
  "payment_tx_hash": null,
  "reserved_until": "2026-11-02T14:05:30Z",
  "hard_expiry": "2026-11-02T14:30:00Z",
  "created_at": "2026-11-02T14:00:30Z",
  "completed_at": null,
  "received_amount": "0",
  "expected_amount": "263000000",
  "payment_status": "awaiting_payment",
  "sell_tokens_after_purchase": true
}
```

### List quotes

`GET /marketplace/quotes`

Returns the caller's quotes. (Bearer JWT · beta · web client only)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: allowed.
- Retry: Safe to retry.

The Marketplace page shows each returned quote as a chip with its wallet count, total and status.

The API does not serve this route yet: it answers `404` with an empty body. Keep the IDs returned by [Create a quote](/reference/marketplace-orders/#create-a-quote) until it does.

#### Returns 200 OK

Returns an array of [Quote](#object-quote) objects.

#### Example request

```bash
curl "https://api-mig.proxima.tools/marketplace/quotes" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
[
  {
    "id": "96332c18-bc7b-48c7-a6a8-e95cc039a9d3",
    "chain": "solana",
    "status": "reserved",
    "items": [
      {
        "wallet_id": "9fb9b985-594c-42e9-9592-fb986f90badb",
        "user_price": "135000000",
        "balance": "41250000",
        "token_holdings": []
      },
      {
        "wallet_id": "b99b3501-9fbb-49a4-b344-226023503aca",
        "user_price": "128000000",
        "balance": "38900000",
        "token_holdings": []
      }
    ],
    "user_price_total": "263000000",
    "buyer_ref": "DEMOUSER-k3Jd8QwZp2LmX7vRt",
    "pay_address": "NEHongC3s1wu2512RY9PeCSKxSafTewh4LaBtZLUwqYa",
    "pay_checkout_url": null,
    "pay_intent_id": null,
    "payment_tx_hash": null,
    "reserved_until": "2026-11-02T14:05:30Z",
    "hard_expiry": "2026-11-02T14:30:00Z",
    "created_at": "2026-11-02T14:00:30Z",
    "completed_at": null,
    "received_amount": "0",
    "expected_amount": "263000000",
    "payment_status": "awaiting_payment",
    "sell_tokens_after_purchase": true
  }
]
```

### List quote wallets

`GET /marketplace/quote/{quote_id}/wallets`

Returns the wallets a quote reserved, with their addresses. (Bearer JWT · beta)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: allowed.
- Retry: Safe to retry.

A durable snapshot of the reserved lot: it stays readable after the hold expires or is cancelled.

> Not called by the current web app.

#### Path parameters

- `quote_id` (string, required): Quote id returned by [Create a quote](#create-a-quote).

#### Returns 200 OK

- `wallet_id` (string): Marketplace wallet id.
- `pubkey` (string): Wallet address.
- `user_price` (string): Price of the wallet in the chain's smallest unit (lamports on Solana, wei on EVM chains), as an integer string.
- `balance` (string): Native balance in the chain's smallest unit (lamports on Solana, wei on EVM chains), as an integer string.
- `age_days_at_reserve` (string | null): Wallet age in days when reserved, as a decimal string.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 404 | `not_found` | `quote not found` | The quote does not exist or was created by another account. | Use a quote id that [Create a quote](/reference/marketplace-orders/#create-a-quote) returned to this account. |
| 422 | `upstream_failure` | `hushxima api issue: <message>` | The marketplace could not be reached, failed, or sent a body the API could not read. The body also carries `service: "hushxima"`. | Retry after a short wait; the failure is on the marketplace side. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/marketplace/quote/{quote_id}/wallets" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
[
  {
    "wallet_id": "9fb9b985-594c-42e9-9592-fb986f90badb",
    "pubkey": "mEQxMmVdmn9yzhgz4iHCejoj6QuKuCwXmc56ZNVRcrNk",
    "user_price": "135000000",
    "balance": "41250000",
    "age_days_at_reserve": "80.2"
  }
]
```

### Refresh a quote

`POST /marketplace/quote/{quote_id}/refresh`

Extends a quote's reservation hold. (Bearer JWT · beta)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. A repeat only pushes the hold back again, within the quote's cap.

Each refresh pushes `reserved_until` back by 30 seconds, within the quote's cap. The checkout calls it once when it opens on an unsettled quote.

#### Path parameters

- `quote_id` (string, required): Quote id returned by [Create a quote](#create-a-quote).

#### Returns 200 OK

Returns the updated [Quote](#object-quote) object.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 404 | `not_found` | `quote not found` | The quote does not exist or was created by another account. | Use a quote id that [Create a quote](/reference/marketplace-orders/#create-a-quote) returned to this account. |
| 422 | `upstream_failure` | `hushxima api issue: <message>` | The marketplace could not be reached, failed, or sent a body the API could not read. The body also carries `service: "hushxima"`. | Retry after a short wait; the failure is on the marketplace side. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/marketplace/quote/{quote_id}/refresh" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "id": "96332c18-bc7b-48c7-a6a8-e95cc039a9d3",
  "chain": "solana",
  "status": "reserved",
  "items": [
    {
      "wallet_id": "9fb9b985-594c-42e9-9592-fb986f90badb",
      "user_price": "135000000",
      "balance": "41250000",
      "token_holdings": []
    },
    {
      "wallet_id": "b99b3501-9fbb-49a4-b344-226023503aca",
      "user_price": "128000000",
      "balance": "38900000",
      "token_holdings": []
    }
  ],
  "user_price_total": "263000000",
  "buyer_ref": "DEMOUSER-k3Jd8QwZp2LmX7vRt",
  "pay_address": "NEHongC3s1wu2512RY9PeCSKxSafTewh4LaBtZLUwqYa",
  "pay_checkout_url": null,
  "pay_intent_id": null,
  "payment_tx_hash": null,
  "reserved_until": "2026-11-02T14:05:30Z",
  "hard_expiry": "2026-11-02T14:30:00Z",
  "created_at": "2026-11-02T14:00:30Z",
  "completed_at": null,
  "received_amount": "0",
  "expected_amount": "263000000",
  "payment_status": "awaiting_payment",
  "sell_tokens_after_purchase": true
}
```

### Settle a quote

`POST /marketplace/quote/{quote_id}/settle`

Confirms the purchase and forces a payment check. (Bearer JWT · beta)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Settling only checks the payment and confirms the buyer; it never charges or books the sale twice.

Optional: a quote settles on its own once the deposit reaches `expected_amount`. The call is safe to repeat. The checkout calls it right after paying, then every 4 seconds until the quote settles.

#### Path parameters

- `quote_id` (string, required): Quote id returned by [Create a quote](#create-a-quote).

#### Returns 200 OK

Returns the updated [Quote](#object-quote) object.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 404 | `not_found` | `quote not found` | The quote does not exist or was created by another account. | Use a quote id that [Create a quote](/reference/marketplace-orders/#create-a-quote) returned to this account. |
| 422 | `upstream_failure` | `hushxima api issue: <message>` | The marketplace could not be reached, failed, or sent a body the API could not read. The body also carries `service: "hushxima"`. | Retry after a short wait; the failure is on the marketplace side. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/marketplace/quote/{quote_id}/settle" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "id": "96332c18-bc7b-48c7-a6a8-e95cc039a9d3",
  "chain": "solana",
  "status": "settled",
  "items": [
    {
      "wallet_id": "9fb9b985-594c-42e9-9592-fb986f90badb",
      "user_price": "135000000",
      "balance": "41250000",
      "token_holdings": []
    },
    {
      "wallet_id": "b99b3501-9fbb-49a4-b344-226023503aca",
      "user_price": "128000000",
      "balance": "38900000",
      "token_holdings": []
    }
  ],
  "user_price_total": "263000000",
  "buyer_ref": "DEMOUSER-k3Jd8QwZp2LmX7vRt",
  "pay_address": "NEHongC3s1wu2512RY9PeCSKxSafTewh4LaBtZLUwqYa",
  "pay_checkout_url": null,
  "pay_intent_id": null,
  "payment_tx_hash": "1hngFymVsG1N5viNWg6uyWcKWmdKjJvqt7DkfhGu5CvARP7QMyk81DTiiPU9EkDA33ohCZxzEQxk3qKYWNhBjk8J",
  "reserved_until": "2026-11-02T14:05:30Z",
  "hard_expiry": "2026-11-02T14:30:00Z",
  "created_at": "2026-11-02T14:00:30Z",
  "completed_at": "2026-11-02T14:02:11Z",
  "received_amount": "263000000",
  "expected_amount": "263000000",
  "payment_status": "awaiting_payment",
  "sell_tokens_after_purchase": true
}
```

### Cancel a quote

`POST /marketplace/quote/{quote_id}/cancel`

Releases a quote's reserved wallets. (Bearer JWT · beta)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. A repeat after a successful cancel answers `409`.

The checkout cancels the held quote when it is closed before any payment was sent, and ignores failures because the hold may already be settled or expired.

#### Path parameters

- `quote_id` (string, required): Quote id returned by [Create a quote](#create-a-quote).

#### Returns 200 OK

- `ok` (boolean): `true` when the reservation was released.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 404 | `not_found` | `quote not found` | The quote does not exist or was created by another account. | Use a quote id that [Create a quote](/reference/marketplace-orders/#create-a-quote) returned to this account. |
| 409 | `conflict` | `<message>` | The quote can no longer be cancelled, and the message is the marketplace's. If it settled in the meantime, the API delivers its wallets to the caller's account. | Read the quote's `status` with [Retrieve a quote](/reference/marketplace-orders/#retrieve-a-quote); a `settled` quote has already been delivered. |
| 422 | `upstream_failure` | `hushxima api issue: <message>` | The marketplace could not be reached, failed, or sent a body the API could not read. The body also carries `service: "hushxima"`. | Retry after a short wait; the failure is on the marketplace side. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/marketplace/quote/{quote_id}/cancel" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "ok": true
}
```

### Pay a quote

`POST /marketplace/quote/{quote_id}/pay`

Pays a reserved quote from one of the caller's funder wallets. (Bearer JWT · 2FA step-up · beta)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Two-factor: step-up for `wallet.withdraw` when the user protects it (`401 2fa_required`).
- Retry: Check before retrying. A lost call may have sent funds. Read the quote with [Retrieve a quote](/reference/marketplace-orders/#retrieve-a-quote): a higher `received_amount` or a `status` past `reserved` means it was paid, and the API refuses a second payment while one is unconfirmed.

The amount and destination are not parameters: the API sends `expected_amount − received_amount` to the quote's `pay_address`, so a partial deposit is topped up rather than paid twice. The network fee is paid on top of the amount. After a successful call the checkout settles the quote and polls until it does.

> **Moves funds.** The call signs and sends a transfer from the selected funder. It is not idempotent: only the checks above stop a second debit.

> Accounts that protect withdrawals with 2FA are challenged here, because the deposit address is not one of their funders.

#### Path parameters

- `quote_id` (string, required): Quote id returned by [Create a quote](#create-a-quote).

#### Body parameters

- `funder_pubkey` (string, required): Funder wallet that pays: a base58 pubkey on Solana, a `0x` address on EVM chains. It must belong to the caller's license.

#### Returns 200 OK

- `ok` (boolean): `true` when the transfer was sent.
- `quote_id` (string): Quote that was paid.
- `chain` (string): Chain the payment was sent on.
- `recipient` (string): Deposit address that received the payment.
- `amount_sent` (string): Amount sent in the chain's smallest unit (lamports on Solana, wei on EVM chains), as an integer string.
- `tx` (string): Payment transaction signature or hash.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `funder_pubkey is required` | `funder_pubkey` is missing or blank. A body that does not parse answers `invalid body: <detail>`. | Send `funder_pubkey` with the address of the wallet that pays. |
| 400 | `bad_request` | `wallet not found for license: <funder_pubkey>` | `funder_pubkey` is not a wallet of the caller's account whose key the API holds. On EVM chains the message is `no signable wallet for license: <address>`, and an address that does not parse answers `invalid funder address: <address>`. | Pay from one of the account's own wallets, such as one returned by [List funders](/reference/funders/#list-funders). |
| 404 | `not_found` | `quote not found` | The quote does not exist or was created by another account. | Use a quote id that [Create a quote](/reference/marketplace-orders/#create-a-quote) returned to this account. |
| 409 | `conflict` | `the reservation expires in <seconds>s — refresh the hold before paying` | Fewer than 15 seconds remain on the hold, too little for a transfer to land and be seen. | Extend the hold with [Refresh a quote](/reference/marketplace-orders/#refresh-a-quote), then pay again. |
| 409 | `conflict` | `quote is <status> and cannot be paid` | The quote is not `reserved`, so it cannot be paid. A hold that has already run out answers `the reservation has expired — reserve the lot again`. | Reserve the lot again with [Create a quote](/reference/marketplace-orders/#create-a-quote). |
| 409 | `conflict` | `the deposit address is not provisioned yet` | The marketplace has not provisioned the deposit address yet. | Wait until [Retrieve a quote](/reference/marketplace-orders/#retrieve-a-quote) returns a `pay_address`, then pay again. |
| 409 | `conflict` | `a payment for this quote has already been sent and is waiting to be credited` | A payment for this quote is already in flight or waiting to be credited, so the API refuses to send another. Related messages: `the deposit is already funded — waiting for settlement`, `payment already landed; waiting for settlement`, `payment confirmation is pending; retry to check its status`. | Poll [Settle a quote](/reference/marketplace-orders/#settle-a-quote) until the quote settles instead of paying again. |
| 409 | `conflict` | `funder holds <balance> lamports, needs <needed>` | The funder cannot cover the amount plus the network fee. On EVM chains the amounts are in wei. | Top up the funder, or pay from another wallet returned by [List funders](/reference/funders/#list-funders). |
| 422 | `upstream_failure` | `hushxima api issue: payment confirmation is pending; retry to check its status` | The transfer was sent but has not confirmed yet. The quote stays locked to that payment, so a retry checks it instead of sending again. Other messages with this code: `hushxima api issue: payment transfer did not land; you can retry payment` (the transfer expired without landing and the lock is released), `hushxima api issue: payment transfer failed: <error>`, and any marketplace failure. | Retry the call to check the transfer, or read `received_amount` with [Retrieve a quote](/reference/marketplace-orders/#retrieve-a-quote). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/marketplace/quote/{quote_id}/pay" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "funder_pubkey": "Fgi2HMYCFt7Hu4ZR7fmiHNxQQvqVDgPx8WUz23zE33Xc"
}'
```

#### Example response

```json
{
  "ok": true,
  "quote_id": "96332c18-bc7b-48c7-a6a8-e95cc039a9d3",
  "chain": "sol",
  "recipient": "NEHongC3s1wu2512RY9PeCSKxSafTewh4LaBtZLUwqYa",
  "amount_sent": "263000000",
  "tx": "1hngFymVsG1N5viNWg6uyWcKWmdKjJvqt7DkfhGu5CvARP7QMyk81DTiiPU9EkDA33ohCZxzEQxk3qKYWNhBjk8J"
}
```

### Deliver a quote

`POST /marketplace/quote/{quote_id}/deliver`

Imports a settled quote's wallets into the caller's account. (Bearer JWT · beta)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Delivery is idempotent: a repeat imports no wallet twice, and `imported` counts only new ones.

Settlement is asynchronous, so poll this call: while the quote has not settled it answers `pending: true` with `imported: 0` and the current `status`. Once settled, the wallets are added to the account with their original funding time and venue, and the web app adds them to the chosen folders. Replaying a delivery is safe and never books the sale twice.

#### Path parameters

- `quote_id` (string, required): Quote id returned by [Create a quote](#create-a-quote).

#### Returns 200 OK

- `imported` (integer): Number of wallets imported by this call.
- `pending` (boolean): `true` while the quote has not settled yet.
- `status` (string | null): Quote status, e.g. `paid`, `settling` or `settled`.
- `wallets` (array<object>): Delivered wallets.
  - `wallet_id` (string): Marketplace wallet id.
  - `pubkey` (string): Wallet address, now in the caller's account.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 404 | `not_found` | `quote not found` | The quote does not exist or was created by another account. | Use a quote id that [Create a quote](/reference/marketplace-orders/#create-a-quote) returned to this account. |
| 409 | `conflict` | `quote is <status> — nothing to deliver` | The quote reached `expired`, `cancelled` or `failed` and can never be delivered. | Start a new purchase with [Create a quote](/reference/marketplace-orders/#create-a-quote). |
| 422 | `upstream_failure` | `hushxima api issue: <message>` | The marketplace could not be reached, failed, or sent a body the API could not read. The body also carries `service: "hushxima"`. | Retry after a short wait; the failure is on the marketplace side. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/marketplace/quote/{quote_id}/deliver" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "imported": 2,
  "pending": false,
  "status": "settled",
  "wallets": [
    {
      "wallet_id": "9fb9b985-594c-42e9-9592-fb986f90badb",
      "pubkey": "mEQxMmVdmn9yzhgz4iHCejoj6QuKuCwXmc56ZNVRcrNk"
    },
    {
      "wallet_id": "b99b3501-9fbb-49a4-b344-226023503aca",
      "pubkey": "nFSZLpyf9UfANbyDzSf6igfD9CmTe975LeakYJEWiw4"
    }
  ]
}
```

### List purchases

`GET /marketplace/purchases`

Returns the caller's settled purchases, newest first. (Bearer JWT · beta)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: allowed.
- Retry: Safe to retry.

Feeds the purchase history in the Marketplace and the wallet import pickers of the launch and funding flows.

#### Query parameters

- `limit` (integer, optional, default "50"): Maximum number of purchases. The web app always sends `100`; the API defaults to 50 and caps at 500.

#### Returns 200 OK

Returns an array of [Purchase](#object-purchase) objects.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 422 | `upstream_failure` | `hushxima api issue: <message>` | The marketplace could not be reached, failed, or sent a body the API could not read. The body also carries `service: "hushxima"`. | Retry after a short wait; the failure is on the marketplace side. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/marketplace/purchases" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
[
  {
    "id": "dcf7c199-074f-4a38-8ea8-83bcaec48e4a",
    "quote_id": "96332c18-bc7b-48c7-a6a8-e95cc039a9d3",
    "chain": "solana",
    "user_price_total": "263000000",
    "wallet_count": 2,
    "settled_at": "2026-11-02T14:02:11Z",
    "payment_tx_hash": "1hngFymVsG1N5viNWg6uyWcKWmdKjJvqt7DkfhGu5CvARP7QMyk81DTiiPU9EkDA33ohCZxzEQxk3qKYWNhBjk8J"
  }
]
```

### List purchase wallets

`GET /marketplace/purchases/{purchase_id}/wallets`

Returns the wallets bought in one of the caller's purchases. (Bearer JWT · beta)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: allowed.
- Retry: Safe to retry.

The web app reads it to import a past order's wallets into a launch or a funding run.

#### Path parameters

- `purchase_id` (string, required): Purchase id from [List purchases](#list-purchases).

#### Returns 200 OK

- `wallet_id` (string): Marketplace wallet id.
- `pubkey` (string): Wallet address.
- `user_price` (string): Price paid for the wallet in the chain's smallest unit (lamports on Solana, wei on EVM chains), as an integer string.
- `age_days_at_sale` (string | null): Wallet age in days at the time of sale, as a decimal string.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 404 | `not_found` | `purchase not found` | The purchase does not exist or belongs to another license. | Use a purchase id returned by [List purchases](/reference/marketplace-orders/#list-purchases). |
| 422 | `upstream_failure` | `hushxima api issue: <message>` | The marketplace could not be reached, failed, or sent a body the API could not read. The body also carries `service: "hushxima"`. | Retry after a short wait; the failure is on the marketplace side. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/marketplace/purchases/{purchase_id}/wallets" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
[
  {
    "wallet_id": "9fb9b985-594c-42e9-9592-fb986f90badb",
    "pubkey": "mEQxMmVdmn9yzhgz4iHCejoj6QuKuCwXmc56ZNVRcrNk",
    "user_price": "135000000",
    "age_days_at_sale": "80.2"
  },
  {
    "wallet_id": "b99b3501-9fbb-49a4-b344-226023503aca",
    "pubkey": "nFSZLpyf9UfANbyDzSf6igfD9CmTe975LeakYJEWiw4",
    "user_price": "128000000",
    "age_days_at_sale": "64.7"
  }
]
```

### Retrieve a bought wallet's tokens

`GET /marketplace/wallets/by-pubkey/{pubkey}/tokens`

Returns the tokens a delivered Marketplace wallet still holds, with any queued operations. (Bearer JWT · beta)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: allowed.
- Retry: Safe to retry.

Used by the *Sell all tokens* panel, which is switched off in the current web app.

#### Path parameters

- `pubkey` (string, required): Address of a wallet bought on the Marketplace and delivered to the caller's account (base58 on Solana, `0x` address on EVM).

#### Returns 200 OK

- `wallet_id` (string): Marketplace wallet id.
- `pubkey` (string): Wallet address.
- `chain` (string): Chain slug of the wallet.
- `count` (integer): Number of tokens listed.
- `has_tokens` (boolean): Whether the wallet holds any token.
- `has_sellable_tokens` (boolean): Whether any token can be sold.
- `has_queued_sell` (boolean): Whether a sell is already queued.
- `has_queued_withdraw` (boolean): Whether a withdrawal is already queued.
- `native_balance` (string): Native balance in the chain's smallest unit (lamports on Solana, wei on EVM chains), as an integer string.
- `total_usd_value` (number): USD value of all tokens.
- `sellable_usd_value` (number): USD value of the sellable part.
- `tokens` (array<object>): Token positions.
  - `mint` (string): Token mint or contract address.
  - `symbol` (string | null): Token symbol.
  - `decimals` (integer): Token decimals.
  - `balance` (string): Raw balance as an integer string.
  - `ui_multiplier` (string | null): Display multiplier scaled by 1e18.
  - `usd_value` (number): USD value of the balance.
  - `sellable_balance` (string): Raw sellable balance as an integer string.
  - `sellable_usd_value` (number): USD value of the sellable balance.
  - `post_sale` (boolean): `true` for a token received after the sale. The web app leaves these out of *Sell all*.
- `queued_operations` (array<object>): Sells and withdrawals in progress on the wallet.
  - `id` (string): Operation id.
  - `kind` (string): Operation kind.
  - `mint` (string): Token concerned.
  - `status` (string): Operation status.
  - `to_address` (string): Destination address.
  - `tx_hash` (string): Transaction, once sent.
  - `created_at` (string): Queue time.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 404 | `not_found` | `wallet not found` | `wallet not found`: the address is not one of the caller's delivered Marketplace wallets. The web app skips these wallets silently. | Use the address of a wallet imported by [Deliver a quote](/reference/marketplace-orders/#deliver-a-quote). |
| 422 | `upstream_failure` | `hushxima api issue: <message>` | The marketplace could not be reached, failed, or sent a body the API could not read. The body also carries `service: "hushxima"`. | Retry after a short wait; the failure is on the marketplace side. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/marketplace/wallets/by-pubkey/{pubkey}/tokens" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "wallet_id": "9fb9b985-594c-42e9-9592-fb986f90badb",
  "pubkey": "mEQxMmVdmn9yzhgz4iHCejoj6QuKuCwXmc56ZNVRcrNk",
  "chain": "solana",
  "count": 1,
  "has_tokens": true,
  "has_sellable_tokens": true,
  "has_queued_sell": false,
  "has_queued_withdraw": false,
  "native_balance": "40180000",
  "total_usd_value": 0.84,
  "sellable_usd_value": 0.84,
  "tokens": [
    {
      "mint": "1kF6kS9Z9RitRBAbgT6LzzxDrdr8odsxtqfEE7PWRCF",
      "symbol": "DEMO",
      "decimals": 6,
      "balance": "1520000000",
      "ui_multiplier": null,
      "usd_value": 0.84,
      "sellable_balance": "1520000000",
      "sellable_usd_value": 0.84,
      "post_sale": false
    }
  ],
  "queued_operations": []
}
```

### Sell all of a bought wallet's tokens

`POST /marketplace/wallets/by-pubkey/{pubkey}/sell-all`

Queues a sale of every token a delivered Marketplace wallet holds. (Bearer JWT · beta)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Check before retrying. A repeat queues a sale of whatever the wallet holds by then. Check `has_queued_sell` with [Retrieve a bought wallet's tokens](/reference/marketplace-orders/#retrieve-wallet-tokens) before retrying.

Takes no body. Returns the queued operation ids; follow them with [Retrieve a bought wallet's tokens](#retrieve-wallet-tokens). A wallet that was paid for but not yet delivered is not addressable. The web app's caller sits in the *Sell all tokens* panel, which is switched off.

> Sale proceeds stay on the wallet as its native token; nothing is transferred out. The call is not idempotent: a second call sells whatever arrived in between.

#### Path parameters

- `pubkey` (string, required): Address of a wallet bought on the Marketplace and delivered to the caller's account (base58 on Solana, `0x` address on EVM).

#### Returns 200 OK

- `wallet_id` (string): Marketplace wallet id.
- `chain` (string): Chain slug of the wallet.
- `tokens` (integer): Number of tokens queued for sale.
- `operation_ids` (array<string>): Ids of the queued sell operations.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 404 | `not_found` | `wallet not found` | `wallet not found`: the address is not one of the caller's delivered Marketplace wallets. The web app skips these wallets silently. | Use the address of a wallet imported by [Deliver a quote](/reference/marketplace-orders/#deliver-a-quote). |
| 422 | `upstream_failure` | `hushxima api issue: <message>` | The marketplace could not be reached, failed, or sent a body the API could not read. The body also carries `service: "hushxima"`. | Check `has_queued_sell` with [Retrieve a bought wallet's tokens](/reference/marketplace-orders/#retrieve-wallet-tokens) before retrying. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/marketplace/wallets/by-pubkey/{pubkey}/sell-all" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "wallet_id": "9fb9b985-594c-42e9-9592-fb986f90badb",
  "chain": "solana",
  "tokens": 1,
  "operation_ids": [
    "79645c07-73aa-4ea5-9b52-a83291f35785"
  ]
}
```
