> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vetox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Vito API and purchases

> Let approved apps charge your Vito with PIN confirmation, and manage payment requests from your Purchases page.

<Info>
  Requires a **Silver** Membership or above — both to apply and for every authenticated call. If the key owner's Membership lapses, the key stops working.
</Info>

A REST API for applications that want to charge or credit Vito — a shop, a game, a rewards integration.

## Applying

A four-step form: **Project**, **Usage**, **Security**, **Review**, plus three acknowledgements. Applications are reviewed by staff.

<Tip>
  Be concrete about what you are building and how you will store the key. Vague applications are the ones that get rejected.
</Tip>

## Your key

Keys look like `vito_live_…`.

<Warning>
  **The key is shown once.** Vetox stores only a hash and cannot show it again. Copy it immediately.

  You have a **7-day window** to reveal it after approval. Miss that and you must rotate to get a new one.
</Warning>

Rotation issues a new key and keeps the old one working for **24 hours** so you can deploy without downtime.

## Webhooks

You also get a signing secret, `whsec_…`. Verify every incoming webhook against it.

<Note>
  During a rotation's 24-hour overlap, webhooks are signed with **both** secrets. Accept either until the overlap ends.
</Note>

## Scopes

| Scope               | Grants                                      |
| ------------------- | ------------------------------------------- |
| `balance:read`      | Read a member's balance                     |
| `deduct:create`     | Charge a member                             |
| `credit:create`     | Credit a member                             |
| `transfer:create`   | Move Vito between members                   |
| `transactions:read` | Read transaction history and webhook events |

## Endpoints

| Endpoint                          | Scope               |
| --------------------------------- | ------------------- |
| `POST /v1/auth/verify`            | any                 |
| `POST /v1/auth/rotate-key`        | any                 |
| `GET /v1/balance/:discordId`      | `balance:read`      |
| `POST /v1/deduct`                 | `deduct:create`     |
| `POST /v1/add`                    | `credit:create`     |
| `POST /v1/transfer`               | `transfer:create`   |
| `GET /v1/transactions` and `/:id` | `transactions:read` |
| `GET /v1/webhooks/events`         | `transactions:read` |

## Charging a member

<Warning>
  **Your application can never take Vito without the member's explicit approval.**

  A charge creates a [payment request](/en/account/payment-requests). The member opens it on the Vetox website and enters their PIN there. Your application never sees the PIN, and no amount of API access can bypass this.
</Warning>

Requests expire after **10 minutes**.

## Fees

The settlement fee applies to charges and transfers:

| Member's Membership  | Fee |
| -------------------- | --- |
| Normal, Silver, Gold | 7%  |
| Platinum             | 6%  |
| Diamond              | 5%  |

<Note>
  Amounts of **5 Vito or less** are fee-free, and **credits via `/v1/add` are always fee-free**.
</Note>

## Rate limits

| Key owner's Membership | Per minute | Per hour |
| ---------------------- | ---------- | -------- |
| None                   | 60         | 1,000    |
| Silver or Gold         | 180        | 5,000    |
| Platinum or Diamond    | 600        | 15,000   |

There is also a per-IP limit of half your per-minute allowance, with a floor of 30.

<Warning>
  Under heavy load, **write endpoints fail closed** — a charge is rejected rather than risking a double-spend. Read endpoints fail open. Build retry logic that treats a rejected write as "did not happen".
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Every call returns unauthorised">
    The key owner's Membership has lapsed. It is checked on every call, not just at issue.
  </Accordion>

  <Accordion title="I lost my key">
    It cannot be recovered. Rotate to get a new one.
  </Accordion>

  <Accordion title="Webhook signatures fail after rotating">
    Accept both secrets during the 24-hour overlap.
  </Accordion>

  <Accordion title="A charge never completes">
    The member has not approved it. Requests expire after 10 minutes.
  </Accordion>

  <Accordion title="Less Vito arrived than I charged">
    The settlement fee. Use amounts of 5 or less to avoid it, or account for it.
  </Accordion>
</AccordionGroup>

<Card title="Payment Requests" icon="receipt" horizontal href="/en/account/payment-requests">
  What the member sees when you charge them.
</Card>