A team subscription gives an organisation, project or DAO its own pool of IXO credits, shared by the people it adds as members. Each member gets a spend limit per period, and the IXO Protocol enforces that limit. Use this page to set up a team, manage its members and budgets, and top it up from your own application. For what a team subscription means to the people in it, see Team subscriptions.
Current limits
Read this before you build on team subscriptions.
- No service spends a team budget. The billing engine does not charge team subscriptions. AI usage in the QiForge Personal Agent is charged to each person's own credits, not to the team's, whatever budget the person has on a team. See Pay for your Personal Agent with credits.
- API only. There is no IXO Portal screen for teams. Every step on this page is an API call.
- No unfreeze route. A frozen team is unfrozen by IXO support after review.
- No list of a team's top-ups. Top-ups are recorded, but no route returns them.
The routes are available on devnet, testnet and mainnet.
What a team subscription is
- The team is an IXO entity,
did:ixo:entity:…: an organisation, a project or a DAO. - The subscription deed. Setup creates a subscription deed (an entity of type
deed/subscription) for the team. The IXO subscriptions service owns the deed and is its only controller. The deed links to the team entity with the relationshipsubscriber. A manager of the team does not own the deed. - The shared balance. The deed's admin account holds the team's PAY. 1 credit is 1 PAY, and
1 PAY is US$1 (1,000,000
upay). PAY is internal credit. It cannot be withdrawn: there is no route for it, and no manager or member is given permission to send it. - Two claim collections. The deed has a subscription collection, for the service's own top-up claims, and an oracle collection, where members' budgets live and where oracles would charge usage. The oracle collection requires intents (see How budgets are enforced on chain).
- Managers set the team up, add and remove members, set budgets and top up. See Who manages a team.
- Members are IXO accounts (
ixo1…) with a budget on the team's oracle collection. The chain is the only record of who is a member. A member needs no role in the team entity.
Who manages a team
The service decides who manages a team from the team entity's record in IXO Blocksync, on every request. The caller is a manager when the caller's DID is one of these:
- a
controllerof the team entity; - the entity's
owner, asdid:ixo:<owner address>; - a
linkedEntityof the entity withservicematrixandrelationshipadmin; - for a DAO named in 1, 2 or 3 as
did:ixo:wasm:<address>: an account with positive voting power in that DAO. That is a member of its cw4 group with a weight above 0, a staker with a cw20 or native token stake above 0, or a staker of an NFT (cw721) in it. The address is also checked as a cw4 group in its own right.
Rule 4 is the same DAO membership rule that IXO Matrix rooms and the virtual file store use. Any stake counts: one staked token unit, or one staked NFT, is enough.
- Fragments (
#…) are ignored. Entities (did:ixo:entity:…) named in these fields are skipped, and their own managers are not looked up. - Every manager has the full manager rights on this page, including setting their own budget. No DAO vote is needed.
- At most 25 DAOs are checked. If the entity names more and the caller is not found in the first
25, the answer is
503, not403. - A change on chain takes effect within about 3 seconds plus IXO Blocksync's indexing delay. This applies to a manager added and to a manager removed.
- If the lookup fails or takes longer than 8 seconds, the answer is
503. It is never403and never "allowed". Retry later.
Call the API
Base URL
| Network | Base URL |
|---|---|
| Mainnet | https://subscriptions-api-mainnet.ixo-api.workers.dev |
| Testnet | https://subscriptions-api-testnet.ixo-api.workers.dev |
| Devnet | https://subscriptions-api.ixo-api.workers.dev |
Every team route is under /api/v1/teams/{teamEntityDid}/. teamEntityDid must match
did:ixo:entity:[A-Za-z0-9]+. Any other value is 422.
Authentication
Send a User Controlled Authorization Network (UCAN) invocation as a bearer token:
Authorization: Bearer <UCAN invocation>
X-Auth-Type: ucan- The invocation must be rooted in an IXO account DID,
did:ixo:ixo1…. Any other root is403. - Its capability is
{ "with": "ixo:subscriptions", "can": "*" }, and it must declare only that one capability. - Its audience is the service's
did:webfor the host you call, published at/.well-known/did.jsonon that host. - No token, or a token that does not validate, is
401.
The service acts only as the account the invocation is rooted in. A route never takes the caller's address from the request body or path.
Amounts and errors
- Budget amounts are integers in micro-USD (
upay). In responses they are strings. 1 PAY is 1,000,000. - An error body is
{ "message": "…" }. A schema error is422with{ "error", "message", "status": 422 }. An authentication error is{ "error": "…" }. 502and503are returned as they are. Any other5xxbecomes a generic500.
Rate limits
| Limit | Applies to | Over the limit |
|---|---|---|
| 20 requests per 60 seconds per caller account | POST, PUT and DELETE under /api/v1/teams/ | 429 { "message": "Too many team changes; try again in a minute" } |
| 600 requests per 60 seconds per IP address | Every route | 429 { "message": "Rate limit exceeded", "status": 429 } |
The team limit is checked after authentication and before the body is validated. Reads do not count towards it.
Set up a team
Start setup
A manager calls POST /api/v1/teams/{teamEntityDid}/subscription. The answer is 202 with
{ "setupStatus": "in_progress" }. Setup runs in the background. It creates the deed, its two
claim collections and the grants they need, in three transactions signed by the service.
Wait for it to finish
Call GET /api/v1/teams/{teamEntityDid}/subscription every few seconds until status is
active or failed.
Retry a failed setup
If status is failed, call POST …/subscription again. A new run reuses the deed and the
collections already created, and sends only what is missing.
The team is set up when status is active and claimCollections holds both collection ids.
Manage members and budgets
A budget is a spend limit per period, in micro-USD.
- Period: 86,400 seconds (24 hours, the chain's minimum) to 31,622,400 seconds (366 days).
- Limit: 1 to 1,000,000,000,000 micro-USD (1,000,000 PAY) per period.
- A new member starts with nothing spent. Their first period ends one period after the block that added them.
- Changing an existing member replaces the limit and the period. What they spent in the current period, and the end of that period, stay. A lower limit can leave nothing to spend until the period ends.
resetSpent: truestarts a fresh period now, with nothing spent.- Period reset. The chain resets a period only when the next charge arrives. The API applies the
reset when it answers: once the period has ended, spent shows as 0 and
periodResetAtmoves to the end of the current period. The API uses its own clock, so right at the end of a period it can differ by a few seconds from the chain. - Removing a member deletes their budget on chain and removes their permission to authorise oracles against the team. Oracle authorisations the member already created stay on chain, but cannot spend: a charge for a member without a budget fails.
- Removing and adding the same member again. Their old oracle authorisations match again and can spend from the new budget. If they had charges in progress when removed, the amounts returned for those charges are applied to the new budget. Avoid removing a member who has charges in progress.
A team has at most 100 members. One request adds, updates or removes at most 25. Each request is one transaction on chain. Only one member change runs at a time for each team.
How budgets are enforced on chain
Member budgets are a feature of the Claims module of the IXO Protocol (x/claims), on the team's
oracle collection. This is how the chain uses them:
- A new member gets a grant that lets them authorise an oracle against the team's oracle
collection, tagged with their own address. They do this with
MsgCreateClaimAuthorization, withmemberAddressset to their own address. - An oracle charges usage by opening an intent (
MsgClaimIntent) withmemberAddressset to the member. The chain checks the member's budget, resets the period if it has ended, and adds the amount to what the member spent. - The oracle submits the claim against that intent. When the claim is approved, the payment comes from the team's admin account.
- If the claim is rejected or the intent expires, the amount goes back to the member's budget.
The oracle collection requires intents. A claim submitted without one is refused, so no charge can skip the budget check.
Top up a team
A manager pays by card for the team. The credits go to the team's admin account, not to the manager's own subscription.
- Call
POST /api/v1/teams/{teamEntityDid}/payments/intentwith the amount. - Confirm the payment with Stripe in your client, using
clientSecret. If you sent a savedpaymentMethodId, the payment is confirmed when it is created. - When Stripe confirms the payment, the service credits the amount to the team in PAY.
- The amount is a whole number of US dollars, 1 to 10,000.
- The card is charged the amount plus a card service fee. Only the amount is credited.
- The manager pays with their own Stripe customer. Saved cards work as for a personal purchase. Promo codes are not accepted.
- Each Stripe payment is credited once. A repeated delivery of the same Stripe event does not credit it again.
Freeze after a card dispute
A card dispute (charge.dispute.created) or a refund (charge.refunded) on a team payment freezes
the team. The payer's personal subscription is not affected.
| While a team is frozen | |
|---|---|
Refused with 409 | PUT …/members and POST …/payments/intent |
| Still allowed | DELETE …/members, every read, POST …/subscription |
| Not stopped | Spending of existing budgets on chain. A payment intent created before the freeze and paid after it is still credited |
There is no route to unfreeze a team. Contact support@ixo.world.
Routes
| Method | Path | Who |
|---|---|---|
GET | /api/v1/teams/{teamEntityDid}/subscription | A manager or a member |
POST | /api/v1/teams/{teamEntityDid}/subscription | A manager |
GET | /api/v1/teams/{teamEntityDid}/members | A manager |
GET | /api/v1/teams/{teamEntityDid}/members/{address} | A manager, or the member reading their own budget |
PUT | /api/v1/teams/{teamEntityDid}/members | A manager |
DELETE | /api/v1/teams/{teamEntityDid}/members | A manager |
POST | /api/v1/teams/{teamEntityDid}/payments/intent | A manager |
The budget object
Every member route returns budgets in this shape.
{
"address": "ixo1kx8manv7l0znk3qwqy6sg306l76l8ehc42vfet",
"periodSeconds": 2592000,
"limitMicroUsd": "50000000",
"spentMicroUsd": "1200000",
"remainingMicroUsd": "48800000",
"periodResetAt": "2026-12-16T09:30:00.000Z"
}| Field | Type | Meaning |
|---|---|---|
address | string | The member's account address |
periodSeconds | integer | Length of a period, in seconds |
limitMicroUsd | string | Spend limit per period, in micro-USD |
spentMicroUsd | string | Spent in the current period, in micro-USD |
remainingMicroUsd | string | Limit minus spent, never below 0 |
periodResetAt | string or null | When the current period ends (ISO 8601). Can be null right after a PUT, see below |
GET /subscription
Returns the team's subscription as the caller may see it. The caller must be a manager or a member.
| Field | Type | Meaning |
|---|---|---|
teamEntityDid | string | The team entity |
deedDid | string or null | The team's subscription deed. Null until it is created |
setupStatus | string | in_progress, completed or failed |
role | string | manager or member. A manager who is also a member is manager |
claimCollections | object | oracleClaimsCollectionId and subscriptionClaimsCollectionId. Empty until setup is complete |
totalCredits | number | The team's balance, in credits |
status | string | After setup: active or inactive (the deed's status). Before: processing, or failed |
adminAddress | string | The deed's admin account, which holds the team's PAY. Empty until setup is complete |
memberBudget | object | The caller's own budget. Present only when the caller is a member |
| Code | Meaning |
|---|---|
200 | The subscription |
401 | Not authenticated |
403 | Neither a manager nor a member. A caller who is not a manager also gets 403 when the team has no subscription or the entity does not exist |
404 | A manager asked about a team with no subscription. Rarely, the deed is not indexed yet: retry |
422 | teamEntityDid is not valid |
503 | The caller's role could not be checked. Retry |
POST /subscription
Starts setup, or reports on it. No body. The answer is always 202 { "setupStatus": "…" }.
| Situation | What happens | setupStatus |
|---|---|---|
| Never set up, or the last run failed | A new run starts | in_progress |
| A run is in progress | Nothing new starts | in_progress |
| A run stopped without reporting for 15 minutes | A new run takes over | in_progress |
| Setup is complete | Nothing new starts | completed |
The call is idempotent: repeating it never creates a second team subscription.
| Code | Meaning |
|---|---|
202 | { "setupStatus" } after this call |
401 | Not authenticated |
403 | Not a manager. Nothing is written |
404 | The entity does not exist. Nothing is written |
422 | teamEntityDid is not valid |
429 | Team write limit |
500 | Setup could not be started. Call again |
503 | The manager check failed. Nothing is written. Retry |
GET /members
Lists one page of the team's member budgets, read from the chain. Manager only.
| Query parameter | Meaning |
|---|---|
limit | Page size, 1 to 100. Default 100 |
paginationKey | nextPaginationKey from the previous page |
The pagination key is standard base64 and can contain +, / and =. URL-encode it, for example
with encodeURIComponent. An unencoded + arrives as a space and is refused with 422.
Response: { "members": [<budget>, …], "nextPaginationKey": "…" }. nextPaginationKey is null on
the last page.
| Code | Meaning |
|---|---|
200 | One page |
400 | paginationKey is not a key from a previous page |
401 | Not authenticated |
403 | Not a manager |
404 | Entity not found, or the deed is not indexed yet |
409 | No team subscription, or setup is not complete |
422 | limit out of range, or paginationKey is not base64 |
503 | The manager check or a chain read failed. Retry |
GET /members/{address}
Returns one member's budget. A manager can read any member. A member can read their own budget.
When address is the caller's own address, the service does not check whether the caller is a
manager. That read answers 404 for anyone who is not a member, whatever state the team is in, so it
reveals nothing about the team.
| Code | Meaning |
|---|---|
200 | The budget |
401 | Not authenticated |
403 | Reading another account's budget without being a manager |
404 | Not a member, or the entity was not found |
409 | Manager reads only: no team subscription, or setup is not complete |
422 | teamEntityDid or address is not valid |
503 | The manager check or a chain read failed. Retry |
PUT /members
Adds new members and updates existing ones, in one transaction. Manager only. Refused while the team is frozen.
{
"members": [
{
"address": "ixo1kx8manv7l0znk3qwqy6sg306l76l8ehc42vfet",
"periodSeconds": 2592000,
"limitMicroUsd": 50000000,
"resetSpent": false
}
]
}| Field | Type | Rules |
|---|---|---|
members | array | 1 to 25 entries. No address twice |
address | string | A lower-case ixo1… account address with a valid checksum |
periodSeconds | integer | 86,400 to 31,622,400 |
limitMicroUsd | integer | 1 to 1,000,000,000,000 |
resetSpent | boolean | Optional. Default false. true starts a fresh period now |
Response: { "members": [<budget>, …], "transactionHash": "…" }, one budget for each entry, in the
order you sent them. If the service cannot read a budget from the transaction's events, it computes
it from what it wrote. A fresh period then shows spent 0 and periodResetAt null.
Sending the same body again sets the same budgets. Take care with resetSpent: true: it starts
another fresh period each time.
| Code | Meaning |
|---|---|
200 | The budgets and the transaction hash |
400 | A bad address checksum, an address twice, or a value out of range |
401 | Not authenticated |
403 | Not a manager |
404 | Entity not found, or the deed is not indexed yet |
409 | No team subscription, setup not complete, the team is frozen, another member change is in progress, the change would take the team over 100 members, or the team already has more than 100 |
422 | Schema error, including more than 25 entries |
429 | Team write limit |
502 | See Failed member changes |
503 | The manager check or a chain read failed, or the change took too long to prepare and was not sent. Retry |
DELETE /members
Removes members, in one transaction. Manager only. Allowed while the team is frozen.
{ "addresses": ["ixo1kx8manv7l0znk3qwqy6sg306l76l8ehc42vfet"] }addresses holds 1 to 25 addresses, with no address twice. Every address must be a member.
Otherwise the answer is 404 naming the addresses that are not, and nothing is removed.
Response: { "removed": ["ixo1…"], "transactionHash": "…" }.
Repeating a removal that succeeded answers 404, because the address is no longer a member.
| Code | Meaning |
|---|---|
200 | The removed addresses and the transaction hash |
400 | A bad address checksum, or an address twice |
401 | Not authenticated |
403 | Not a manager |
404 | Entity not found, or an address is not a member |
409 | No team subscription, setup not complete, another member change is in progress, or the team has more than 100 members |
422 | Schema error |
429 | Team write limit |
502 | See Failed member changes |
503 | The manager check or a chain read failed, or the change was not sent in time. Retry |
POST /payments/intent
Creates a Stripe payment intent that tops up the team. Manager only. The team must be set up and not frozen.
| Field | Type | Meaning |
|---|---|---|
amount | integer | US dollars to credit, 1 to 10,000 |
paymentMethodId | string | Optional. A saved card. When set, the payment is confirmed when it is created |
setAsDefault | boolean | Optional. Default false. Makes paymentMethodId your default card |
| Response field | Type | Meaning |
|---|---|---|
setupIntentId | string | The Stripe payment intent id |
clientSecret | string | Pass it to Stripe in your client to confirm the payment |
requiresAction | boolean | true when Stripe reports the payment intent as requires_action: the card holder must complete a further step, such as 3-D Secure |
serviceFee | number | The card service fee, in US dollars |
amountCharged | number | What the card is charged: amount plus serviceFee |
Each call creates a new payment intent. Do not repeat a call to retry a payment: confirm the intent you already have.
| Code | Meaning |
|---|---|
200 | The payment intent |
400 | The saved payment method can no longer be used. Remove the card and add it again |
401 | Not authenticated |
402 | The card was declined. The message comes from Stripe and can be shown to the user |
403 | Not a manager |
404 | Entity not found |
409 | Setup is not complete, or the team is frozen |
422 | Schema error, including an amount that is not a whole number from 1 to 10,000 |
429 | Team write limit |
500 | Any other Stripe error |
503 | The manager check failed. Retry |
Failed member changes
A PUT or DELETE on members can fail in three ways.
| Answer | Meaning | What to do |
|---|---|---|
502 "The member change could not be completed on chain; try again shortly" | Nothing changed | Retry |
502 "The member change was sent to the chain but could not be confirmed, so it may still apply. …" | The transaction was sent and may still land | Wait about 2 minutes. Read GET …/members. Repeat the change only if it did not apply |
503 "The member change took too long to prepare and was not sent; try again shortly" | Nothing was sent | Retry |
After a change whose outcome is unknown, the team's member changes stay locked for 2 minutes from
when the change started, so the pending transaction can land first. A change in that time gets
409. The transaction carries no timeout, so landing within 2 minutes is likely but not certain.
Next steps
What a team subscription means for a member and for a manager.
Personal Agent creditsHow the Personal Agent charges each person's own credits.
How claim disputes work on chainClaims, intents and evaluation in the Claims module.
What works todayWhat is available on which network.