{"openapi":"3.1.0","info":{"title":"Reward API","description":"Management of the Rewards Platform founded upon the CFX Network.\n\nRewards are managed within the CFX Platform as a ledger mechanism aligning with double entry account priciples. The issuance of a Reward to a recipient Identity results two matching entries:\n\n- A `CREDIT` entry of the `amount` against a recipient Identity account (the person receiving the Reward)\n- A `DEBIT` entry of the `amount` against a reward issuer (the entity issuing the Reward)\n\nThe collateral that underpins CFX Rewards is held as MOVEUSD, which is the USD-backed stablecoin supporting the CFX Network. This collateral underwrites Reward issuance and is held within a customer's Reward Inventory Wallet. MOVEUSD collateral is transferred from the Reward Inventory Wallet into the Identity's self-custodied wallet during the Reward claim process. The management of each customer's Reward liability (the total of Rewards issued by the customer to recipients) and the customer Reward Inventory Wallet is established as part of the CFX customer onboarding process.\n\nCFX Rewards are integrated into the MOVEUSD stablecoin, as well as broader capabilities offered by the CFX Network. CFX also offers a fully managed, hosted, customizable Rewards Wallet that exposes these capabilities through a integrated web application:\n\n- A fully hosted, minimal integration, branded Rewards Wallet\n- Exposed as a web application, avoiding native app installations and with user login purely through a verified phone number\n- Enabling CFX customers to push Rewards to their users in real-time. Rewards are displayed users the moment they are issued.\n- Allowing users to hold reward assets in a self-custodied wallet\n\nThe wallet incorporates many of the capabilities of the CFX Network, including the ability to:\n\n- Receive rewards as a customer-branded reward (eg ACMI Dollars)\n- Watch their rewards balance grow in real time\n- Convert their rewards balance in a USD-backed stablecoin\n- Send funds to friends and family simply by nominating their phone number\n- Withdraw to a US bank account\n- Deposit additional funds into the wallet\n- Convert funds into selected cryptocurrencies\n- Request funds from family and friends\n- Send stablecoins and crytocurrencies via the Solana blockchain\n\nThis Reward API documentation illustrates key endpoints supporting the creation and management of Rewards and the associated balances. Please speak with your CFX account representative for more information.","termsOfService":"","contact":{"name":"API Owner","email":"api@cfxlabs.com"},"license":{"name":"","url":""},"version":"@VERSION@","summary":"CFX Reward API"},"components":{"securitySchemes":{"ApiKeyAuth":{"name":"x-api-key","type":"apiKey","in":"header"},"ApiSecretAuth":{"name":"x-api-secret","type":"apiKey","in":"header"}},"schemas":{}},"paths":{"/v1/reward":{"post":{"summary":"Create Reward","tags":["Reward"],"description":"Create a reward for a specific CFX Identity.\n\nRewards are issued to a recipient through their phone number. Consequently Rewards can be issued to a recipient Identity prior to them registering within the CFX Network, which allows the creation of a Reward prior to recipient registration.\n\nRewards are managed within the CFX Platform as a ledger mechanism aligning with double entry account priciples. The issuance of a Reward to a recipient Identity results two matching entries:\n\n- A `CREDIT` entry of the `amount` against the recipient Identity account\n- A `DEBIT` entry of the `amount` against the reward issuer\n\nThe ledger allows the system to flexibily manage the growing Reward assets and liabilities for recipients and our CFX partners.\n\nWhen creating a reward the body must contain:\n\n- The `phone` of the recipient.\n- An `idempotencyKey` for the request, which is used to filter out duplicate reward issuances. Each invocation of the Create Reward endpoint should nominate a unique idempotency key.\n- A `category` for the reward, which is a free text field used to support client reporting and reconciliation.\n- A `transactionType` which indicates whether this is a `CREDIT` (add to reward balance) or `DEBIT` (reduce reward balance). Typically these will be `CREDIT` transactions.\n- A free text `note` to be associated with the Reward instance.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone","idempotencyKey","amount","transactionType"],"properties":{"phone":{"type":"string","description":"Phone number associated with the reward recipient","example":"+12915558686"},"idempotencyKey":{"type":"string","description":"A unique key provided by the consumer to ensure idempotency when creating rewards","example":"reward-38592738"},"category":{"type":"string","description":"Type of reward issued. This is a free text field used primarily for reporting and operations.","example":"signup"},"amount":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number","description":"Amount of the nominated reward currency"},"currency":{"type":"string","enum":["MOVEUSD"]}}},"transactionType":{"type":"string","enum":["DEBIT","CREDIT"]},"note":{"type":"string","description":"A free text note associated with the reward.","example":"Rewards Job # 202407013"}}}}}},"parameters":[{"schema":{"type":"string"},"in":"header","name":"Idempotency-Key","required":false}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["id","phone","idempotencyKey","amount","transactionType","createdAt"],"properties":{"id":{"type":"string","description":"Unique identifier for a reward","example":"rew_k9Ii3Mtd8UdgxCgTkW22k"},"phone":{"type":"string","description":"Phone number associated with the reward recipient","example":"+12915558686"},"idempotencyKey":{"type":"string","description":"A unique key provided by the consumer to ensure idempotency when creating rewards","example":"reward-38592738"},"category":{"type":"string","description":"Type of reward issued. This is a free text field used primarily for reporting and operations.","example":"signup"},"amount":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number","description":"Amount of the nominated reward currency"},"currency":{"type":"string","enum":["MOVEUSD"]}}},"transactionType":{"type":"string","enum":["DEBIT","CREDIT"]},"note":{"type":"string","description":"A free text note associated with the reward.","example":"Rewards Job # 202407013"},"createdAt":{"type":"string","format":"date-time","description":"Datetime the reward was created"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_REQUEST"]},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":true}}},"title":"INVALID_REQUEST","description":"The service cannot understand the request"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["MISSING_IDEMPOTENCY_KEY"]},"message":{"type":"string"}},"title":"MISSING_IDEMPOTENCY_KEY","description":"Missing required idempotency key header"},{"anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_PHONE"]},"message":{"type":"string"}},"title":"INVALID_PHONE","description":"A service error has occurred"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_ENTITY_TYPE"]},"message":{"type":"string"}},"title":"INVALID_ENTITY_TYPE","description":"A service error has occurred"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["ENTITY_NOT_FOUND"]},"message":{"type":"string"}},"title":"ENTITY_NOT_FOUND","description":"A service error has occurred"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["IDEMPOTENCY_ERROR"]},"message":{"type":"string"}},"title":"IDEMPOTENCY_ERROR","description":"A service error has occurred"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_AMOUNT"]},"message":{"type":"string"}},"title":"INVALID_AMOUNT","description":"A service error has occurred"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INSUFFICIENT_BALANCE"]},"message":{"type":"string"}},"title":"INSUFFICIENT_BALANCE","description":"A service error has occurred"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_REQUEST"]},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":true}}},"title":"INVALID_REQUEST","description":"The service cannot understand the request"}]}]}}}},"401":{"description":"The access to this resource has been denied","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["UNAUTHORIZED"]},"message":{"type":"string"}},"title":"UNAUTHORIZED","description":"The access to this resource has been denied"}}}},"409":{"description":"A duplicate request with this idempotency key is already in progress","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["IDEMPOTENCY_IN_PROGRESS"]},"message":{"type":"string"}},"title":"IDEMPOTENCY_IN_PROGRESS","description":"A duplicate request with this idempotency key is already in progress"}}}},"422":{"description":"Another request with this idempotency key was made using a different body","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["IDEMPOTENCY_KEY_REUSED"]},"message":{"type":"string"}},"title":"IDEMPOTENCY_KEY_REUSED","description":"Another request with this idempotency key was made using a different body"}}}},"default":{"description":"Catch-all error response for any unexpected internal errors","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INTERNAL"]},"message":{"type":"string","enum":["An unexpected internal error has occurred"]}},"title":"INTERNAL","description":"Catch-all error response for any unexpected internal errors"}}}}}},"get":{"summary":"Search Rewards","tags":["Reward"],"description":"Search for issued rewards.\n\nThis search capability supports the ability to nominate search criteria such as:\n\n- Date ranges\n- Pagination\n- Limits\n- Sorting","parameters":[{"schema":{"type":"string"},"example":"+12915558686","in":"query","name":"phone","required":false,"description":"Phone number associated with the reward recipient"},{"schema":{"type":"string","enum":["DEBIT","CREDIT"]},"in":"query","name":"transactionType","required":false},{"schema":{"type":"string"},"example":"signup","in":"query","name":"category","required":false,"description":"Type of reward issued. This is a free text field used primarily for reporting and operations."},{"schema":{"type":"number"},"in":"query","name":"limit","required":false,"description":"Page size."},{"schema":{"type":"number","minimum":1},"in":"query","name":"page","required":false,"description":"Page number. Index starts at 1."},{"schema":{"type":"boolean"},"in":"query","name":"ascending","required":false,"description":"To order rewards by oldest creation date."},{"schema":{"type":"string"},"example":"2023-10-23T06:20:04.366+00:00","in":"query","name":"after","required":false,"description":"Filter the results to have a creation date after than this datetime"},{"schema":{"type":"string"},"example":"2023-10-23T06:20:04.366+00:00","in":"query","name":"before","required":false,"description":"Filter the results to have a creation date before than this datetime"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data","pagination","hasNext"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","phone","idempotencyKey","amount","transactionType","createdAt"],"properties":{"id":{"type":"string","description":"Unique identifier for a reward","example":"rew_k9Ii3Mtd8UdgxCgTkW22k"},"phone":{"type":"string","description":"Phone number associated with the reward recipient","example":"+12915558686"},"idempotencyKey":{"type":"string","description":"A unique key provided by the consumer to ensure idempotency when creating rewards","example":"reward-38592738"},"category":{"type":"string","description":"Type of reward issued. This is a free text field used primarily for reporting and operations.","example":"signup"},"amount":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number","description":"Amount of the nominated reward currency"},"currency":{"type":"string","enum":["MOVEUSD"]}}},"transactionType":{"type":"string","enum":["DEBIT","CREDIT"]},"note":{"type":"string","description":"A free text note associated with the reward.","example":"Rewards Job # 202407013"},"createdAt":{"type":"string","format":"date-time","description":"Datetime the reward was created"}}}},"pagination":{"type":"object","required":["limit","page"],"properties":{"limit":{"type":"number"},"page":{"type":"number"}}},"hasNext":{"type":"boolean"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_PHONE"]},"message":{"type":"string"}},"title":"INVALID_PHONE","description":"A service error has occurred"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_ENTITY_TYPE"]},"message":{"type":"string"}},"title":"INVALID_ENTITY_TYPE","description":"A service error has occurred"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["ENTITY_NOT_FOUND"]},"message":{"type":"string"}},"title":"ENTITY_NOT_FOUND","description":"A service error has occurred"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_REQUEST"]},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":true}}},"title":"INVALID_REQUEST","description":"The service cannot understand the request"}]}}}},"401":{"description":"The access to this resource has been denied","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["UNAUTHORIZED"]},"message":{"type":"string"}},"title":"UNAUTHORIZED","description":"The access to this resource has been denied"}}}},"default":{"description":"Catch-all error response for any unexpected internal errors","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INTERNAL"]},"message":{"type":"string","enum":["An unexpected internal error has occurred"]}},"title":"INTERNAL","description":"Catch-all error response for any unexpected internal errors"}}}}}}},"/v1/reward/{id}":{"get":{"summary":"Get Reward","tags":["Reward"],"description":"Retrieve a specific reward by nominating the Reward ID.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["id","phone","idempotencyKey","amount","transactionType","createdAt"],"properties":{"id":{"type":"string","description":"Unique identifier for a reward","example":"rew_k9Ii3Mtd8UdgxCgTkW22k"},"phone":{"type":"string","description":"Phone number associated with the reward recipient","example":"+12915558686"},"idempotencyKey":{"type":"string","description":"A unique key provided by the consumer to ensure idempotency when creating rewards","example":"reward-38592738"},"category":{"type":"string","description":"Type of reward issued. This is a free text field used primarily for reporting and operations.","example":"signup"},"amount":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number","description":"Amount of the nominated reward currency"},"currency":{"type":"string","enum":["MOVEUSD"]}}},"transactionType":{"type":"string","enum":["DEBIT","CREDIT"]},"note":{"type":"string","description":"A free text note associated with the reward.","example":"Rewards Job # 202407013"},"createdAt":{"type":"string","format":"date-time","description":"Datetime the reward was created"}}}}}},"401":{"description":"The access to this resource has been denied","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["UNAUTHORIZED"]},"message":{"type":"string"}},"title":"UNAUTHORIZED","description":"The access to this resource has been denied"}}}},"404":{"description":"The resource was not found","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["NOT_FOUND"]},"message":{"type":"string"}},"title":"NOT_FOUND","description":"The resource was not found"}}}},"default":{"description":"Catch-all error response for any unexpected internal errors","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INTERNAL"]},"message":{"type":"string","enum":["An unexpected internal error has occurred"]}},"title":"INTERNAL","description":"Catch-all error response for any unexpected internal errors"}}}}}}},"/v1/reward/balance":{"get":{"summary":"Get Customer Reward Balance","tags":["Reward"],"description":"Retrieve the reward balance associated with a CFX customer. The balance illustrates the total financial exposure of the currently issued rewards.\n\nThe customer is not explicitly provided as input, but is instead mapped from the API credentials provided.","parameters":[{"schema":{"type":"boolean"},"in":"query","name":"count","required":false,"description":"Flag indicating whether the balance debit and credit counts should also be returned"},{"schema":{"type":"boolean"},"in":"query","name":"inventory","required":false,"description":"Flag indicating whether the reward wallet inventory balance should also be returned"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"allOf":[{"allOf":[{"type":"object","required":["amount"],"properties":{"amount":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number","description":"Amount of the nominated reward currency"},"currency":{"type":"string","enum":["MOVEUSD"]}}}}},{"type":"object","properties":{"creditCount":{"type":"number"},"debitCount":{"type":"number"}}}]},{"type":"object","properties":{"rewardInventoryWallet":{"allOf":[{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number","description":"Amount of the nominated reward currency"},"currency":{"type":"string","enum":["MOVEUSD"]}}},{"type":"object","required":["wallet"],"properties":{"wallet":{"type":"object","required":["address","blockchain"],"properties":{"address":{"type":"string","description":"Blockchain address or account"},"blockchain":{"type":"string","description":"The blockchain network"}}}}}]}}}]}}}},"401":{"description":"The access to this resource has been denied","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["UNAUTHORIZED"]},"message":{"type":"string"}},"title":"UNAUTHORIZED","description":"The access to this resource has been denied"}}}},"default":{"description":"Catch-all error response for any unexpected internal errors","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INTERNAL"]},"message":{"type":"string","enum":["An unexpected internal error has occurred"]}},"title":"INTERNAL","description":"Catch-all error response for any unexpected internal errors"}}}}}}},"/v1/reward/balance/{phone}":{"get":{"summary":"Get Identity Reward Balance","tags":["Reward"],"description":"Retrieve the reward balance for a specific recipient Identity by nominating their phone number.","parameters":[{"schema":{"type":"boolean"},"in":"query","name":"count","required":false,"description":"Flag indicating whether the balance debit and credit counts should also be returned"},{"schema":{"type":"string"},"in":"path","name":"phone","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["amount"],"properties":{"amount":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number","description":"Amount of the nominated reward currency"},"currency":{"type":"string","enum":["MOVEUSD"]}}}}},{"type":"object","properties":{"creditCount":{"type":"number"},"debitCount":{"type":"number"}}}]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_PHONE"]},"message":{"type":"string"}},"title":"INVALID_PHONE","description":"A service error has occurred"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_ENTITY_TYPE"]},"message":{"type":"string"}},"title":"INVALID_ENTITY_TYPE","description":"A service error has occurred"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["ENTITY_NOT_FOUND"]},"message":{"type":"string"}},"title":"ENTITY_NOT_FOUND","description":"A service error has occurred"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_REQUEST"]},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":true}}},"title":"INVALID_REQUEST","description":"The service cannot understand the request"}]}}}},"401":{"description":"The access to this resource has been denied","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["UNAUTHORIZED"]},"message":{"type":"string"}},"title":"UNAUTHORIZED","description":"The access to this resource has been denied"}}}},"default":{"description":"Catch-all error response for any unexpected internal errors","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INTERNAL"]},"message":{"type":"string","enum":["An unexpected internal error has occurred"]}},"title":"INTERNAL","description":"Catch-all error response for any unexpected internal errors"}}}}}}},"/v1/reward/claim":{"post":{"summary":"Claim Reward","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"allOf":[{"type":"object","required":["identityId"],"properties":{"identityId":{"type":"string","description":"Identity ID associated with the deposit request","examples":["id_VfsdSMtd8UdgxCgTnz0tm"]}},"title":"Individual"},{"allOf":[{"type":"object","required":["amount"],"properties":{"category":{"type":"string","description":"Type of reward issued. This is a free text field used primarily for reporting and operations.","examples":["signup"]},"amount":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number","description":"Amount of the nominated reward currency"},"currency":{"type":"string","enum":["MOVEUSD"]}}},"note":{"type":"string","description":"A free text note associated with the reward.","examples":["Rewards Job # 202407013"]}}},{"type":"object","required":["walletAddress"],"properties":{"walletAddress":{"type":"string","description":"Target wallet address to send MOVEUSD to. Must be a valid base-58 encoded solana address"}}}]}]},{"allOf":[{"type":"object","required":["organizationId"],"properties":{"organizationId":{"type":"string","description":"Organization ID associated with the deposit request","examples":["org_RD2of9vs3XFodUSd8T5hW"]}},"title":"Organization"},{"allOf":[{"type":"object","required":["amount"],"properties":{"category":{"type":"string","description":"Type of reward issued. This is a free text field used primarily for reporting and operations.","examples":["signup"]},"amount":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number","description":"Amount of the nominated reward currency"},"currency":{"type":"string","enum":["MOVEUSD"]}}},"note":{"type":"string","description":"A free text note associated with the reward.","examples":["Rewards Job # 202407013"]}}},{"type":"object","required":["walletAddress"],"properties":{"walletAddress":{"type":"string","description":"Target wallet address to send MOVEUSD to. Must be a valid base-58 encoded solana address"}}}]}]}]}}}},"parameters":[{"schema":{"type":"string"},"in":"header","name":"Idempotency-Key","required":false}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["id","status","reward","createdAt","updatedAt"],"properties":{"id":{"type":"string","description":"Unique identifier for a reward claim","example":"rewclaim_mTTTzXaDlLAxgvfcod5Cd"},"status":{"type":"string","enum":["PENDING","CLAIMED","RETURNED"]},"reward":{"type":"object","required":["id","phone","idempotencyKey","amount","transactionType","createdAt"],"properties":{"id":{"type":"string","description":"Unique identifier for a reward","example":"rew_k9Ii3Mtd8UdgxCgTkW22k"},"phone":{"type":"string","description":"Phone number associated with the reward recipient","example":"+12915558686"},"idempotencyKey":{"type":"string","description":"A unique key provided by the consumer to ensure idempotency when creating rewards","example":"reward-38592738"},"category":{"type":"string","description":"Type of reward issued. This is a free text field used primarily for reporting and operations.","example":"signup"},"amount":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number","description":"Amount of the nominated reward currency"},"currency":{"type":"string","enum":["MOVEUSD"]}}},"transactionType":{"type":"string","enum":["DEBIT","CREDIT"]},"note":{"type":"string","description":"A free text note associated with the reward.","example":"Rewards Job # 202407013"},"createdAt":{"type":"string","format":"date-time","description":"Datetime the reward was created"}}},"receipt":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"Unique receipt identifier"},"type":{"type":"string","title":"SOLANA_TRANSACTION_SIGNATURE","enum":["SOLANA_TRANSACTION_SIGNATURE"]}},"description":"Receipt associated with the claim"},"returnedRewardId":{"type":"string","description":"Unique identifier for a returned reward if claim was unsuccessful","example":"rew_xUkxHHcINd4Qt31WrrCmK"},"createdAt":{"type":"string","format":"date-time","description":"Datetime the claim was created"},"updatedAt":{"type":"string","format":"date-time","description":"Datetime the claim was updated"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_REQUEST"]},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":true}}},"title":"INVALID_REQUEST","description":"The service cannot understand the request"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["MISSING_IDEMPOTENCY_KEY"]},"message":{"type":"string"}},"title":"MISSING_IDEMPOTENCY_KEY","description":"Missing required idempotency key header"},{"anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_PHONE"]},"message":{"type":"string"}},"title":"INVALID_PHONE","description":"A service error has occurred"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_ENTITY_TYPE"]},"message":{"type":"string"}},"title":"INVALID_ENTITY_TYPE","description":"A service error has occurred"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["ENTITY_NOT_FOUND"]},"message":{"type":"string"}},"title":"ENTITY_NOT_FOUND","description":"A service error has occurred"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["IDEMPOTENCY_ERROR"]},"message":{"type":"string"}},"title":"IDEMPOTENCY_ERROR","description":"A service error has occurred"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_AMOUNT"]},"message":{"type":"string"}},"title":"INVALID_AMOUNT","description":"A service error has occurred"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INSUFFICIENT_BALANCE"]},"message":{"type":"string"}},"title":"INSUFFICIENT_BALANCE","description":"A service error has occurred"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_REQUEST"]},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":true}}},"title":"INVALID_REQUEST","description":"The service cannot understand the request"}]}]}}}},"401":{"description":"The access to this resource has been denied","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["UNAUTHORIZED"]},"message":{"type":"string"}},"title":"UNAUTHORIZED","description":"The access to this resource has been denied"}}}},"409":{"description":"A duplicate request with this idempotency key is already in progress","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["IDEMPOTENCY_IN_PROGRESS"]},"message":{"type":"string"}},"title":"IDEMPOTENCY_IN_PROGRESS","description":"A duplicate request with this idempotency key is already in progress"}}}},"422":{"description":"Another request with this idempotency key was made using a different body","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["IDEMPOTENCY_KEY_REUSED"]},"message":{"type":"string"}},"title":"IDEMPOTENCY_KEY_REUSED","description":"Another request with this idempotency key was made using a different body"}}}},"default":{"description":"Catch-all error response for any unexpected internal errors","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INTERNAL"]},"message":{"type":"string","enum":["An unexpected internal error has occurred"]}},"title":"INTERNAL","description":"Catch-all error response for any unexpected internal errors"}}}}}}},"/v1/reward/claim/{id}":{"get":{"summary":"Get Reward Claim","description":"Retrieve a specific reward claim by nominating the Reward Claim ID.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["id","status","reward","createdAt","updatedAt"],"properties":{"id":{"type":"string","description":"Unique identifier for a reward claim","example":"rewclaim_mTTTzXaDlLAxgvfcod5Cd"},"status":{"type":"string","enum":["PENDING","CLAIMED","RETURNED"]},"reward":{"type":"object","required":["id","phone","idempotencyKey","amount","transactionType","createdAt"],"properties":{"id":{"type":"string","description":"Unique identifier for a reward","example":"rew_k9Ii3Mtd8UdgxCgTkW22k"},"phone":{"type":"string","description":"Phone number associated with the reward recipient","example":"+12915558686"},"idempotencyKey":{"type":"string","description":"A unique key provided by the consumer to ensure idempotency when creating rewards","example":"reward-38592738"},"category":{"type":"string","description":"Type of reward issued. This is a free text field used primarily for reporting and operations.","example":"signup"},"amount":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number","description":"Amount of the nominated reward currency"},"currency":{"type":"string","enum":["MOVEUSD"]}}},"transactionType":{"type":"string","enum":["DEBIT","CREDIT"]},"note":{"type":"string","description":"A free text note associated with the reward.","example":"Rewards Job # 202407013"},"createdAt":{"type":"string","format":"date-time","description":"Datetime the reward was created"}}},"receipt":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"Unique receipt identifier"},"type":{"type":"string","title":"SOLANA_TRANSACTION_SIGNATURE","enum":["SOLANA_TRANSACTION_SIGNATURE"]}},"description":"Receipt associated with the claim"},"returnedRewardId":{"type":"string","description":"Unique identifier for a returned reward if claim was unsuccessful","example":"rew_xUkxHHcINd4Qt31WrrCmK"},"createdAt":{"type":"string","format":"date-time","description":"Datetime the claim was created"},"updatedAt":{"type":"string","format":"date-time","description":"Datetime the claim was updated"}}}}}},"401":{"description":"The access to this resource has been denied","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["UNAUTHORIZED"]},"message":{"type":"string"}},"title":"UNAUTHORIZED","description":"The access to this resource has been denied"}}}},"404":{"description":"The resource was not found","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["NOT_FOUND"]},"message":{"type":"string"}},"title":"NOT_FOUND","description":"The resource was not found"}}}},"default":{"description":"Catch-all error response for any unexpected internal errors","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INTERNAL"]},"message":{"type":"string","enum":["An unexpected internal error has occurred"]}},"title":"INTERNAL","description":"Catch-all error response for any unexpected internal errors"}}}}}}},"/v1/reward/event-config":{"post":{"summary":"Create Reward Event Configuration","tags":["Events"],"description":"The CFX Rewards Engine supports the automation of reward issuance based off certain CFX Network events. These can be configured to ensure Identities are issued rewards as they perform specific network activities. For example:\n\n* Issue a $50 signup reward bonus\n* Issue a $5 reward for completing KYC\n* Issue a $1 reward for completing a deposit\n\n### Events\n\nThe following events are currently supported:\n\n* `deposit.cryptoRequest.statusUpdated`: The status of a crypto deposit quote has changed\n* `deposit.deposit.statusUpdated`: The status of a deposit has changed\n* `identity.identity.statusUpdated`: The status of an identity has changed\n* `identity.verification.statusUpdated`: The status of an identity verification process has changed\n* `organization.organization.statusUpdated`: The status of an organization has changed\n* `reward.reward.claimed`: THe status of a reward claim has changed\n* `reward.reward.created`: A reward has been created\n* `swap.swap.statusUpdated`: The status of a swap between currencies has changed\n* `withdrawal.withdrawal.statusUpdated`: The status of a withdrawal has changed\n* `send.send.statusUpdated`: The status of a fund transfer has changed\n* `user.register.statusUpdated`: The status of a CFX wallet has changed\n\nPlease see our WebHook Guide for details on the data structures for each event.\n\n### Event Rules\n\nOne or more rules can be configured for each event. When the event fires, the first matching rule, in order, will be triggered.\n\nRules are configured by specifying:\n\n* The `status` of the rule (ACTIVE or DISABLED)\n* The `event` the rule is triggered by\n* An array of reward `rules` to apply when the event occurs, which each specify a reward `amount`, `currency` and a `matcher` to filter the event more specifically.\n\nThe `matcher` configuration lets you refine the filtering for each event. Matcher qeuries are defined similar to [MongoDB query language](https://www.mongodb.com/docs/manual/tutorial/query-documents/). For example:\n\n* `\"matcher\":{\"countryOfResidence\":\"US\"}`\n* `\"matcher\":{\"amount\":{\"$gte\":10}}`\n\nPlease reach out to support for more information on how to use this feature.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status","event","rules"],"properties":{"status":{"type":"string","enum":["ACTIVE","DISABLED"]},"event":{"type":"string","description":"The incoming event name to expect for this configuration"},"rules":{"type":"array","items":{"type":"object","required":["status","reward"],"properties":{"status":{"type":"string","enum":["ACTIVE","DISABLED"]},"reward":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number"},"currency":{"type":"string","enum":["MOVEUSD"]}},"description":"How much reward is awarded to identity or organization when this rule is matched"},"matcher":{"type":"object","properties":{},"additionalProperties":true,"description":"Criteria to match this rule more specifically to events"}},"description":"Rules for awarding events. The first matching rule wins."}}}}}}},"parameters":[{"schema":{"type":"string"},"in":"header","name":"Idempotency-Key","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["status","event","rules","createdAt","updatedAt"],"properties":{"status":{"type":"string","enum":["ACTIVE","DISABLED"]},"event":{"type":"string","description":"The incoming event name to expect for this configuration"},"rules":{"type":"array","items":{"type":"object","required":["status","reward"],"properties":{"status":{"type":"string","enum":["ACTIVE","DISABLED"]},"reward":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number"},"currency":{"type":"string","enum":["MOVEUSD"]}},"description":"How much reward is awarded to identity or organization when this rule is matched"},"matcher":{"type":"object","properties":{},"additionalProperties":true,"description":"Criteria to match this rule more specifically to events"}},"description":"Rules for awarding events. The first matching rule wins."}},"createdAt":{"type":"string","format":"date-time","description":"When this record was created"},"updatedAt":{"type":"string","format":"date-time","description":"When this record was last updated"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_REQUEST"]},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":true}}},"title":"INVALID_REQUEST","description":"The service cannot understand the request"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["MISSING_IDEMPOTENCY_KEY"]},"message":{"type":"string"}},"title":"MISSING_IDEMPOTENCY_KEY","description":"Missing required idempotency key header"}]}}}},"401":{"description":"The access to this resource has been denied","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["UNAUTHORIZED"]},"message":{"type":"string"}},"title":"UNAUTHORIZED","description":"The access to this resource has been denied"}}}},"409":{"description":"A duplicate request with this idempotency key is already in progress","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["IDEMPOTENCY_IN_PROGRESS"]},"message":{"type":"string"}},"title":"IDEMPOTENCY_IN_PROGRESS","description":"A duplicate request with this idempotency key is already in progress"}}}},"422":{"description":"Another request with this idempotency key was made using a different body","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["IDEMPOTENCY_KEY_REUSED"]},"message":{"type":"string"}},"title":"IDEMPOTENCY_KEY_REUSED","description":"Another request with this idempotency key was made using a different body"}}}},"default":{"description":"Catch-all error response for any unexpected internal errors","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INTERNAL"]},"message":{"type":"string","enum":["An unexpected internal error has occurred"]}},"title":"INTERNAL","description":"Catch-all error response for any unexpected internal errors"}}}}}},"get":{"summary":"Search Reward Event Configurations","tags":["Events"],"description":"The CFX Rewards Engine supports the automation of reward issuance based off certain CFX Network events. This endpoint allows you to search for existing reward event configurations.\n\nThe search can be filtered to return either `ACTIVE` or `DISABLED` configurations. Each configuration returned will have a `status` (ACTIVE or DISABLED), an `event` name, and an array of reward `rules`. Rules are configured by specifying:\n\n* The `status` of the rule (ACTIVE or DISABLED)\n* The `event` the rule is triggered by\n* An array of reward `rules` to apply when the event occurs, which each specify a reward `amount`, `currency` and a `matcher` to filter the event more specifically.\n\nPlease see the Create Reward Event Configuration endpoint for more information.","parameters":[{"schema":{"type":"string","enum":["ACTIVE","DISABLED"]},"in":"query","name":"status","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","required":["status","event","rules","createdAt","updatedAt"],"properties":{"status":{"type":"string","enum":["ACTIVE","DISABLED"]},"event":{"type":"string","description":"The incoming event name to expect for this configuration"},"rules":{"type":"array","items":{"type":"object","required":["status","reward"],"properties":{"status":{"type":"string","enum":["ACTIVE","DISABLED"]},"reward":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number"},"currency":{"type":"string","enum":["MOVEUSD"]}},"description":"How much reward is awarded to identity or organization when this rule is matched"},"matcher":{"type":"object","properties":{},"additionalProperties":true,"description":"Criteria to match this rule more specifically to events"}},"description":"Rules for awarding events. The first matching rule wins."}},"createdAt":{"type":"string","format":"date-time","description":"When this record was created"},"updatedAt":{"type":"string","format":"date-time","description":"When this record was last updated"}}}}}}}}},"401":{"description":"The access to this resource has been denied","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["UNAUTHORIZED"]},"message":{"type":"string"}},"title":"UNAUTHORIZED","description":"The access to this resource has been denied"}}}},"default":{"description":"Catch-all error response for any unexpected internal errors","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INTERNAL"]},"message":{"type":"string","enum":["An unexpected internal error has occurred"]}},"title":"INTERNAL","description":"Catch-all error response for any unexpected internal errors"}}}}}}},"/v1/reward/event-config/{event}":{"get":{"summary":"Get Reward Event Configuration","tags":["Events"],"description":"The CFX Rewards Engine supports the automation of reward issuance based off certain CFX Network events. This endpoint allows you to retrieve the reward configurations for a specific event.\n\nConfiguration is retrieved by providing the `event` name within the URL path.\n\nPlease see the Create Reward Event Configuration endpoint for more information regarding the returned data types.","parameters":[{"schema":{"type":"string"},"in":"path","name":"event","required":true,"description":"The incoming event name to expect for this configuration"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["status","event","rules","createdAt","updatedAt"],"properties":{"status":{"type":"string","enum":["ACTIVE","DISABLED"]},"event":{"type":"string","description":"The incoming event name to expect for this configuration"},"rules":{"type":"array","items":{"type":"object","required":["status","reward"],"properties":{"status":{"type":"string","enum":["ACTIVE","DISABLED"]},"reward":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number"},"currency":{"type":"string","enum":["MOVEUSD"]}},"description":"How much reward is awarded to identity or organization when this rule is matched"},"matcher":{"type":"object","properties":{},"additionalProperties":true,"description":"Criteria to match this rule more specifically to events"}},"description":"Rules for awarding events. The first matching rule wins."}},"createdAt":{"type":"string","format":"date-time","description":"When this record was created"},"updatedAt":{"type":"string","format":"date-time","description":"When this record was last updated"}}}}}},"401":{"description":"The access to this resource has been denied","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["UNAUTHORIZED"]},"message":{"type":"string"}},"title":"UNAUTHORIZED","description":"The access to this resource has been denied"}}}},"404":{"description":"The resource was not found","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["NOT_FOUND"]},"message":{"type":"string"}},"title":"NOT_FOUND","description":"The resource was not found"}}}},"default":{"description":"Catch-all error response for any unexpected internal errors","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INTERNAL"]},"message":{"type":"string","enum":["An unexpected internal error has occurred"]}},"title":"INTERNAL","description":"Catch-all error response for any unexpected internal errors"}}}}}}}},"servers":[{"url":"https://api.dev.cfx.to","description":"Customer Sandbox"},{"url":"https://api.cfx.to","description":"Production"}],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"tags":[{"name":"Rewards"}],"externalDocs":{"description":"Find out more about CFX","url":"https://www.cfxlabs.com/"}}