Namespace claim fee API

Public namespace claims pay a fee upfront into the Allocator. This fee applies to a namespace such as yourbrand. Prices for names beneath it, such as alice.yourbrand, use the separate native claim interface. Read the quote before preparing an announcement. After settlement, use the receipt and credit routes to check the outcome. All claim-fee routes use Cache-Control: no-store.

Quote

GET /v1/claim-fee

Reads the Allocator’s current claim_fee_policy and checks its token against the API deployment’s accepted configuration. The current testnet policy uses native XLM. Other deployments can explicitly configure a different accepted token; an unexpected token fails the read.

Field	Meaning
`allocatorId`	Allocator contract
`token`	Fee token contract from the verified policy
`amount`	Integer token base units, as a decimal string
`recipient`	Configured fee recipient
`decimals`, `asset`	The current API returns `7`; the label is `"XLM"` for native XLM or the deployment’s configured asset label (default `"TOKEN"`)
`network`	Stellar network passphrase
`rounding`	`"floor"`

One XLM is 10,000,000 base units. The response’s refundBps object gives each outcome’s refund rate:

Outcome	Basis points refunded
`Awarded`	0
`Rejected`, `Stuck`	10,000
`Withdrawn`, `Expired`	8,000

See claim outcomes for what each outcome means. Verify the policy independently on chain before signing a payment authorization.

Prepare a paid announcement

This route requires an authenticated wallet session:

POST /console/register/announce/prepare
Content-Type: application/json

{
  "label": "yourbrand",
  "basis": ["Your public claim evidence"],
  "expectedFee": {
    "allocatorId": "ALLOCATOR_FROM_QUOTE",
    "token": "TOKEN_FROM_QUOTE",
    "amount": "AMOUNT_FROM_QUOTE",
    "recipient": "RECIPIENT_FROM_QUOTE",
    "network": "NETWORK_FROM_QUOTE"
  }
}

Replace every uppercase placeholder with the corresponding quote value. basis is an array of up to 16 nonempty strings, each at most 120 characters. Omitting it uses an empty array. The response contains ok, unsigned xdr, claimant, fee and network. The claimant is the authenticated wallet. Preparing the transaction does not submit the announcement or collect the fee. Before signing, independently verify the network, Allocator, claimant, label, evidence, exact quoted-token transfer and accepted network-fee ceiling. The API checks that expectedFee matches the current quote, but that check does not replace your wallet’s transaction review.

Error	Meaning
`400 invalid_request`	Invalid label, basis or body
`400 wallet_required`	The session has no wallet account
`400 claim_fee_quote_required`	`expectedFee` is missing
`409 claim_fee_changed`	At least one quoted field no longer matches
`409 reserved_label`	An active bound reservation prevents this announcement

Receipt

GET /v1/claim-fee/{label}

Returns label, current policy and a nullable receipt. A receipt contains:

Field	Meaning
`claimant`	Claiming address
`amount`	Original fee, in decimal-string base units
`outcome`	`Held`, `Awarded`, `Rejected`, `Withdrawn`, `Expired` or `Stuck`
`refundAmount`	Claimant’s settlement entitlement
`treasuryAmount`	Fee recipient’s settlement entitlement

All amounts are decimal strings. Entitlements do not prove that every transfer was delivered; check available credit when a payout is undelivered. A new claim for the same label can replace the current receipt. Use archived fee events for earlier claims. Invalid labels return 400 bad_label.

Recover an undelivered payout

Read available credit

GET /v1/claim-fee/credit/{address}

Returns address, available amount in decimal-string base units and current policy. Use the G or C payee address recorded by the contract.

Prepare recovery

POST /v1/claim-fee/credit/{address}/prepare
Content-Type: application/json

{ "source": "YOUR_FUNDED_G_ACCOUNT" }

Replace the placeholder with a funded G transaction-source account. A successful response adds source, unsigned xdr and network to the credit result. The transaction calls claim_fee_credit(address) and always pays the recorded payee, even when the transaction source differs. Review and sign the transaction with a network-fee ceiling. Invalid sources return 400 wallet_required; zero available credit returns 409 no_credit. The contract also exposes fee_credit, claim_fee_credit and touch_fee_credit directly. Objection bond credit uses separate accounting. Reserved direct Registry claims are exempt from this fee and do not create paid Allocator receipts.

Unavailable fee reads

An unconfigured fee policy returns 409 claim_fee_not_configured. Failed reads, invalid responses and token mismatches return 503 with an error code. A failed read does not establish a zero fee or zero credit.

​Quote

​Prepare a paid announcement

​Receipt

​Recover an undelivered payout

​Read available credit

​Prepare recovery

​Unavailable fee reads