X Money

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:

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.

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.

Getting Started

Self-hosting

Federation

Administration

API

Development

The disclaimer

Endpoints

Your wallet

Sending money

Requesting money

Activity

Objects

Payment

Request

Errors

​The disclaimer

​Endpoints

​Your wallet

​Sending money

​Requesting money

​Activity

​Objects

​Payment

​Request

​Errors

The disclaimer

Endpoints

Your wallet

Sending money

Requesting money

Activity

Objects

Payment

Request

Errors