curl --fail-with-body "https://maatstays.wtf/v1/finance/balance" \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN"const res = await fetch('https://maatstays.wtf/v1/finance/balance', {
headers: { Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}` },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
for (const partition of body.partitions) {
// One partition per currency. Never add two together.
console.log(partition.currency, partition.available.value);
}
import os
import requests
res = requests.get(
"https://maatstays.wtf/v1/finance/balance",
headers={"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"},
timeout=30,
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
for partition in body["partitions"]:
# One partition per currency. Never add two together.
print(partition["currency"], partition["available"]["value"])
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
type money struct {
Value string `json:"value"`
Currency string `json:"currency"`
}
type partition struct {
Currency string `json:"currency"`
Available money `json:"available"`
}
type balance struct {
Partitions []partition `json:"partitions"`
}
func main() {
req, _ := http.NewRequest(http.MethodGet,
"https://maatstays.wtf/v1/finance/balance", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("MAAT_PARTNER_TOKEN"))
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
var body balance
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
log.Fatal(err)
}
if res.StatusCode >= 400 {
log.Fatalf("balance failed: %d", res.StatusCode)
}
for _, p := range body.Partitions {
fmt.Println(p.Currency, p.Available.Value)
}
}
{
"partitions": [
{
"currency": "EGP",
"pending": {
"value": "4200.00",
"currency": "EGP"
},
"available": {
"value": "18100.00",
"currency": "EGP"
},
"reserved_for_payout": {
"value": "5000.00",
"currency": "EGP"
},
"paid_out_total": {
"value": "96500.00",
"currency": "EGP"
},
"outstanding_penalties": {
"value": "300.00",
"currency": "EGP"
}
},
{
"currency": "USD",
"pending": {
"value": "0.00",
"currency": "USD"
},
"available": {
"value": "640.00",
"currency": "USD"
},
"reserved_for_payout": {
"value": "0.00",
"currency": "USD"
},
"paid_out_total": {
"value": "1280.00",
"currency": "USD"
},
"outstanding_penalties": {
"value": "0.00",
"currency": "USD"
}
}
]
}Read your balance, per currency
Where your money is right now, as one partition per settlement currency.
A workspace has as many balances as it has settled currencies, and they are separate positions — not one figure in a preferred currency. Nothing in this API adds one currency to another and nothing converts between them. If you want a single headline number, convert the partitions yourself, with a rate you chose and can explain.
available + reserved_for_payout + paid_out_total is everything that has cleared.
pending is on top of that and has not: it is money a guest has paid, held until
the stay starts. outstanding_penalties is what you OWE, and it is deliberately
not subtracted from any of them — it is settled from released funds, and netting
it here would make one number mean two things.
A currency you have never traded in is absent, not zero. Absence means nothing has ever happened there.
Live in a sandbox workspace. Returns 501 against a production one. A sandbox
never charges anybody, so it answers { "partitions": [] } — the real shape, with
nothing in it.
curl --fail-with-body "https://maatstays.wtf/v1/finance/balance" \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN"const res = await fetch('https://maatstays.wtf/v1/finance/balance', {
headers: { Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}` },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
for (const partition of body.partitions) {
// One partition per currency. Never add two together.
console.log(partition.currency, partition.available.value);
}
import os
import requests
res = requests.get(
"https://maatstays.wtf/v1/finance/balance",
headers={"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"},
timeout=30,
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
for partition in body["partitions"]:
# One partition per currency. Never add two together.
print(partition["currency"], partition["available"]["value"])
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
type money struct {
Value string `json:"value"`
Currency string `json:"currency"`
}
type partition struct {
Currency string `json:"currency"`
Available money `json:"available"`
}
type balance struct {
Partitions []partition `json:"partitions"`
}
func main() {
req, _ := http.NewRequest(http.MethodGet,
"https://maatstays.wtf/v1/finance/balance", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("MAAT_PARTNER_TOKEN"))
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
var body balance
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
log.Fatal(err)
}
if res.StatusCode >= 400 {
log.Fatalf("balance failed: %d", res.StatusCode)
}
for _, p := range body.Partitions {
fmt.Println(p.Currency, p.Available.Value)
}
}
{
"partitions": [
{
"currency": "EGP",
"pending": {
"value": "4200.00",
"currency": "EGP"
},
"available": {
"value": "18100.00",
"currency": "EGP"
},
"reserved_for_payout": {
"value": "5000.00",
"currency": "EGP"
},
"paid_out_total": {
"value": "96500.00",
"currency": "EGP"
},
"outstanding_penalties": {
"value": "300.00",
"currency": "EGP"
}
},
{
"currency": "USD",
"pending": {
"value": "0.00",
"currency": "USD"
},
"available": {
"value": "640.00",
"currency": "USD"
},
"reserved_for_payout": {
"value": "0.00",
"currency": "USD"
},
"paid_out_total": {
"value": "1280.00",
"currency": "USD"
},
"outstanding_penalties": {
"value": "0.00",
"currency": "USD"
}
}
]
}Authorizations
A short-lived partner token, obtained by exchanging your API key at
POST /token. Send it as Authorization: Bearer <access_token>.
Tokens live for fifteen minutes by default and never for more than an hour. Mint one per batch of work, not one per request.
The token carries the workspace and the environment its key was issued for. You cannot change either by asking: the exchange ignores everything in the request body for exactly that reason.
It also carries the key's scopes (scope, a list). Every operation names a
scope as x-maat-scope, and a token whose key lacks it is refused with
403 insufficient_scope, naming the scope. Scopes are fixed when a key is
issued and are re-read from the key on every request, so a key narrowed today is
narrowed on its next call — the token's scope is what the key held at exchange
time, for your own reading, never what authorizes a request.
x-maat-scope is the floor, and on the quick-action operations it is not the
whole requirement. PUT and DELETE /listings/{listing_id}/quick-actions/{template_key}
carry rules:write, and additionally require pricing:write when
template_key begins pricing. — the capability depends on the template in
the path, because a cleaning fee changes what a guest pays and a minimum stay
does not. The refusal is the same 403 insufficient_scope, naming
pricing:write. The two READS apply the same requirement without erroring:
GET /listings/{listing_id}/quick-actions still lists the pricing.* rows but
withholds their applied state, and GET /listings/{listing_id}/rules omits the
pricing rules entirely and reports pricing_withheld in warnings. These four
are the only operations in this document whose requirement is not exactly their
x-maat-scope, and each of them says so machine-readably:
x-maat-scope-additional lists the second scope it can require and
x-maat-scope-additional-when says what happens without it.
Never send it as a cookie or in a query string, and never store it — store the API key, mint tokens from it.
Response
Your position, one partition per settlement currency.
One partition per settlement currency you have rows in, sorted by currency. A currency you have never traded in is absent, not zero.
Show child attributes
Show child attributes