Team subscriptions API

Reference for team subscriptions in the IXO Subscriptions API: who manages a team, setup, member budgets enforced on chain, card top-ups, freezes, every route with its fields, limits and errors.

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 relationship subscriber. 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:

  1. a controller of the team entity;
  2. the entity's owner, as did:ixo:<owner address>;
  3. a linkedEntity of the entity with service matrix and relationship admin;
  4. 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, not 403.
  • 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 never 403 and never "allowed". Retry later.

Call the API

Base URL

NetworkBase URL
Mainnethttps://subscriptions-api-mainnet.ixo-api.workers.dev
Testnethttps://subscriptions-api-testnet.ixo-api.workers.dev
Devnethttps://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 is 403.
  • Its capability is { "with": "ixo:subscriptions", "can": "*" }, and it must declare only that one capability.
  • Its audience is the service's did:web for the host you call, published at /.well-known/did.json on 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 is 422 with { "error", "message", "status": 422 }. An authentication error is { "error": "…" }.
  • 502 and 503 are returned as they are. Any other 5xx becomes a generic 500.

Rate limits

LimitApplies toOver the limit
20 requests per 60 seconds per caller accountPOST, 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 addressEvery route429 { "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: true starts 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 periodResetAt moves 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:

  1. 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, with memberAddress set to their own address.
  2. An oracle charges usage by opening an intent (MsgClaimIntent) with memberAddress set 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.
  3. The oracle submits the claim against that intent. When the claim is approved, the payment comes from the team's admin account.
  4. 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.

  1. Call POST /api/v1/teams/{teamEntityDid}/payments/intent with the amount.
  2. Confirm the payment with Stripe in your client, using clientSecret. If you sent a saved paymentMethodId, the payment is confirmed when it is created.
  3. 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 409PUT …/members and POST …/payments/intent
Still allowedDELETE …/members, every read, POST …/subscription
Not stoppedSpending 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

MethodPathWho
GET/api/v1/teams/{teamEntityDid}/subscriptionA manager or a member
POST/api/v1/teams/{teamEntityDid}/subscriptionA manager
GET/api/v1/teams/{teamEntityDid}/membersA manager
GET/api/v1/teams/{teamEntityDid}/members/{address}A manager, or the member reading their own budget
PUT/api/v1/teams/{teamEntityDid}/membersA manager
DELETE/api/v1/teams/{teamEntityDid}/membersA manager
POST/api/v1/teams/{teamEntityDid}/payments/intentA 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"
}
FieldTypeMeaning
addressstringThe member's account address
periodSecondsintegerLength of a period, in seconds
limitMicroUsdstringSpend limit per period, in micro-USD
spentMicroUsdstringSpent in the current period, in micro-USD
remainingMicroUsdstringLimit minus spent, never below 0
periodResetAtstring or nullWhen 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.

FieldTypeMeaning
teamEntityDidstringThe team entity
deedDidstring or nullThe team's subscription deed. Null until it is created
setupStatusstringin_progress, completed or failed
rolestringmanager or member. A manager who is also a member is manager
claimCollectionsobjectoracleClaimsCollectionId and subscriptionClaimsCollectionId. Empty until setup is complete
totalCreditsnumberThe team's balance, in credits
statusstringAfter setup: active or inactive (the deed's status). Before: processing, or failed
adminAddressstringThe deed's admin account, which holds the team's PAY. Empty until setup is complete
memberBudgetobjectThe caller's own budget. Present only when the caller is a member
CodeMeaning
200The subscription
401Not authenticated
403Neither 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
404A manager asked about a team with no subscription. Rarely, the deed is not indexed yet: retry
422teamEntityDid is not valid
503The caller's role could not be checked. Retry

POST /subscription

Starts setup, or reports on it. No body. The answer is always 202 { "setupStatus": "…" }.

SituationWhat happenssetupStatus
Never set up, or the last run failedA new run startsin_progress
A run is in progressNothing new startsin_progress
A run stopped without reporting for 15 minutesA new run takes overin_progress
Setup is completeNothing new startscompleted

The call is idempotent: repeating it never creates a second team subscription.

CodeMeaning
202{ "setupStatus" } after this call
401Not authenticated
403Not a manager. Nothing is written
404The entity does not exist. Nothing is written
422teamEntityDid is not valid
429Team write limit
500Setup could not be started. Call again
503The 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 parameterMeaning
limitPage size, 1 to 100. Default 100
paginationKeynextPaginationKey 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.

CodeMeaning
200One page
400paginationKey is not a key from a previous page
401Not authenticated
403Not a manager
404Entity not found, or the deed is not indexed yet
409No team subscription, or setup is not complete
422limit out of range, or paginationKey is not base64
503The 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.

CodeMeaning
200The budget
401Not authenticated
403Reading another account's budget without being a manager
404Not a member, or the entity was not found
409Manager reads only: no team subscription, or setup is not complete
422teamEntityDid or address is not valid
503The 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
    }
  ]
}
FieldTypeRules
membersarray1 to 25 entries. No address twice
addressstringA lower-case ixo1… account address with a valid checksum
periodSecondsinteger86,400 to 31,622,400
limitMicroUsdinteger1 to 1,000,000,000,000
resetSpentbooleanOptional. 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.

CodeMeaning
200The budgets and the transaction hash
400A bad address checksum, an address twice, or a value out of range
401Not authenticated
403Not a manager
404Entity not found, or the deed is not indexed yet
409No 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
422Schema error, including more than 25 entries
429Team write limit
502See Failed member changes
503The 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.

CodeMeaning
200The removed addresses and the transaction hash
400A bad address checksum, or an address twice
401Not authenticated
403Not a manager
404Entity not found, or an address is not a member
409No team subscription, setup not complete, another member change is in progress, or the team has more than 100 members
422Schema error
429Team write limit
502See Failed member changes
503The 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.

FieldTypeMeaning
amountintegerUS dollars to credit, 1 to 10,000
paymentMethodIdstringOptional. A saved card. When set, the payment is confirmed when it is created
setAsDefaultbooleanOptional. Default false. Makes paymentMethodId your default card
Response fieldTypeMeaning
setupIntentIdstringThe Stripe payment intent id
clientSecretstringPass it to Stripe in your client to confirm the payment
requiresActionbooleantrue when Stripe reports the payment intent as requires_action: the card holder must complete a further step, such as 3-D Secure
serviceFeenumberThe card service fee, in US dollars
amountChargednumberWhat 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.

CodeMeaning
200The payment intent
400The saved payment method can no longer be used. Remove the card and add it again
401Not authenticated
402The card was declined. The message comes from Stripe and can be shown to the user
403Not a manager
404Entity not found
409Setup is not complete, or the team is frozen
422Schema error, including an amount that is not a whole number from 1 to 10,000
429Team write limit
500Any other Stripe error
503The manager check failed. Retry

Failed member changes

A PUT or DELETE on members can fail in three ways.

AnswerMeaningWhat to do
502 "The member change could not be completed on chain; try again shortly"Nothing changedRetry
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 landWait 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 sentRetry

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