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

# X Money

> Balances, payments and requests through the public API.

X Money lets accounts send each other money. It's the instance's own play money, with no cash value.

X Money is off by default. Admins turn it on and set its limits in Admin > Money. When it's off, every `/money` endpoint answers `404`.

## The disclaimer

Each account must accept X Money's disclaimer once before any money moves. Until then, endpoints that move or list money answer `403`. Show the user the `disclaimer` text from `GET /money`, then accept it:

```bash theme={null}
curl -X POST https://xit.example.org/api/v1/money/disclaimer \
  -H "Authorization: Bearer $TOKEN"
```

## Endpoints

| Method | Path | Scope | Description |
| - | - | - | - |
| `GET` | `/money` | read | Your wallet and the instance's settings. Works before the disclaimer is accepted. |
| `POST` | `/money/disclaimer` | write | Accept the disclaimer, once. |
| `GET` | `/money/activity` | read | Your payments, newest first. Pages with `cursor`. |
| `GET` | `/money/requests` | read | Open requests: asking you to pay, and yours waiting on others. |
| `POST` | `/money/send` | write | Pay someone, or pay a request. |
| `POST` | `/money/requests` | write | Ask for money. |
| `POST` | `/money/requests/{id}/decline` | write | Decline a request of you. |
| `POST` | `/money/requests/{id}/cancel` | write | Cancel your own request. |
| `GET` | `/money/payments/{id}` | read | One payment you're part of, or one its sender or recipient put in a post (the `/i/xmoney/p/{id}` address). |
| `GET` | `/money/requests/{id}` | read | One request (the `/i/xmoney/r/{id}` address). |

## Your wallet

`GET /money` returns:

| Field | Description |
| - | - |
| `name` | The currency's name, for example `Xitter Money`. |
| `balance_cents` | Your balance. |
| `disclaimer_accepted` | Whether you've accepted the disclaimer. |
| `disclaimer` | The disclaimer text to show. |
| `max_transfer_cents` | The largest single payment. |
| `like_cents` | What a post's author earns per like. |
| `note_max` | The longest note. |

## Sending money

`POST /money/send` takes:

| Field | Required | Description |
| - | - | - |
| `to` | yes | A username on this instance. |
| `amount_cents` | yes | A whole number of cents over 0. |
| `idempotency_key` | yes | A unique key: 8–64 letters, digits, `-` or `_`. Sending the same key again doesn't pay twice. |
| `note` | no | A note for the payment. |
| `request_id` | no | The request this payment pays. |

```bash theme={null}
curl -X POST https://xit.example.org/api/v1/money/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to": "alice", "amount_cents": 250, "note": "coffee", "idempotency_key": "coffee-2026-10-23"}'
```

A new payment answers `201`. A repeat of an earlier `idempotency_key` answers `200` with the original payment.

## Requesting money

`POST /money/requests` takes:

| Field | Required | Description |
| - | - | - |
| `from` | no | A username to ask. Leave it out for a "Pay @you" card anyone can pay. |
| `amount_cents` | with `from` | A whole number of cents over 0. |
| `note` | no | A note for the request. |

The new request's `url` shows as a card when it's put in a post.

## Activity

`GET /money/activity` lists your payments, newest first, and pages with `cursor` and `next_cursor` like other lists. The first page also has `earnings`: what likes paid you, by day, for the last 30 days with any, each with `day`, `likes` and `cents`.

## Objects

### Payment

| Field | Description |
| - | - |
| `id` | Payment id. |
| `amount_cents` | Amount. |
| `note` | Note. |
| `created_at` | When it was sent. |
| `direction` | `sent` or `received`, from your side; `null` if you're neither. |
| `sender`, `recipient` | Accounts. One you can no longer see (a block since) keeps only `id`, `screen_name`, `name` and `avatar_url`. |
| `merchant` | For a payment to a business in merchant mode: `name` and `banner_url`. Otherwise `null`. |
| `reversed` | Whether the payment was reversed. |
| `url` | Its `/i/xmoney/p/{id}` address. |

### Request

| Field | Description |
| - | - |
| `id` | Request id. |
| `amount_cents` | Amount asked. |
| `note` | Note. |
| `status` | `open` while it can be acted on. |
| `created_at` | When it was made. |
| `requester` | Who asked. |
| `payer` | Who was asked, or `null` if anyone may pay. |
| `paid_count`, `paid_cents` | How many payments it got, and their total. |
| `url` | Its `/i/xmoney/r/{id}` address. |
| `can_pay`, `can_decline`, `can_cancel` | What you can do with it now. |

## Errors

| Status | Meaning |
| - | - |
| `400` | The payment or request was refused, for example a bad amount or an unknown user. The `error` says why. |
| `403` | Accept the disclaimer first, or a read token tried to write. |
| `404` | X Money is off, or there's no payment or request with that id that you can see. |
| `409` | The request isn't open to you (decline), or isn't yours or isn't open (cancel). |

Sending, requesting, declining and cancelling count toward the normal write limit.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.