Developer funding and allocations

Choose the right funding path

The hosted allocation service distributes operator-approved development funds in its configured environment. A developer or agent authenticates, names a recipient identity and public key, and receives a funded result or a typed pending or refusal outcome. The service controls the allocation amount, treasury, eligibility, and quota policy.

A development allocation is scoped to its environment and policy. It does not establish a general entitlement to free real-value Assets, fiat conversion, or unlimited liquidity. Public account deposit funding uses the custody credit path. Use the allocation endpoint supplied for your approved development environment rather than assuming a public faucet hostname.

Developer journey

1. Obtain access to the configured allocation environment and an active hosted identity session.
2. Create or select a recipient signing identity. Record its public DID and 64-hex Ed25519 public key without exposing the seed.
3. Choose and persist an idempotency key for this allocation request.
4. Submit the claim and retain the funding identifier and transaction identifier.
5. Resolve pending outcomes under the same request key.
6. Verify the transfer receipt and recipient balance before sending a payment.

Authentication and roles

The caller's session token is introspected as request data; it is never reused as an upstream service authorization credential. The direct claim resolves an active session subject. The service claim accepts its separate configured credential and supplies a principal explicitly. Keep service and treasury credentials on trusted servers.

Submit a direct claim

POST /v1/faucet/claims
Authorization: Bearer <hosted-session-token>
Idempotency-Key: developer-allocation-order-01
Content-Type: application/json

{
  "did": "did:layerx:<lowercase-public-key-hex>",
  "public_key": "<64-hex-public-key>"
}

The JSON body accepts only did and public_key. The allocation amount is configured by the service rather than chosen in the claim. Use the key-derived DID that the treasury funding path validates. Idempotency-Key is 1–128 characters from letters, digits, hyphen, underscore, dot, and colon.

Service and JSON-RPC access

A configured service caller uses POST /v1/faucet/service-claims with the same headers and a body containing exactly principal, did, and public_key. Direct and service requests for the same principal share its identity quota. The service route must be configured with its dedicated credential.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "lx_requestFunds",
  "params": ["did:layerx:<lowercase-public-key-hex>", "<64-hex-public-key>"]
}

The configured gateway proxies this method to the service-claim flow. RpcClient::request_funds, the layerx faucet CLI command, and the faucet.request tool use the same allocation capability. Gateway and environment eligibility still apply.

Amounts and configurable ceilings

Amounts are integer base units of the configured treasury Asset. Interpret them using that Asset's decimals and metadata; do not assume an allocation amount is a fiat amount or a whole-token count. Responses encode amounts as decimal strings.

These are service configuration defaults, not a promised allowance for every deployment. The gateway additionally bounds its claim request rate at 30 per minute. The direct service derives network admission from the TCP peer; service claims use a principal-scoped network bucket. Forwarded identity or IP headers are refused rather than trusted as quota authority.

Signed canonical funding

The allocation service reserves quota and an idempotency record atomically, then sends its controller a funding command containing funding_id, did, public_key, and amount. The controller constructs an owner-authorized native Asset SEND from the treasury main account to the recipient main account.

Preparation reads the treasury identity sequence separately from its state-proven source-account sequence and verifies sufficient treasury Asset balance. The signing disclosure binds the canonical envelope, debit authorization, recipient, amount, validity interval, fee limit, and idempotency key. The transfer uses current sequences and an interval from 60 seconds before preparation through 300 seconds after it.

The core submission follows the ordinary signed activity and receipt verification path. Result code zero produces a funded result. A refused transfer produces a refusal, and a receipt timeout remains pending. Allocation does not mint arbitrary supply or bypass normal transfer authorization.

Response verification and recovery

{
  "funded": true,
  "funding_id": "<funding-id>",
  "transaction_id": "<transaction-id>",
  "amount": "1000000",
  "network": "layerx-testnet"
}

This illustrates the default claim amount and the allocation response's environment label. Direct HTTP success is an unwrapped body rather than an ok envelope; its transaction identifier is optional at that layer. The gateway additionally requires a transaction identifier and a complete funded response before returning JSON-RPC success.

Retain the returned identifiers and verify the transaction's canonical receipt, recipient, Asset, amount, result code, network authority, and requested commitment. Confirm the recipient account with lx_getAccount or lx_getBalance. A funding identifier is a correlation reference, not an independent finality proof.

HTTP/1.1 202 Accepted
Retry-After: 10

{
  "state": "still_checking",
  "retry": "after",
  "retry_after_seconds": 10
}

Repeat the original claim with the same idempotency key and unchanged body after the carried delay. The service recovers the same funding identifier. A stored funded response is replayed; a different request digest under the same key returns 409 idempotency_conflict. The gateway maps pending allocation to JSON-RPC -32001 with faucet_claim_pending, never a funded result.

Typed refusals

Owner operations

Configure the allocation amount and caps, supply a funded treasury with fee balance, and provision separate identity, service-claim, and control credentials. Persist quota and idempotency state in the configured TLS Redis service. Keep the funding journal durable across controller restarts and retain its request digest bindings.

The service exposes GET /livez for process liveness and GET /readyz for Redis readiness. A ready response establishes Redis availability; independently monitor identity introspection, controller connectivity, treasury balances, and receipt recovery. Its hash-chained allocation audit records event, result, and funding reference without recording authentication values.

Continue building

• Send your first payment
• Deposit-backed custody funding
• Asset metadata and account balances
• Execution fees and fee limits
• Public payment API