get-fountain-info.rst (1981B)
1 .. http:get:: [/instances/$INSTANCE]/fountain/info 2 3 Used by wallets to learn which token families they can withdraw 4 from and to obtain the token family metadata and issue public 5 keys needed to prepare blinded envelopes. Wallets re-poll this 6 endpoint at the advertised ``poll_freq`` to learn about changed 7 promotional grants. 8 This endpoint is available since protocol **vTokenFountains**. 9 10 The fountain secret authenticates the request via the 11 ``Authorization: Bearer $FOUNTAIN_SECRET`` header; it is 12 deliberately never placed in the URL to keep it out of server 13 logs and proxies. 14 15 **Response:** 16 17 :http:statuscode:`200 OK`: 18 The backend has successfully returned the fountain information. 19 Returns a `FountainInfoResponse`. 20 :http:statuscode:`401 Unauthorized`: 21 The fountain secret is unknown. This includes deleted 22 fountains: the wallet should report the access as revoked. 23 :http:statuscode:`500 Internal Server Error`: 24 The server experienced an internal failure. 25 26 **Details:** 27 28 .. ts:def:: FountainInfoResponse 29 30 interface FountainInfoResponse { 31 32 // How often the wallet should re-poll this endpoint. 33 poll_freq: RelativeTime; 34 35 // Grants of this fountain, with the token family metadata 36 // and issue keys needed to prepare blinded envelopes. 37 grants: FountainWalletGrant[]; 38 } 39 40 .. ts:def:: FountainWalletGrant 41 42 interface FountainWalletGrant { 43 44 // Slug of the token family. 45 token_family_slug: string; 46 47 // Maximum withdrawals per key validity period. 48 tokens_per_period_limit: Integer; 49 50 // Suggested number of tokens to hold per period. 51 tokens_per_period_stash: Integer; 52 53 // Number of key slots ahead the wallet may withdraw for. 54 key_window_size: Integer; 55 56 // Token family metadata including the currently valid 57 // (and, within ``key_window_size``, upcoming) issue 58 // public keys. 59 token_family: ContractTokenFamily; 60 }