{ "openapi": "3.0.2", "servers": [ { "url": "https://api-sandbox.circle.com" }, { "url": "https://api.circle.com" } ], "info": { "version": "2.16.0", "title": "All Circle APIs", "description": "Circle's General, Core Functionality, Crypto Deposits, Payouts, Accounts, and Crypto Payments APIs bundled into one OpenAPI Specification." }, "tags": [ { "name": "Addresses", "description": "Generate and get information on blockchain addresses." }, { "name": "Crypto Address Book", "description": "Manage blockchain addresses with metadata." }, { "name": "Balances", "description": "Get information on settled and unsettled balances." }, { "name": "Crypto Payment Intents", "description": "Create and track intent for end user to pay via crypto." }, { "name": "Deposits", "description": "Get information on 1st party deposits." }, { "name": "Exchange Rates", "description": "Pull estimated exchange rate for crypto currencies." }, { "name": "Health", "description": "Inspect the health of the API." }, { "name": "Management", "description": "General account and management information." }, { "name": "Payments", "description": "Get updates on whether user's crypto payment was received." }, { "name": "Payouts", "description": "Create and get information on address book payouts." }, { "name": "CUBIX", "description": "Create and get information on CUBIX accounts." }, { "name": "PIX", "description": "Create and get information on PIX accounts." }, { "name": "Stablecoins", "description": "Retrieve stablecoins and their respective names, symbols, circulating total and per-chain amounts." }, { "name": "Subscriptions", "description": "Manage subscriptions to notifications." }, { "name": "Transfers", "description": "Create transfers to another wallet or blockchain address, and get information on those transfers." }, { "name": "Wallets", "description": "Create digital wallets and get information on their activity." }, { "name": "Wires", "description": "Create, get instructions, and get information on bank accounts for wire transfers." }, { "name": "Trades", "description": "Execute currency exchange trades." }, { "name": "Settlements", "description": "Settlement endpoints" }, { "name": "Reserve Management", "description": "Report daily stablecoin balances to Circle." }, { "name": "External Entities", "description": "Manage your external entities." } ], "paths": { "/ping": { "get": { "summary": "Ping", "description": "Checks that the service is running.", "operationId": "ping", "tags": ["Health"], "responses": { "200": { "description": "Successful ping.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ping" }, "examples": { "response": { "value": { "message": "pong" } } } } } } } } }, "/v1/configuration": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "Get configuration info", "description": "Retrieves general configuration information.", "operationId": "getAccountConfig", "tags": ["Management"], "responses": { "200": { "description": "Successfully retrieved configuration information.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "GetConfigResponse", "properties": { "data": { "$ref": "#/components/schemas/AccountConfiguration" } } }, "examples": { "response": { "value": { "data": { "payments": { "masterWalletId": "212000" } } } } } } } } } } }, "/v1/notifications/subscriptions": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Create a notification subscription", "description": "Subscribe to receiving notifications at a given endpoint. The endpoint should be able to handle AWS SNS subscription requests. For more details see https://docs.aws.amazon.com/mobile/sdkforxamarin/developerguide/sns-send-http.html. Note, the sandbox environment allows a maximum of 3 active subscriptions; otherwise, this is limited to 1 active subscription and subsequent create requests will be rejected with a Limit Exceeded error.\n", "operationId": "createSubscription", "tags": ["Subscriptions"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionRequest" } } } }, "responses": { "200": { "description": "Successfully created a notification subscription.", "content": { "application/json": { "schema": { "title": "CreateSubscriptionResponse", "properties": { "data": { "$ref": "#/components/schemas/SubscriptionResponse" } } }, "examples": { "response": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "endpoint": "https://example.org/handler/for/notifications", "subscriptionDetails": [ { "url": "arn:aws:sns:us-east-1:<...>:fcb4a2c9-9c4f-4706-b312-6b22650f5d17", "status": "confirmed" } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "429": { "$ref": "#/components/responses/LimitExceeded" } } }, "get": { "security": [ { "bearerAuth": [] } ], "summary": "List all notification subscriptions", "description": "Retrieve a list of existing notification subscriptions with details.", "parameters": [], "operationId": "listSubscriptions", "tags": ["Subscriptions"], "responses": { "200": { "description": "Successfully retrieved a list of notification subscriptions.", "content": { "application/json": { "schema": { "title": "ListSubscriptionsResponse", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "examples": { "response": { "value": { "data": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "endpoint": "https://example.org/handler/for/notifications", "subscriptionDetails": [ { "url": "arn:aws:sns:us-east-1:<...>:fcb4a2c9-9c4f-4706-b312-6b22650f5d17", "status": "confirmed" } ] } ] } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/v1/notifications/subscriptions/{id}": { "delete": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "security": [ { "bearerAuth": [] } ], "summary": "Remove a notification subscription", "description": "To remove a subscription, all its subscription requests' statuses must be either 'confirmed', 'deleted' or a combination of those. A subscription with at least one 'pending' subscription request cannot be removed.", "operationId": "deleteSubscription", "tags": ["Subscriptions"], "responses": { "200": { "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "description": "Successfully removed a subscription.", "content": { "application/json": { "schema": { "title": "DeleteSubscriptionResponse", "properties": { "data": { "$ref": "#/components/schemas/UnsubscribeResponse" } } }, "examples": { "response": { "value": { "data": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/stablecoins": { "get": { "summary": "List all stablecoins", "description": "Retrieves total circulating supply for supported stablecoins across all chains. This endpoint is rate limited to one call per minute (based on IP).", "operationId": "listStablecoins", "tags": ["Stablecoins"], "responses": { "200": { "description": "Successfully retrieved all stablecoin supplies across all chains.", "content": { "application/json": { "schema": { "title": "ListStablecoinsResponse", "properties": { "data": { "$ref": "#/components/schemas/Stablecoins" } } }, "examples": { "response": { "value": { "data": [ { "name": "USD Coin", "symbol": "USDC", "totalAmount": "132.584192", "chains": [ { "amount": "132.584192", "chain": "ALGO" } ] } ] } } } } } }, "429": { "$ref": "#/components/responses/LimitExceeded" } } } }, "/v1/businessAccount/balances": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "List all balances", "description": "Retrieves the balance of funds that are available for use.", "operationId": "listBusinessBalances", "tags": ["Balances"], "parameters": [ { "name": "walletId", "description": "The wallet ID of the wallet for which to retrieve the balances. If not provided, the default is the main wallet of the account.\n\nYou can get wallet IDs associated with your account using the [Core API for Institutions](/api-reference/circle-mint/institutional/get-all-external-entities).\n", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved balances.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "ListBusinessBalancesResponse", "properties": { "data": { "$ref": "#/components/schemas/Balances" } } }, "examples": { "response": { "value": { "data": { "available": [ { "amount": "3.14", "currency": "USD" } ], "unsettled": [ { "amount": "3.14", "currency": "USD" } ] } } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/v1/businessAccount/banks/wires": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Create a wire bank account", "operationId": "createBusinessWireAccount", "tags": ["Wires"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WireCreationRequest" } } } }, "responses": { "201": { "description": "Successfully created a bank account for wire transfers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "CreateBusinessWireAccountResponse", "properties": { "data": { "$ref": "#/components/schemas/Wire" } } }, "examples": { "response": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "wire", "status": "pending", "description": "WELLS FARGO BANK, NA ****0010", "trackingRef": "CIR13FB13A", "transferTypesInfo": { "wire": { "currencies": ["USD", "EUR"] }, "rtgs": { "currencies": ["USD"] } }, "fingerprint": "eb170539-9e1c-4e92-bf4f-1d09534fdca2", "billingDetails": { "name": "Satoshi Nakamoto", "city": "Boston", "country": "US", "line1": "100 Money Street", "line2": "Suite 1", "district": "MA", "postalCode": "01234" }, "bankAddress": { "bankName": "SAN FRANCISCO", "city": "SAN FRANCISCO", "country": "US", "line1": "100 Money Street", "line2": "Suite 1", "district": "CA" }, "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z", "virtualAccountEnabled": false } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" } } }, "get": { "security": [ { "bearerAuth": [] } ], "summary": "List all wire bank accounts", "operationId": "listBusinessWireAccounts", "tags": ["Wires"], "responses": { "200": { "description": "Successfully retrieved a list of bank accounts.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "ListBusinessWireAccountsResponse", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Wire" } } } }, "examples": { "response": { "value": { "data": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "wire", "status": "pending", "description": "WELLS FARGO BANK, NA ****0010", "trackingRef": "CIR13FB13A", "transferTypesInfo": { "wire": { "currencies": ["USD", "EUR"] }, "rtgs": { "currencies": ["USD"] } }, "fingerprint": "eb170539-9e1c-4e92-bf4f-1d09534fdca2", "billingDetails": { "name": "Satoshi Nakamoto", "city": "Boston", "country": "US", "line1": "100 Money Street", "line2": "Suite 1", "district": "MA", "postalCode": "01234" }, "bankAddress": { "bankName": "SAN FRANCISCO", "city": "SAN FRANCISCO", "country": "US", "line1": "100 Money Street", "line2": "Suite 1", "district": "CA" }, "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z", "virtualAccountEnabled": false } ] } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/v1/businessAccount/banks/wires/{id}": { "get": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "security": [ { "bearerAuth": [] } ], "summary": "Get a wire bank account", "operationId": "getBusinessWireAccount", "tags": ["Wires"], "responses": { "200": { "description": "Successfully retrieved a bank account for wire transfers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "GetBusinessWireAccountResponse", "properties": { "data": { "$ref": "#/components/schemas/Wire" } } }, "examples": { "response": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "wire", "status": "pending", "description": "WELLS FARGO BANK, NA ****0010", "trackingRef": "CIR13FB13A", "transferTypesInfo": { "wire": { "currencies": ["USD", "EUR"] }, "rtgs": { "currencies": ["USD"] } }, "fingerprint": "eb170539-9e1c-4e92-bf4f-1d09534fdca2", "billingDetails": { "name": "Satoshi Nakamoto", "city": "Boston", "country": "US", "line1": "100 Money Street", "line2": "Suite 1", "district": "MA", "postalCode": "01234" }, "bankAddress": { "bankName": "SAN FRANCISCO", "city": "SAN FRANCISCO", "country": "US", "line1": "100 Money Street", "line2": "Suite 1", "district": "CA" }, "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z", "virtualAccountEnabled": false } } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/businessAccount/banks/wires/{id}/instructions": { "get": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/Currency" }, { "name": "walletId", "description": "The wallet ID of the external entity. If not provided, the instructions will be for your default wallet.\n\nYou can create additional wallets using the [Core API for Institutions](/api-reference/circle-mint/institutional/create-external-entity).\n", "in": "query", "required": false, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "summary": "Get wire instructions", "description": "Get the wire transfer instructions into the Circle bank account given your bank account ID.", "operationId": "getBusinessWireAccountInstructions", "tags": ["Wires"], "responses": { "200": { "description": "Successfully retrieved wire transfer instructions for the bank account.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "GetBusinessWireAccountInstructionsResponse", "properties": { "data": { "$ref": "#/components/schemas/WireInstruction" } } }, "examples": { "response": { "value": { "data": { "trackingRef": "CIR13FB13A", "beneficiary": { "name": "CIRCLE INTERNET FINANCIAL INC", "address1": "99 HIGH STREET", "address2": "BOSTON MA 02110" }, "beneficiaryBank": { "name": "WELLS FARGO BANK", "swiftCode": "WFBIUS6SXXX", "routingNumber": "121000248", "accountNumber": "****7427", "currency": "USD", "address": "4250 EXECUTIVE SQUARE SUITE 300", "city": "LA JOLLA", "postalCode": "02110", "country": "US" } } } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/businessAccount/banks/cubix": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Create a CUBIX bank account", "operationId": "createBusinessCubixAccount", "tags": ["CUBIX"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CubixFiatAccountCreationRequest" } } } }, "responses": { "201": { "description": "Successfully created a bank account for CUBIX transfers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "CreateBusinessCubixAccountResponse", "properties": { "data": { "$ref": "#/components/schemas/CubixFiatAccountResponse" } } }, "examples": { "response": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "status": "pending", "trackingRef": "CIR25XSXT8", "accountId": "ff2212d7-8476-4d1e-9d95-eda6455f4f54", "transferTypesInfo": { "cubix": { "currencies": ["USD"] } }, "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" } } }, "get": { "security": [ { "bearerAuth": [] } ], "summary": "List all CUBIX bank accounts.", "operationId": "listBusinessCubixAccounts", "tags": ["CUBIX"], "responses": { "200": { "description": "Successfully retrieved all bank accounts for CUBIX transfers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "ListBusinessCubixAccountsResponse", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CubixFiatAccountResponse" } } } }, "examples": { "response": { "value": { "data": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "status": "pending", "trackingRef": "CIR25XSXT8", "accountId": "ff2212d7-8476-4d1e-9d95-eda6455f4f54", "transferTypesInfo": { "cubix": { "currencies": ["USD"] } }, "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } ] } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/v1/businessAccount/banks/cubix/{id}": { "get": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "security": [ { "bearerAuth": [] } ], "summary": "Get a CUBIX bank account", "operationId": "getBusinessCubixAccount", "tags": ["CUBIX"], "responses": { "200": { "description": "Successfully retrieved a bank account for CUBIX transfers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "GetBusinessCubixAccountResponse", "properties": { "data": { "$ref": "#/components/schemas/CubixFiatAccountResponse" } } }, "examples": { "response": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "status": "pending", "trackingRef": "CIR25XSXT8", "accountId": "ff2212d7-8476-4d1e-9d95-eda6455f4f54", "transferTypesInfo": { "cubix": { "currencies": ["USD"] } }, "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/businessAccount/banks/cubix/{id}/instructions": { "get": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "security": [ { "bearerAuth": [] } ], "summary": "Get CUBIX instructions", "description": "Get the CUBIX transfer instructions into the Circle bank account given your fiat account id.", "operationId": "getBusinessCubixAccountInstructions", "tags": ["CUBIX"], "responses": { "200": { "description": "Successfully retrieved CUBIX transfer instructions for the fiat account.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "ListBusinessCubixAccountInstructionsResponse", "properties": { "data": { "$ref": "#/components/schemas/CubixInstruction" } } }, "examples": { "response": { "value": { "data": { "trackingRef": "CIR25XSXT8", "accountId": "ff2212d7-8476-4d1e-9d95-eda6455f4f54" } } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/businessAccount/banks/pix": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Create a PIX bank account", "operationId": "createBusinessPixAccount", "tags": ["PIX"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixFiatAccountCreationRequest" } } } }, "responses": { "201": { "description": "Successfully created a bank account for PIX transfers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "CreateBusinessPixAccountResponse", "properties": { "data": { "$ref": "#/components/schemas/PixFiatAccountResponse" } } }, "examples": { "response": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "status": "pending", "description": "BTG Pactual ****0010", "trackingRef": "CIR13FB13A", "transferTypesInfo": { "pix": { "currencies": ["BRL"] } }, "riskEvaluation": { "decision": "approved", "reason": "3000" }, "fingerprint": "eb170539-9e1c-4e92-bf4f-1d09534fdca2", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" } } }, "get": { "security": [ { "bearerAuth": [] } ], "summary": "List all PIX bank accounts.", "operationId": "listBusinessPixAccounts", "tags": ["PIX"], "responses": { "200": { "description": "Successfully retrieved all bank accounts for PIX transfers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "ListBusinessPixAccountsResponse", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PixFiatAccountResponse" } } } }, "examples": { "response": { "value": { "data": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "status": "pending", "description": "BTG Pactual ****0010", "trackingRef": "CIR13FB13A", "transferTypesInfo": { "pix": { "currencies": ["BRL"] } }, "riskEvaluation": { "decision": "approved", "reason": "3000" }, "fingerprint": "eb170539-9e1c-4e92-bf4f-1d09534fdca2", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } ] } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/v1/businessAccount/banks/pix/{id}": { "get": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "security": [ { "bearerAuth": [] } ], "summary": "Get a PIX bank account", "operationId": "getBusinessPixAccount", "tags": ["PIX"], "responses": { "200": { "description": "Successfully retrieved a bank account for PIX transfers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "GetBusinessPixAccountResponse", "properties": { "data": { "$ref": "#/components/schemas/PixFiatAccountResponse" } } }, "examples": { "response": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "status": "pending", "description": "BTG Pactual ****0010", "trackingRef": "CIR13FB13A", "transferTypesInfo": { "pix": { "currencies": ["BRL"] } }, "riskEvaluation": { "decision": "approved", "reason": "3000" }, "fingerprint": "eb170539-9e1c-4e92-bf4f-1d09534fdca2", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/businessAccount/banks/pix/{id}/instructions": { "get": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "security": [ { "bearerAuth": [] } ], "summary": "Get PIX instructions", "description": "Get the PIX transfer instructions into the Circle bank account given your bank account id.", "operationId": "getBusinessPixAccountInstructions", "tags": ["PIX"], "responses": { "200": { "description": "Successfully retrieved PIX transfer instructions for the bank account.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "BusinessPixAccountInstructionsResponse", "properties": { "data": { "$ref": "#/components/schemas/PixInstruction" } } }, "examples": { "response": { "value": { "data": { "trackingRef": "CIR25XSXT8", "ispb": "68033222", "branchCode": "123", "accountNumber": "322286803", "accountType": "checking", "taxId": "57112345675712", "name": "CIRCLE INTERNET FINANCIAL INC" } } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/businessAccount/wallets/addresses/deposit": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Create a deposit address", "description": "Generates a new blockchain address for a wallet for a given currency/chain pair. Circle may reuse addresses on blockchains that support reuse. For example, if you're requesting two addresses for depositing USD and ETH, both on Ethereum, you may see the same Ethereum address returned. Depositing cryptocurrency to a generated address will credit the associated wallet with the value of the deposit. Note: Circle Mint Singapore customers must verify all transfer recipients using the UI in the Circle Console, as transfers from unverified addresses will be held in `pending` status. \n", "operationId": "createBusinessDepositAddress", "parameters": [ { "name": "walletId", "description": "The wallet ID to be credited when deposits are made to this address. If not provided, deposits default to the main wallet of the account.\n\nYou can get wallet IDs associated with your account using the [Core API for Institutions](/api-reference/circle-mint/institutional/get-all-external-entities).\n", "in": "query", "required": false, "schema": { "type": "string" } } ], "tags": ["Addresses"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessGenerateAddressRequest" } } } }, "responses": { "201": { "description": "Successfully generated a new deposit address.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "CreateBusinessDepositAddressResponse", "properties": { "data": { "$ref": "#/components/schemas/AddressObject" } } }, "examples": { "response": { "value": { "data": { "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", "addressTag": "123456789", "currency": "USD", "chain": "ALGO", "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "walletId": "1000999922" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" } } }, "get": { "security": [ { "bearerAuth": [] } ], "summary": "List all deposit addresses", "description": "Returns a list of deposit addresses for a given wallet.", "parameters": [ { "name": "walletId", "description": "The wallet ID for which the deposit addresses were generated. If not provided, the default is the main wallet of the account.\n\nYou can get wallet IDs associated with your account using the [Core API for Institutions](/api-reference/circle-mint/institutional/get-all-external-entities).\n", "in": "query", "required": false, "schema": { "type": "string" } } ], "operationId": "getBusinessDepositAddress", "tags": ["Addresses"], "responses": { "200": { "description": "Successfully retrieved a list of deposit addresses.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "GetBusinessDepositAddressResponse", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AddressObject" } } } }, "examples": { "response": { "value": { "data": [ { "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", "addressTag": "123456789", "currency": "USD", "chain": "ALGO", "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "walletId": "1000999922" } ] } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/v1/businessAccount/wallets/addresses/recipient": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Create a recipient address", "description": "Stores an external blockchain address. Once added, the recipient address must be verified to ensure that you know and trust each new address. \n\n**For France customers:**\n\nCircle Mint France customers must verify all transfer recipients using the UI in the Circle Console, as transfers from unverified addresses will be held in pending status. Please see Help Center articles below for details:\n- [Circle Mint France Travel Rule](https://help.circle.com/s/article/Circle-Mint-France-Travel-Rule)\n- [Circle Mint France wallet verification](https://help.circle.com/s/article/Circle-Mint-France-wallet-verification)\n", "operationId": "createBusinessRecipientAddress", "tags": ["Addresses"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessRecipientAddressCreationRequest" } } } }, "responses": { "200": { "description": "Successfully added a recipient address.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "CreateBusinessRecipientAddressResponse", "properties": { "data": { "$ref": "#/components/schemas/BusinessRecipientAddressObject" } } }, "examples": { "response": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", "addressTag": "123456789", "chain": "ALGO", "currency": "USD", "description": "My USDC address at a cryptocurrency exchange", "status": "active" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" } } }, "get": { "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "$ref": "#/components/parameters/PageBefore" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageSize" } ], "summary": "List all recipient addresses", "description": "Returns a list of recipient addresses that have each been verified and are eligible for transfers. Any recipient addresses pending administrator verification are not included in the response.\n", "operationId": "listBusinessRecipientAddresses", "tags": ["Addresses"], "responses": { "200": { "description": "Successfully retrieved a list of recipient addresses.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "listBusinessRecipientAddressesResponse", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessRecipientAddressObject" } } } }, "examples": { "response": { "value": { "data": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", "addressTag": "123456789", "chain": "ALGO", "currency": "USD", "description": "My USDC address at a cryptocurrency exchange", "status": "active" } ] } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/v1/businessAccount/wallets/addresses/recipient/{id}": { "delete": { "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "summary": "Delete a recipient address", "description": "Deletes an external blockchain address. The recipient address must be in an 'active' or 'pending' state in order to be deleted successfully.\n", "operationId": "deleteBusinessRecipientAddress", "tags": ["Addresses"], "responses": { "200": { "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "description": "Successfully removed the recipient address." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/businessAccount/deposits": { "get": { "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "type", "description": "Unique identifier for the deposit type. Filters results to fetch deposits made by this specific type.", "in": "query", "schema": { "type": "string", "enum": ["wire"] } }, { "name": "walletId", "description": "The wallet ID to which the deposits were made. If not provided, the default is the main wallet of the account.\n\nYou can get wallet IDs associated with your account using the [Core API for Institutions](/api-reference/circle-mint/institutional/get-all-external-entities).\n", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "$ref": "#/components/parameters/PageBefore" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageSize" } ], "summary": "List all deposits", "description": "Searches for deposits sent to your business account. If the date parameters are omitted, returns the most recent deposits. This endpoint returns up to 50 deposits in descending chronological order or pageSize, if provided.", "operationId": "listBusinessDeposits", "tags": ["Deposits"], "responses": { "200": { "description": "Successfully retrieved a list of deposits.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "ListBusinessDepositsResponse", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessDeposit" } } } }, "examples": { "response": { "value": { "data": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "sourceWalletId": "9b57048d-2365-4ff5-956b-0199170d1035", "destination": { "type": "wallet", "id": "12345" }, "amount": { "amount": "3.14", "currency": "USD" }, "fee": { "amount": "3.14", "currency": "USD" }, "status": "pending", "riskEvaluation": { "decision": "approved", "reason": "3000" }, "customerExternalRef": "EXT01ABSJKDKASJHDS922", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z", "source": { "type": "wire", "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "name": "COMMERZBANK AG ****3000" }, "fromAmount": { "amount": "3.14", "currency": "USD" }, "fees": { "amount": "3.14", "currency": "USD" }, "externalRef": "b8627ae8-732b-4d25-b947-1df8f4007a29", "trackingRef": "CIR37N5FXJ" } ] } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/v1/businessAccount/deposits/{id}": { "get": { "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "name": "type", "description": "Filters results to get only deposits made by this specific type.", "in": "query", "schema": { "type": "string", "enum": ["wire"] } }, { "name": "walletId", "description": "The wallet ID to which the deposits were made. If not provided, the default is the main wallet of the account.", "in": "query", "required": false, "schema": { "type": "string" } } ], "summary": "Get a deposit by ID", "description": "Returns a deposit by ID.", "operationId": "getBusinessDepositById", "tags": ["Deposits"], "responses": { "200": { "description": "Successfully retrieved a deposit.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDeposit" }, "examples": { "response": { "value": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "sourceWalletId": "9b57048d-2365-4ff5-956b-0199170d1035", "destination": { "type": "wallet", "id": "12345" }, "amount": { "amount": "3.14", "currency": "USD" }, "fee": { "amount": "3.14", "currency": "USD" }, "status": "pending", "riskEvaluation": { "decision": "approved", "reason": "3000" }, "customerExternalRef": "EXT01ABSJKDKASJHDS922", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z", "source": { "type": "wire", "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "name": "COMMERZBANK AG ****3000" }, "fromAmount": { "amount": "3.14", "currency": "USD" }, "fees": { "amount": "3.14", "currency": "USD" }, "externalRef": "b8627ae8-732b-4d25-b947-1df8f4007a29", "trackingRef": "CIR37N5FXJ" } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/paymentIntents": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Create a payment intent", "description": "Create a transient or continuous payment intent", "operationId": "createPaymentIntent", "tags": ["Crypto Payment Intents"], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PaymentIntentCreationRequest" }, { "$ref": "#/components/schemas/ContinuousPaymentIntentCreationRequest" } ] } } } }, "responses": { "201": { "description": "Successfully created a payment intent.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "CreatePaymentIntentResponse", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/PaymentIntent" }, { "$ref": "#/components/schemas/ContinuousPaymentIntent" } ] } } }, "examples": { "Transient Payment Intent": { "value": { "data": { "id": "8755d0ea-14f9-4259-b092-de23c14b6568", "amount": { "amount": "3.14", "currency": "USD" }, "amountPaid": { "amount": "0.00", "currency": "USD" }, "settlementCurrency": "USD", "paymentMethods": [ { "type": "blockchain", "chain": "ETH" } ], "paymentIds": [], "timeline": [ { "status": "created", "time": "2022-07-21T20:13:35.579331Z" } ], "createDate": "2022-07-21T20:13:35.578678Z", "updateDate": "2022-07-21T20:19:24.859052Z" } } }, "Continuous Payment Intent": { "value": { "data": { "id": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b", "currency": "USD", "settlementCurrency": "USD", "amountPaid": { "amount": "0.00", "currency": "USD" }, "paymentMethods": [ { "type": "blockchain", "chain": "ETH" } ], "timeline": [ { "status": "created", "time": "2023-01-21T20:13:35.579331Z" } ], "type": "continuous", "createDate": "2023-01-21T20:13:35.578678Z", "updateDate": "2023-01-21T20:13:35.578678Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "security": [ { "bearerAuth": [] } ], "summary": "List all payment intents", "operationId": "listPaymentIntents", "tags": ["Crypto Payment Intents"], "parameters": [ { "name": "status", "description": "Filters by the most recent `timeline.status` within the payment intent.", "in": "query", "required": false, "schema": { "type": "string", "enum": ["created", "pending", "complete", "expired", "failed"] } }, { "name": "context", "description": "Filters by the most recent `timeline.context` within the payment intent.", "in": "query", "required": false, "schema": { "type": "string", "enum": ["underpaid", "paid", "overpaid"] } }, { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "$ref": "#/components/parameters/PageBefore" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageSize" } ], "responses": { "200": { "description": "Successfully retrieved a list of payment intents.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "ListPaymentIntentsResponse", "properties": { "data": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/PaymentIntent" }, { "$ref": "#/components/schemas/ContinuousPaymentIntent" } ] } } } }, "examples": { "Transient Payment Intent": { "value": { "data": [ { "id": "8755d0ea-14f9-4259-b092-de23c14b6568", "amount": { "amount": "3.14", "currency": "USD" }, "amountPaid": { "amount": "0.00", "currency": "USD" }, "settlementCurrency": "USD", "paymentMethods": [ { "type": "blockchain", "chain": "ETH" } ], "paymentIds": [], "timeline": [ { "status": "created", "time": "2022-07-21T20:13:35.579331Z" } ], "createDate": "2022-07-21T20:13:35.578678Z", "updateDate": "2022-07-21T20:19:24.859052Z" } ] } }, "Continuous Payment Intent": { "value": { "data": [ { "id": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b", "currency": "USD", "settlementCurrency": "USD", "amountPaid": { "amount": "0.00", "currency": "USD" }, "paymentMethods": [ { "type": "blockchain", "chain": "ETH" } ], "timeline": [ { "status": "created", "time": "2023-01-21T20:13:35.579331Z" } ], "type": "continuous", "createDate": "2023-01-21T20:13:35.578678Z", "updateDate": "2023-01-21T20:13:35.578678Z" } ] } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/v1/paymentIntents/{id}": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "Get a payment intent", "operationId": "getPaymentIntent", "tags": ["Crypto Payment Intents"], "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Successfully retrieved a payment intent.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "GetPaymentIntentResponse", "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/PaymentIntent" }, { "$ref": "#/components/schemas/ContinuousPaymentIntent" } ] } } }, "examples": { "Transient Payment Intent": { "value": { "data": { "id": "8755d0ea-14f9-4259-b092-de23c14b6568", "amount": { "amount": "3.14", "currency": "USD" }, "amountPaid": { "amount": "0.00", "currency": "USD" }, "settlementCurrency": "USD", "paymentMethods": [ { "type": "blockchain", "chain": "ETH" } ], "paymentIds": [], "timeline": [ { "status": "created", "time": "2022-07-21T20:13:35.579331Z" } ], "createDate": "2022-07-21T20:13:35.578678Z", "updateDate": "2022-07-21T20:19:24.859052Z" } } }, "Continuous Payment Intent": { "value": { "data": { "id": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b", "currency": "USD", "settlementCurrency": "USD", "amountPaid": { "amount": "0.00", "currency": "USD" }, "paymentMethods": [ { "type": "blockchain", "chain": "ETH" } ], "timeline": [ { "status": "created", "time": "2023-01-21T20:13:35.579331Z" } ], "type": "continuous", "createDate": "2023-01-21T20:13:35.578678Z", "updateDate": "2023-01-21T20:13:35.578678Z" } } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/paymentIntents/{id}/expire": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Expire a payment intent", "operationId": "expirePaymentIntent", "tags": ["Crypto Payment Intents"], "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Successfully expired a payment intent.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "ExpirePaymentIntentResponse", "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/PaymentIntent" }, { "$ref": "#/components/schemas/ContinuousPaymentIntent" } ] } } }, "examples": { "Transient Payment Intent": { "value": { "data": { "id": "8755d0ea-14f9-4259-b092-de23c14b6568", "amount": { "amount": "3.14", "currency": "USD" }, "amountPaid": { "amount": "0.00", "currency": "USD" }, "settlementCurrency": "USD", "paymentMethods": [ { "type": "blockchain", "chain": "ETH" } ], "paymentIds": [], "timeline": [ { "status": "created", "time": "2022-07-21T20:13:35.579331Z" } ], "createDate": "2022-07-21T20:13:35.578678Z", "updateDate": "2022-07-21T20:19:24.859052Z" } } }, "Continuous Payment Intent": { "value": { "data": { "id": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b", "currency": "USD", "settlementCurrency": "USD", "amountPaid": { "amount": "0.00", "currency": "USD" }, "paymentMethods": [ { "type": "blockchain", "chain": "ETH" } ], "timeline": [ { "status": "created", "time": "2023-01-21T20:13:35.579331Z" } ], "type": "continuous", "createDate": "2023-01-21T20:13:35.578678Z", "updateDate": "2023-01-21T20:13:35.578678Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/paymentIntents/{id}/refund": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Refund a payment intent", "operationId": "refundPaymentIntent", "tags": ["Crypto Payment Intents"], "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CryptoRefundCreationRequest" } } } }, "responses": { "201": { "description": "Crypto refund successfully created for the given payment intent.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "CreateCryptoRefundResponse", "properties": { "data": { "$ref": "#/components/schemas/CryptoPayment" } } }, "examples": { "response": { "value": { "data": { "id": "3389f4ba-aafd-4eef-aaa2-3292df8f62e6", "type": "refund", "status": "pending", "amount": { "currency": "USD" }, "merchantId": "5ffea093-d210-44b4-a7ca-ad33b9498188", "merchantWalletId": "1000999922", "paymentIntentId": "77c91fe9-e603-4e7b-9672-1ef8ac502cf6", "settlementAmount": { "amount": "1.00", "currency": "ETH" }, "fromAddresses": { "chain": "ETH", "addresses": [ "0x0d4344cFF68F72A5B9Abded37CA5862941a62050" ] }, "depositAddress": { "chain": "ETH", "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f" }, "createDate": "2022-07-21T20:16:35.092852Z", "updateDate": "2022-07-21T20:19:24.719313Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/addressBook/recipients": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Create a recipient", "operationId": "createAddressBookRecipient", "tags": ["Crypto Address Book"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBookRecipientRequest" } } } }, "responses": { "201": { "description": "Successfully created an address book recipient.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "CreateAddressBookRecipientResponse", "properties": { "data": { "$ref": "#/components/schemas/AddressBookRecipient" } } }, "examples": { "response": { "value": { "data": { "id": "8755d0ea-14f9-4259-b092-de23c14b6568", "chain": "ETH", "address": "0x45bfcf1a6289a0b77b4d3f7d12005a05949fd8c3", "metadata": { "nickname": "sample nickname", "email": "satoshi@circle.com", "bns": "sample.circle" }, "status": "pending", "createDate": "2022-07-21T20:13:35.578678Z", "updateDate": "2022-07-21T20:19:24.859052Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" } } }, "get": { "security": [ { "bearerAuth": [] } ], "summary": "List all recipients", "operationId": "listAddressBookRecipients", "tags": ["Crypto Address Book"], "parameters": [ { "name": "address", "description": "Filters results to fetch only address book recipients with the provided address.", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "chain", "description": "Filters results to fetch only address book recipients with the provided chain.", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "email", "description": "Filters results to fetch only address book recipients that have the provided email in their metadata.", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "description": "Filters results to fetch only address book recipients that have the provided status.", "in": "query", "required": false, "schema": { "type": "string", "enum": ["pending", "inactive", "active", "denied"] } }, { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "$ref": "#/components/parameters/PageBefore" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageSize" } ], "responses": { "200": { "description": "Successfully retrieved a list of address book recipients.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "ListAddressBookRecipientsResponse", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AddressBookRecipient" } } } }, "examples": { "response": { "value": { "data": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "chain": "ALGO", "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", "addressTag": "123456789", "metadata": { "nickname": "sample nickname", "email": "satoshi@circle.com", "bns": "sample.circle" }, "status": "pending", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } ] } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/v1/addressBook/recipients/{id}": { "get": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "security": [ { "bearerAuth": [] } ], "summary": "Get a recipient", "operationId": "getAddressBookRecipient", "tags": ["Crypto Address Book"], "responses": { "200": { "description": "Successfully retrieved an address book recipient.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "GetAddressBookRecipientResponse", "properties": { "data": { "$ref": "#/components/schemas/AddressBookRecipient" } } }, "examples": { "response": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "chain": "ALGO", "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", "addressTag": "123456789", "metadata": { "nickname": "sample nickname", "email": "satoshi@circle.com", "bns": "sample.circle" }, "status": "pending", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "security": [ { "bearerAuth": [] } ], "summary": "Modify a recipient", "operationId": "modifyAddressBookRecipient", "tags": ["Crypto Address Book"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBookRecipientModifyRequest" } } } }, "responses": { "200": { "description": "Successfully updated the address book recipient.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "ModifyAddressBookRecipientResponse", "properties": { "data": { "$ref": "#/components/schemas/AddressBookRecipient" } } }, "examples": { "response": { "value": { "data": { "id": "8755d0ea-14f9-4259-b092-de23c14b6568", "chain": "ETH", "address": "0x45bfcf1a6289a0b77b4d3f7d12005a05949fd8c3", "metadata": { "nickname": "sample nickname", "email": "satoshi@circle.com", "bns": "sample.circle" }, "status": "pending", "createDate": "2022-07-21T20:13:35.578678Z", "updateDate": "2022-07-21T20:19:24.859052Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "security": [ { "bearerAuth": [] } ], "summary": "Delete a recipient", "operationId": "deleteAddressBookRecipient", "tags": ["Crypto Address Book"], "responses": { "200": { "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "description": "Successfully removed the address book recipient." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/payments": { "get": { "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Source" }, { "$ref": "#/components/parameters/SettlementId" }, { "$ref": "#/components/parameters/PaymentIntentId" }, { "$ref": "#/components/parameters/PaymentSourceType" }, { "$ref": "#/components/parameters/PaymentStatus" }, { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "$ref": "#/components/parameters/PageBefore" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageSize" } ], "summary": "List all payments", "operationId": "listPayments", "tags": ["Payments"], "responses": { "200": { "description": "Successfully retrieved a list of payments.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "ListPaymentsResponse", "properties": { "data": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/FiatPayment" }, { "$ref": "#/components/schemas/CryptoPayment" }, { "$ref": "#/components/schemas/FiatCancel" }, { "$ref": "#/components/schemas/FiatRefund" } ] } } } }, "examples": { "Fiat Payment": { "value": { "data": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "payment", "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", "merchantWalletId": "212000", "amount": { "amount": "3.14", "currency": "USD" }, "fromAmount": { "amount": "3.14", "currency": "EUR" }, "source": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "card" }, "description": "Payment", "status": "pending", "captured": false, "captureAmount": { "amount": "3.14", "currency": "USD" }, "captureDate": "2020-04-10T02:13:30.000Z", "requiredAction": { "type": "three_d_secure_required", "redirectUrl": "https://example.org" }, "cancel": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "cancel", "description": "Payment", "status": "pending", "createDate": "2020-04-10T02:13:30.000Z" }, "refunds": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "payment", "amount": { "amount": "3.14", "currency": "USD" }, "description": "Payment", "status": "pending", "requiredAction": { "type": "three_d_secure_required", "redirectUrl": "https://example.org" }, "fees": { "amount": "3.14", "currency": "USD" }, "createDate": "2020-04-10T02:13:30.000Z" } ], "fees": { "amount": "3.14", "currency": "USD" }, "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } ] } }, "Crypto Payment": { "value": { "data": [ { "id": "66c56b6a-fc79-338b-8b94-aacc4f0f18de", "type": "payment", "status": "paid", "amount": { "amount": "1.00", "currency": "USD" }, "fees": { "amount": "0.01", "currency": "USD" }, "networkFees": { "amount": "0.01", "currency": "USD", "feePayer": "endUser" }, "merchantId": "f1397191-56e6-42fd-be86-0a7b9bd91522", "merchantWalletId": "1000999922", "paymentIntentId": "6e4d4047-db14-4c09-b238-1215aee50d03", "settlementAmount": { "amount": "1.00", "currency": "USD" }, "fromAddresses": { "chain": "ETH", "addresses": [ "0x0d4344cFF68F72A5B9Abded37CA5862941a62050" ] }, "depositAddress": { "chain": "ETH", "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f" }, "transactionHash": "0x7351585460bd657f320b9afa02a52c26d89272d0d10cc29913eb8b28e64fd906", "createDate": "2022-07-21T20:16:35.092852Z", "updateDate": "2022-07-21T20:19:24.719313Z" } ] } }, "Fiat Cancel": { "value": { "data": [ { "id": "2dc266f5-0658-48ec-a81f-9c768279564d", "type": "cancel", "status": "confirmed", "description": "Cancel Payment", "amount": { "amount": "10.00", "currency": "USD" }, "createDate": "2022-04-21T21:50:34.274Z", "updateDate": "2022-04-21T21:50:34.647839Z", "merchantId": "b1e4e9fe-0bf1-43ad-86c7-3ab993b0051b", "merchantWalletId": "1000174786", "source": { "id": "bc9157fe-5d73-48fe-9e77-9f6723bdcfeb", "type": "card" }, "originalPayment": { "id": "2812f549-062a-4bdd-8ee5-b521aa48a84d", "type": "payment", "status": "failed", "createDate": "2022-04-21T21:47:41.501Z", "updateDate": "2022-04-21T21:50:34.669012Z" }, "reason": "requested_by_customer" } ] } }, "Fiat Refund": { "value": { "data": [ { "id": "03fbe7da-096a-4763-af77-e43006cd83be", "type": "refund", "status": "paid", "description": "Refund Payment", "amount": { "amount": "3.14", "currency": "USD" }, "fees": { "amount": "0.00", "currency": "USD" }, "createDate": "2022-04-21T12:49:21.146Z", "updateDate": "2022-04-21T12:54:10.596976Z", "merchantId": "b1e4e9fe-0bf1-43ad-86c7-3ab993b0051b", "merchantWalletId": "1000174786", "source": { "id": "45fa5524-41b9-48ca-94cd-f45cb36cce4d", "type": "card" }, "originalPayment": { "id": "895f8db5-1d8c-407d-9533-b5ca3fbcc74e", "type": "payment", "status": "paid", "createDate": "2022-04-06T19:33:29.690Z", "updateDate": "2022-04-06T19:47:23.681180Z" }, "reason": "requested_by_customer" } ] } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/v1/payments/{id}": { "get": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "security": [ { "bearerAuth": [] } ], "summary": "Get a payment", "operationId": "getPayment", "tags": ["Payments"], "responses": { "200": { "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "description": "Successfully retrieved a payment.", "content": { "application/json": { "schema": { "title": "GetPaymentResponse", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/FiatPaymentPolymorphic" }, { "$ref": "#/components/schemas/CryptoPayment" } ] } } }, "examples": { "Fiat Payment": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "payment", "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", "merchantWalletId": "212000", "amount": { "amount": "3.14", "currency": "USD" }, "fromAmount": { "amount": "3.14", "currency": "EUR" }, "source": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "card" }, "description": "Payment", "status": "pending", "requiredAction": { "type": "three_d_secure_required", "redirectUrl": "https://example.org" }, "verification": { "avs": "D", "cvv": "not_requested", "threeDSecure": "pass", "eci": "00" }, "originalPayment": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "payment", "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", "merchantWalletId": "212000", "amount": { "amount": "3.14", "currency": "USD" }, "source": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "card" }, "description": "Payment", "status": "pending", "captured": false, "captureAmount": { "amount": "3.14", "currency": "USD" }, "captureDate": "2020-04-10T02:13:30.000Z", "requiredAction": { "type": "three_d_secure_required", "redirectUrl": "https://example.org" }, "cancel": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "cancel", "description": "Payment", "status": "pending", "createDate": "2020-04-10T02:13:30.000Z" }, "refunds": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "payment", "amount": { "amount": "3.14", "currency": "USD" }, "description": "Payment", "status": "pending", "requiredAction": { "type": "three_d_secure_required", "redirectUrl": "https://example.org" }, "fees": { "amount": "3.14", "currency": "USD" }, "createDate": "2020-04-10T02:13:30.000Z" } ], "fees": { "amount": "3.14", "currency": "USD" }, "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" }, "cancel": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "cancel", "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", "merchantWalletId": "212000", "amount": { "amount": "3.14", "currency": "USD" }, "source": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "card" }, "description": "Payment", "status": "pending", "originalPayment": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "payment", "amount": { "amount": "3.14", "currency": "USD" }, "description": "Payment", "status": "pending", "requiredAction": { "type": "three_d_secure_required", "redirectUrl": "https://example.org" }, "fees": { "amount": "3.14", "currency": "USD" }, "createDate": "2020-04-10T02:13:30.000Z" }, "fees": { "amount": "3.14", "currency": "USD" }, "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" }, "refunds": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "refund", "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", "merchantWalletId": "212000", "amount": { "amount": "3.14", "currency": "USD" }, "source": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "card" }, "description": "Payment", "status": "pending", "originalPayment": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "payment", "amount": { "amount": "3.14", "currency": "USD" }, "description": "Payment", "status": "pending", "requiredAction": { "type": "three_d_secure_required", "redirectUrl": "https://example.org" }, "fees": { "amount": "3.14", "currency": "USD" }, "createDate": "2020-04-10T02:13:30.000Z" }, "cancel": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "cancel", "description": "Payment", "status": "pending", "createDate": "2020-04-10T02:13:30.000Z" }, "fees": { "amount": "3.14", "currency": "USD" }, "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } ], "fees": { "amount": "3.14", "currency": "USD" }, "trackingRef": "24910599141085313498894", "externalRef": "YYYYMMDDXXXXXXXX012345", "errorCode": "payment_failed", "metadata": { "email": "satoshi@circle.com", "phoneNumber": "+14155555555" }, "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", "riskEvaluation": { "decision": "approved", "reason": "3000" }, "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } } }, "Crypto Payment": { "value": { "data": { "id": "66c56b6a-fc79-338b-8b94-aacc4f0f18de", "type": "payment", "status": "paid", "amount": { "amount": "1.00", "currency": "USD" }, "fees": { "amount": "0.01", "currency": "USD" }, "networkFees": { "amount": "0.01", "currency": "USD", "feePayer": "endUser" }, "merchantId": "f1397191-56e6-42fd-be86-0a7b9bd91522", "merchantWalletId": "1000999922", "paymentIntentId": "6e4d4047-db14-4c09-b238-1215aee50d03", "settlementAmount": { "amount": "1.00", "currency": "USD" }, "fromAddresses": { "chain": "ETH", "addresses": [ "0x0d4344cFF68F72A5B9Abded37CA5862941a62050" ] }, "depositAddress": { "chain": "ETH", "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f" }, "transactionHash": "0x7351585460bd657f320b9afa02a52c26d89272d0d10cc29913eb8b28e64fd906", "createDate": "2022-07-21T20:16:35.092852Z", "updateDate": "2022-07-21T20:19:24.719313Z" } } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/businessAccount/payouts": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Create a payout", "description": "Create a redemption (offramp) payout. This payout converts a digital asset to fiat currency.\n", "operationId": "createBusinessPayout", "tags": ["Payouts"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPayoutCreationRequest" } } } }, "responses": { "201": { "description": "Successfully created a payout.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "CreateBusinessPayoutResponse", "properties": { "data": { "$ref": "#/components/schemas/BusinessPayout" } } }, "examples": { "response": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "sourceWalletId": "53535335", "destination": { "type": "wire", "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "name": "COMMERZBANK AG ****3000" }, "amount": { "amount": "3.14", "currency": "USD" }, "toAmount": { "amount": "3.14", "currency": "USD" }, "fees": { "amount": "3.14", "currency": "USD" }, "status": "pending", "trackingRef": "CIR-6ESOQANEP3NAO", "errorCode": "insufficient_funds", "riskEvaluation": { "decision": "approved", "reason": "3000" }, "adjustments": { "fxCredit": { "amount": "3.14", "currency": "USD" }, "fxDebit": { "amount": "3.14", "currency": "USD" } }, "return": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "payoutId": "abdb500d-4a59-457c-801f-2d418c8703ac", "amount": { "amount": "3.14", "currency": "USD" }, "fees": { "amount": "3.14", "currency": "USD" }, "reason": "payout_returned", "status": "pending", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" }, "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" } } }, "get": { "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Destination" }, { "name": "type", "description": "Destination bank account type. Filters the results to fetch all payouts made to a specified destination bank account type. This query parameter can be passed multiple times to fetch results matching multiple destination bank account types.", "in": "query", "required": false, "schema": { "type": "string", "enum": ["wire", "cubix"] } }, { "name": "status", "description": "Queries items with the specified status. Matches any status if unspecified.", "in": "query", "required": false, "schema": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/PayoutStatus" } } }, { "name": "sourceWalletId", "description": "Filters for payouts created from a specific source wallet.", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "$ref": "#/components/parameters/PageBefore" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageSize" } ], "summary": "List all payouts", "description": "Lists all payouts for your account.\n\nNote that this endpoint does not return the tracking reference number for the payouts in the response. If you need that information you must get each payout individually by ID.\n", "operationId": "listBusinessPayouts", "tags": ["Payouts"], "responses": { "200": { "description": "Successfully retrieved a list of payouts.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBusinessPayout" }, "examples": { "response": { "value": { "data": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "sourceWalletId": "53535335", "destination": { "type": "wire", "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "name": "COMMERZBANK AG ****3000" }, "amount": { "amount": "3.14", "currency": "USD" }, "toAmount": { "amount": "3.14", "currency": "USD" }, "fees": { "amount": "3.14", "currency": "USD" }, "status": "pending", "errorCode": "insufficient_funds", "riskEvaluation": { "decision": "approved", "reason": "3000" }, "adjustments": { "fxCredit": { "amount": "3.14", "currency": "USD" }, "fxDebit": { "amount": "3.14", "currency": "USD" } }, "return": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "payoutId": "abdb500d-4a59-457c-801f-2d418c8703ac", "amount": { "amount": "3.14", "currency": "USD" }, "fees": { "amount": "3.14", "currency": "USD" }, "reason": "payout_returned", "status": "pending", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" }, "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } ] } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/v1/businessAccount/payouts/{id}": { "get": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "security": [ { "bearerAuth": [] } ], "summary": "Get a payout", "operationId": "getBusinessPayout", "tags": ["Payouts"], "responses": { "200": { "description": "Successfully retrieved a payout.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "GetBusinessPayoutResponse", "properties": { "data": { "$ref": "#/components/schemas/BusinessPayout" } } }, "examples": { "response": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "sourceWalletId": "53535335", "destination": { "type": "wire", "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "name": "COMMERZBANK AG ****3000" }, "amount": { "amount": "3.14", "currency": "USD" }, "toAmount": { "amount": "3.14", "currency": "USD" }, "fees": { "amount": "3.14", "currency": "USD" }, "status": "pending", "trackingRef": "CIR-6ESOQANEP3NAO", "errorCode": "insufficient_funds", "riskEvaluation": { "decision": "approved", "reason": "3000" }, "adjustments": { "fxCredit": { "amount": "3.14", "currency": "USD" }, "fxDebit": { "amount": "3.14", "currency": "USD" } }, "return": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "payoutId": "abdb500d-4a59-457c-801f-2d418c8703ac", "amount": { "amount": "3.14", "currency": "USD" }, "fees": { "amount": "3.14", "currency": "USD" }, "reason": "payout_returned", "status": "pending", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" }, "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/payouts": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Create a payout", "description": "\nCreate a crypto payout. \n\nThe following table includes the supported pairs of `amount.currency` and `toAmount.currency` for address book payouts:\n\n| amount.currency | toAmount.currency |\n| ---------------- | ----------------- |\n| USD | USD |\n| EUR | EUR |\n", "operationId": "createPayout", "tags": ["Payouts"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CryptoPayoutCreationRequest" } } } }, "responses": { "201": { "description": "Successfully created a payout.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "CreatePayoutResponse", "properties": { "data": { "$ref": "#/components/schemas/CryptoPayout" } } }, "examples": { "Crypto Payout": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "sourceWalletId": "53535335", "destination": { "type": "address_book", "id": "b8627ae8-732b-4d25-b947-1df8f4007a29" }, "amount": { "amount": "3.14", "currency": "USD" }, "toAmount": { "amount": "3.14", "currency": "ETH" }, "fees": { "amount": "3.14", "currency": "USD" }, "networkFees": { "amount": "0.14", "currency": "USD" }, "status": "pending", "errorCode": "transaction_denied", "riskEvaluation": { "decision": "denied", "reason": "4000" }, "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" } } }, "get": { "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "source", "description": "Identifier for the source wallet. Filters the fetched payout results to only be from a specific source wallet. If not provided, payouts from all wallets will be returned.", "in": "query", "required": false, "schema": { "type": "string", "example": "1000565227" } }, { "name": "destination", "description": "Universally unique identifier (UUID v4) for the destination. Filters the fetched payout results made to a specific destination. If not provided, payouts to all destinations will be returned.", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "54c1cbab-c419-450f-ad23-906fa03af7f0" } }, { "name": "type", "description": "Destination type. Filters the results to fetch all payouts made to a specified destination type. This query parameter can be passed multiple times to fetch results matching multiple destination types. The address_book destination type cannot be combined with other types.", "in": "query", "required": false, "schema": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/PayoutDestinationType" } } }, { "name": "status", "description": "Queries items with the specified status. Matches any status if unspecified.", "in": "query", "required": false, "schema": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/PayoutStatus" } } }, { "name": "sourceCurrency", "description": "Queries items with the specified source currency `amount.currency`. Matches any source currency if unspecified.", "in": "query", "required": false, "schema": { "type": "string", "enum": ["USD", "EUR", "BTC", "ETH", "MTC", "FLW", "MAN"] } }, { "name": "destinationCurrency", "description": "Queries items with the specified destination currency `toAmount.currency`. Matches any destination currency if unspecified.", "in": "query", "required": false, "schema": { "type": "string", "enum": ["USD", "EUR", "BTC", "ETH", "MTC", "FLW", "MAN"] } }, { "$ref": "#/components/parameters/Chain" }, { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "$ref": "#/components/parameters/PageBefore" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageSize" } ], "summary": "List all payouts", "operationId": "listPayouts", "tags": ["Payouts"], "responses": { "200": { "description": "Successfully retrieved a list of payouts.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "ListPayoutsResponse", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CryptoPayout" } } } }, "examples": { "Crypto Payout": { "value": { "data": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "sourceWalletId": "53535335", "destination": { "type": "address_book", "id": "b8627ae8-732b-4d25-b947-1df8f4007a29" }, "amount": { "amount": "3.14", "currency": "USD" }, "toAmount": { "amount": "3.14", "currency": "ETH" }, "fees": { "amount": "3.14", "currency": "USD" }, "networkFees": { "amount": "0.14", "currency": "USD" }, "status": "pending", "errorCode": "transaction_denied", "riskEvaluation": { "decision": "denied", "reason": "4000" }, "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } ] } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/v1/payouts/{id}": { "get": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "security": [ { "bearerAuth": [] } ], "summary": "Get a payout", "operationId": "getPayout", "tags": ["Payouts"], "responses": { "200": { "description": "Successfully retrieved a payout.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "GetPayoutResponse", "properties": { "data": { "$ref": "#/components/schemas/CryptoPayout" } } }, "examples": { "Crypto Payout": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "sourceWalletId": "53535335", "destination": { "type": "address_book", "id": "b8627ae8-732b-4d25-b947-1df8f4007a29" }, "amount": { "amount": "3.14", "currency": "USD" }, "toAmount": { "amount": "3.14", "currency": "ETH" }, "fees": { "amount": "3.14", "currency": "USD" }, "networkFees": { "amount": "0.14", "currency": "USD" }, "status": "pending", "errorCode": "transaction_denied", "riskEvaluation": { "decision": "denied", "reason": "4000" }, "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/exchange/quotes": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Get quote", "operationId": "getQuote", "description": "Fetches an indicative exchange rate between two currencies. Either the from currency or to currency must be USD.\nNote: The current market exchange rate will be applied when Circle receives the deposit.\n", "tags": ["Trades"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeRateRequest" } } } }, "responses": { "201": { "description": "Successfully fetched quote.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "FetchExchangeRateResponse", "properties": { "data": { "$ref": "#/components/schemas/ExchangeRateResponse" } } }, "examples": { "response": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "rate": 0.1974, "from": { "amount": "3.14", "currency": "USD" }, "to": { "amount": "3.14", "currency": "USD" }, "expiry": "2020-04-10T02:13:30.000Z", "type": "tradable", "estimatedSettlementTime": "2020-04-10T03:13:30.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/fees/redemption/dailyReports": { "get": { "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "minimumFeeAmount", "description": "Burn fee calculations below this value are filtered.", "in": "query", "required": false, "schema": { "type": "string", "example": "3.14" } }, { "name": "feeType", "description": "Fee calculation type", "in": "query", "required": true, "schema": { "type": "string", "enum": ["gross", "net"], "example": "net" } }, { "$ref": "#/components/parameters/Currency" }, { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "$ref": "#/components/parameters/PageBefore" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageSize" } ], "summary": "List daily burn fee calculations", "description": "Returns daily burn fee calculations. This endpoint returns up to 50 daily fee calculations in descending chronological order or `pageSize`, if provided.", "operationId": "listNetBurnFeeDailyCalculations", "tags": ["Payouts"], "responses": { "200": { "description": "Successfully retrieved a list of burn fee calculations.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "ListBurnFeeCalculationsResponse", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RedemptionFeeCalculation" } } } }, "examples": { "response": { "value": { "data": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "fee": { "amount": "3.14", "currency": "USD" }, "cumulatedPayoutAmount": { "amount": "64.54", "currency": "USD" }, "cumulatedPaymentAmount": { "amount": "34.54", "currency": "USD" }, "cumulatedNetAmount": { "amount": "30.00", "currency": "USD" }, "valueDate": "2023-05-23", "status": "paid", "thresholdResetTimestamp": "2023-05-23T23:59:59.999Z", "createDate": "2024-04-10T02:13:30.000Z" } ] } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/v1/businessAccount/transfers": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Create a transfer", "description": "A transfer can be made from an existing business account to a blockchain location.", "operationId": "createBusinessTransfer", "tags": ["Transfers"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessTransferCreationRequest" } } } }, "responses": { "201": { "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "description": "Successfully created a transfer.", "content": { "application/json": { "schema": { "title": "CreateBusinessTransferResponse", "properties": { "data": { "$ref": "#/components/schemas/Transfer" } } }, "examples": { "response": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "source": { "type": "wallet", "id": "12345", "identities": [ { "type": "individual", "name": "Satoshi Nakamoto", "addresses": [ { "line1": "100 Money Street", "line2": "Suite 1", "city": "Boston", "district": "MA", "postalCode": "01234", "country": "US" } ] } ] }, "destination": { "type": "blockchain", "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", "addressTag": "123456789", "chain": "ALGO" }, "amount": { "amount": "3.14", "currency": "USD" }, "fees": [ { "amount": "10.00", "currency": "USD", "type": "network" } ], "transactionHash": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63", "status": "pending", "errorCode": "transfer_failed", "createDate": "2020-04-10T02:13:30.000Z" } } } } } } } } }, "get": { "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "walletId", "description": "Filters results to get only transfers to or from this Circle wallet.", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sourceWalletId", "description": "Filters results to get only transfers from this Circle wallet.\n\nYou can get wallet IDs associated with your account using the [Core API for Institutions](/api-reference/circle-mint/institutional/get-all-external-entities).\n", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "destinationWalletId", "description": "Filters results to get only transfers to this Circle wallet.", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "$ref": "#/components/parameters/PageBefore" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageSize" } ], "summary": "List all transfers", "description": "Searches for transfers from your business account. If the date parameters are omitted, returns the most recent transfers. This endpoint returns up to 50 transfers in descending chronological order or pageSize, if provided.", "operationId": "listBusinessTransfers", "tags": ["Transfers"], "responses": { "200": { "description": "Successfully retrieved a list of transfers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "ListBusinessTransfersResponse", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transfer" } } } }, "examples": { "response": { "value": { "data": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "source": { "type": "wallet", "id": "12345", "identities": [ { "type": "individual", "name": "Satoshi Nakamoto", "addresses": [ { "line1": "100 Money Street", "line2": "Suite 1", "city": "Boston", "district": "MA", "postalCode": "01234", "country": "US" } ] } ] }, "destination": { "type": "blockchain", "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", "addressTag": "123456789", "chain": "ALGO" }, "amount": { "amount": "3.14", "currency": "USD" }, "fees": [ { "amount": "10.00", "currency": "USD", "type": "network" } ], "transactionHash": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63", "status": "pending", "errorCode": "transfer_failed", "createDate": "2020-04-10T02:13:30.000Z" } ] } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/v1/businessAccount/transfers/{id}": { "get": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "security": [ { "bearerAuth": [] } ], "summary": "Get a transfer", "operationId": "getBusinessTransfer", "tags": ["Transfers"], "responses": { "200": { "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "description": "Successfully retrieved a transfer.", "content": { "application/json": { "schema": { "title": "GetBusinessTransferResponse", "properties": { "data": { "$ref": "#/components/schemas/Transfer" } } }, "examples": { "response": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "source": { "type": "wallet", "id": "12345", "identities": [ { "type": "individual", "name": "Satoshi Nakamoto", "addresses": [ { "line1": "100 Money Street", "line2": "Suite 1", "city": "Boston", "district": "MA", "postalCode": "01234", "country": "US" } ] } ] }, "destination": { "type": "blockchain", "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", "addressTag": "123456789", "chain": "ALGO" }, "amount": { "amount": "3.14", "currency": "USD" }, "fees": [ { "amount": "10.00", "currency": "USD", "type": "network" } ], "transactionHash": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63", "status": "pending", "errorCode": "transfer_failed", "createDate": "2020-04-10T02:13:30.000Z" } } } } } } } } } }, "/v1/mocks/payments/wire": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Create a mock Wire payment", "description": "In the sandbox environment, initiate a mock wire payment that mimics the behavior of funds sent through the bank (wire) account linked to master wallet.", "operationId": "createMockWirePayment", "tags": ["Payments"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MockWirePaymentRequest" } } } }, "responses": { "201": { "description": "Successfully created a mock wire payment.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "CreateWirePaymentResponse", "properties": { "data": { "$ref": "#/components/schemas/MockWirePaymentResponse" } } }, "examples": { "response": { "value": { "data": { "trackingRef": "CIR13FB13A", "amount": { "amount": "3.14", "currency": "USD" }, "beneficiaryBank": { "accountNumber": "11111111" }, "status": "pending" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/v1/exchange/trades": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Create FX trade", "description": "Creates a cross-currency trade", "operationId": "createFxTrade", "tags": ["Trades"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxTradeRequest" } } } }, "responses": { "200": { "description": "Successfully created trade.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFxTradeResponse" }, "examples": { "response": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "from": { "amount": "3.14", "currency": "USDC" }, "to": { "amount": "3.14", "currency": "USDC" }, "status": "pending", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z", "quoteId": "b8627ae8-732b-4d25-b947-1df8f4007a29" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "security": [ { "bearerAuth": [] } ], "summary": "Get all FX trades", "description": "Returns all cross-currency trades. You can include an optional `settlementId` query parameter to filter the trades to only a specific settlement.", "operationId": "getFxTrades", "tags": ["Trades"], "parameters": [ { "$ref": "#/components/parameters/SettlementId" } ], "responses": { "200": { "description": "Successfully retrieved trades.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "GetFxTradesResponse", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Trade" } } } }, "examples": { "response": { "value": { "data": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "from": { "amount": "3.14", "currency": "USDC" }, "to": { "amount": "3.14", "currency": "USDC" }, "status": "pending", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z", "quoteId": "b8627ae8-732b-4d25-b947-1df8f4007a29", "settlementId": "b8627ae8-732b-4d25-b947-1df8f4007a29", "rate": 0.9039, "expectedBatchTime": "2020-04-10T02:13:30.000Z" } ] } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/exchange/trades/{id}": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "Get FX trade", "description": "Returns an FX trade by ID.", "operationId": "getFxTradeId", "tags": ["Trades"], "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Successfully retrieved trade.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "GetFxTradesResponse", "properties": { "data": { "$ref": "#/components/schemas/Trade" } } }, "examples": { "response": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "from": { "amount": "3.14", "currency": "USDC" }, "to": { "amount": "3.14", "currency": "USDC" }, "status": "pending", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z", "quoteId": "b8627ae8-732b-4d25-b947-1df8f4007a29", "settlementId": "b8627ae8-732b-4d25-b947-1df8f4007a29", "rate": 0.9039, "expectedBatchTime": "2020-04-10T02:13:30.000Z" } } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/exchange/trades/settlements": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "Get all settlements", "description": "Returns all settlements.", "operationId": "getSettlements", "tags": ["Settlements"], "parameters": [ { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "$ref": "#/components/parameters/PageBefore" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageSize" }, { "name": "type", "description": "The type of settlement.", "in": "query", "required": false, "schema": { "type": "string", "enum": ["account_payable", "account_receivable"] } }, { "name": "status", "description": "Status of the settlement.", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SettlementStatus" } }, { "name": "currency", "description": "Currency of the settlement", "in": "query", "required": false, "schema": { "type": "string", "enum": ["MXN", "BRL"] } } ], "responses": { "200": { "description": "Successfully retrieved settlements.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "GetSettlementsResponse", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Settlement" } } } }, "examples": { "response": { "value": { "data": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "entityId": "b8627ae8-732b-4d25-b947-1df8f4007a29", "status": "pending", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z", "details": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "payable", "amount": { "amount": "3.14", "currency": "USDC" }, "status": "pending", "reference": "FXR1234567", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } ] } ] } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/exchange/trades/settlements/{id}": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "Get settlement", "description": "Returns a settlement by ID.", "operationId": "getSettlementId", "tags": ["Settlements"], "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Successfully retrieved settlement.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "GetSettlementIdResponse", "properties": { "data": { "$ref": "#/components/schemas/Settlement" } } }, "examples": { "response": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "entityId": "b8627ae8-732b-4d25-b947-1df8f4007a29", "status": "pending", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z", "details": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "type": "payable", "amount": { "amount": "3.14", "currency": "USDC" }, "status": "pending", "reference": "FXR1234567", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } ] } } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/exchange/trades/settlements/instructions/{currency}": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "Get settlement instructions", "description": "Returns settlement instructions for a specific currency.", "operationId": "getSettlementInstructions", "tags": ["Settlements"], "parameters": [ { "$ref": "#/components/parameters/FxCurrencyPath" } ], "responses": { "200": { "description": "Successfully retrieved settlement instructions.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "GetSettlementInstructionsResponse", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/MXNSettlementInstructions" }, { "$ref": "#/components/schemas/BRLSettlementInstructions" } ] } } }, "examples": { "response": { "value": { "data": { "currency": "MXN", "fiatAccountType": "wire", "instruction": { "trackingRef": "CIR13FB13A", "beneficiary": { "name": "CIRCLE INTERNET FINANCIAL INC", "address1": "99 HIGH STREET", "address2": "BOSTON MA 02110" }, "beneficiaryBank": { "name": "WELLS FARGO BANK", "swiftCode": "WFBIUS6SXXX", "routingNumber": "121000248", "accountNumber": "****7427", "currency": "USD", "address": "4250 EXECUTIVE SQUARE SUITE 300", "city": "LA JOLLA", "postalCode": "02110", "country": "US" } } } } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/exchange/fxConfigs/accounts": { "put": { "security": [ { "bearerAuth": [] } ], "summary": "Create FX account", "description": "Creates a currency trading account", "operationId": "createFxAccount", "tags": ["Trades"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFxAccountRequest" } } } }, "responses": { "200": { "description": "Successfully created a currency trading account.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "CreateFxAccountResponse", "properties": { "data": { "$ref": "#/components/schemas/CreateFxAccountResponse" } } }, "examples": { "response": { "value": { "data": { "currency": "MXN", "fiatAccountId": "b8627ae8-732b-4d25-b947-1df8f4007a29", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/exchange/fxConfigs/dailyLimits": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "Get daily currency exchange limits", "description": "Returns daily currency exchange limits and usages.", "operationId": "getDailyFxLimits", "tags": ["Trades"], "responses": { "200": { "description": "Successfully retrieved daily FX limits.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "GetFxLimitsResponse", "properties": { "data": { "type": "object", "properties": { "dailyLimits": { "$ref": "#/components/schemas/DailyFxLimits" } } } } }, "examples": { "response": { "value": { "data": { "dailyLimits": { "EURC": { "limit": "1000000.00", "usage": "0.00", "available": "1000000.00" }, "MXN": { "limit": "1000000.00", "usage": "0.00", "available": "1000000.00" }, "USDC": { "limit": "1000000.00", "usage": "0.00", "available": "1000000.00" }, "BRL": { "limit": "1000000.00", "usage": "0.00", "available": "1000000.00" } } } } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/v1/mocks/payments/pix": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Create a mock PIX payment", "description": "Initiates a mock PIX payment in the sandbox environment that mimics the behavior of funds sent through the bank account linked to the main wallet.", "operationId": "createMockPixPayment", "tags": ["Payments"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MockPixPaymentRequest" } } } }, "responses": { "201": { "description": "Successfully created a mock PIX payment.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "CreatePixPaymentResponse", "properties": { "data": { "$ref": "#/components/schemas/MockPixPaymentResponse" } } }, "examples": { "response": { "value": { "data": { "trackingRef": "CIR13FB13A", "amount": { "amount": "3.14", "currency": "BRL" }, "beneficiaryAccountNumber": "4842622", "status": "pending" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/v2/reserveManagement/dailyCustodyBalances": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Create daily custody balance report", "operationId": "ReportDailyCustodyBalances", "description": "Creates a daily custody balance report for USDC and EURC and sends it to Circle.\n\n**Note:** Only one report is allowed per day per currency.\n", "tags": ["Reserve Management"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyCustodyBalancesRequest" } } } }, "responses": { "200": { "description": "Request with duplicate values and idempotency key has already been made. Existing record is returned.\n", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "DuplicateRequest", "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DailyCustodyBalancesResponse" } } }, "examples": { "response": { "value": { "data": { "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "createDate": "2025-07-15T18:03:52.429Z", "localBalance": 1000000, "currency": "USDC", "asOfDate": "2025-06-26", "reportType": "eea", "additionalFields": { "equivalentEuroLocalBalance": 26994.6, "totalBalance": 5000000, "equivalentEuroTotalBalance": 853949.09 } } } } } } } }, "201": { "description": "Successfully created daily custody balance report.\n", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "title": "NewReportSuccess", "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DailyCustodyBalancesResponse" } } }, "examples": { "response": { "value": { "data": { "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "createDate": "2025-07-15T18:03:52.429Z", "localBalance": 1000000, "currency": "USDC", "asOfDate": "2025-06-26", "reportType": "eea", "additionalFields": { "equivalentEuroLocalBalance": 26994.6, "totalBalance": 5000000, "equivalentEuroTotalBalance": 853949.09 } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/externalEntities": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Create an external entity", "description": "Creates an external entity for the institutional account.\n\nTo access the Core API for Institutions, contact your Circle account representative.\n", "operationId": "createExternalEntity", "tags": ["External Entities"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalEntityCreationRequest" } } } }, "responses": { "201": { "description": "Successfully created an external entity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalEntity" }, "examples": { "response": { "value": { "walletId": "212000", "businessName": "Circle Internet Financial Inc.", "businessUniqueIdentifier": "1234567890", "identifierIssuingCountryCode": "US", "complianceState": "PENDING" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "get": { "security": [ { "bearerAuth": [] } ], "summary": "Get all external entities", "description": "Returns all external entities for the institutional account.\n\nTo access the Core API for Institutions, contact your Circle account representative.\n\nNote that the `businessUniqueIdentifier` and `identifierIssuingCountryCode` must both be provided, or not at all. Only providing one will result in an error.\n", "operationId": "getAllExternalEntities", "tags": ["External Entities"], "parameters": [ { "name": "businessUniqueIdentifier", "description": "The unique identifier of the business. For example, a company number or tax ID.", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "identifierIssuingCountryCode", "description": "The country code of the issuing authority. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2.", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } } ], "responses": { "200": { "description": "Successfully retrieved a list of external entities.", "content": { "application/json": { "schema": { "title": "ListExternalEntitiesResponse", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalEntity" } } } }, "examples": { "response": { "value": { "data": [ { "walletId": "212000", "businessName": "Circle Internet Financial Inc.", "businessUniqueIdentifier": "1234567890", "identifierIssuingCountryCode": "US", "complianceState": "PENDING" } ] } } } } } } } } }, "/v1/externalEntities/{walletId}": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "Get an external entity by wallet ID", "description": "Returns an external entity by wallet ID.\n\nTo access the Core API for Institutions, contact your Circle account representative.\n", "operationId": "getExternalEntityByWalletId", "tags": ["External Entities"], "parameters": [ { "name": "walletId", "description": "The wallet ID of the external entity.", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved an external entity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalEntity" }, "examples": { "response": { "value": { "walletId": "212000", "businessName": "Circle Internet Financial Inc.", "businessUniqueIdentifier": "1234567890", "identifierIssuingCountryCode": "US", "complianceState": "PENDING" } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Ping": { "type": "object", "required": ["message"], "properties": { "message": { "type": "string", "example": "pong" } } }, "MerchantWalletId": { "type": "string", "description": "Unique system generated identifier for the wallet of the merchant.", "maxLength": 36, "example": "212000" }, "AccountConfiguration": { "type": "object", "properties": { "payments": { "title": "WalletConfig", "type": "object", "properties": { "masterWalletId": { "$ref": "#/components/schemas/MerchantWalletId" } } } } }, "Id": { "type": "string", "description": "Unique system generated identifier for the entity.", "format": "uuid", "example": "b8627ae8-732b-4d25-b947-1df8f4007a29" }, "SubscriptionDetail": { "type": "object", "properties": { "url": { "type": "string", "description": "Identifier for created subscription.", "example": "arn:aws:sns:us-east-1:<...>:fcb4a2c9-9c4f-4706-b312-6b22650f5d17" }, "status": { "type": "string", "description": "Status of the subscription request.", "enum": ["confirmed", "pending", "deleted"] } } }, "SubscriptionResponse": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "endpoint": { "type": "string", "description": "URL of the endpoint.", "example": "https://example.org/handler/for/notifications" }, "subscriptionDetails": { "type": "array", "description": "List of subscriptions details for created subscriptions.", "items": { "$ref": "#/components/schemas/SubscriptionDetail" } } } }, "SubscriptionRequest": { "type": "object", "required": ["endpoint"], "properties": { "endpoint": { "type": "string", "description": "URL of the subscriber endpoint. Must be publicly accessible and utilize HTTPS.", "example": "https://example.org/handler/for/notifications" } } }, "UnsubscribeResponse": { "type": "object", "description": "Unsubscribe response object. No fields as of now.", "example": {} }, "Chain": { "type": "string", "description": "A blockchain that a given currency is available on.", "enum": [ "ALGO", "APTOS", "ARB", "AVAX", "BASE", "BTC", "CELO", "CODEX", "ETH", "HBAR", "HYPEREVM", "INK", "LINEA", "NEAR", "NOBLE", "OP", "PLUME", "PAH", "POLY", "SEI", "SOL", "SONIC", "SUI", "UNI", "WORLDCHAIN", "XDC", "XLM", "XRP", "ZKS", "ZKSYNC" ] }, "TokenAmount": { "type": "object", "required": ["amount", "chain"], "properties": { "amount": { "type": "string", "description": "Magnitude of the amount, in units of the currency, with a `.`.", "example": "132.584192" }, "chain": { "$ref": "#/components/schemas/Chain" } } }, "Stablecoin": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the stablecoin.", "example": "USD Coin" }, "symbol": { "type": "string", "description": "Symbol of the stablecoin.", "example": "USDC" }, "totalAmount": { "type": "string", "description": "Total circulating amount of the stablecoin.", "example": "132.584192" }, "chains": { "type": "array", "description": "A list of the broken down totalAmount by chain of the stablecoin.", "items": { "$ref": "#/components/schemas/TokenAmount" } } } }, "Stablecoins": { "type": "array", "description": "A list of stablecoin objects containing its name, symbol, total amount, and per-chain amount.", "items": { "$ref": "#/components/schemas/Stablecoin" } }, "Money": { "type": "object", "required": ["amount", "currency"], "properties": { "amount": { "type": "string", "description": "Magnitude of the amount, in units of the currency, with a `.`.", "example": "3.14" }, "currency": { "type": "string", "description": "Currency code for the amount.", "enum": ["USD", "EUR", "BTC", "ETH"] } } }, "Balances": { "type": "object", "description": "Available and unsettled balances of the merchant.", "required": ["available", "unsettled"], "properties": { "available": { "type": "array", "description": "List of currency balances (one for each currency) that are currently available to spend.", "items": { "$ref": "#/components/schemas/Money" } }, "unsettled": { "type": "array", "description": "List of currency balances (one for each currency) that have been captured but are currently in the process of settling and will become available to spend at some point in the future.", "items": { "$ref": "#/components/schemas/Money" } } } }, "ExternalFiatAccountStatus": { "description": "Status of the account. A `pending` status indicates that the linking is in-progress; `complete` indicates the account was linked successfully; `failed` indicates it failed.", "type": "string", "enum": ["pending", "complete", "failed"] }, "FiatCurrency": { "type": "string", "description": "Currency code.", "title": "Currency", "enum": ["USD", "EUR", "MXN", "SGD", "BRL"] }, "TransferTypeInfo": { "type": "object", "required": ["currencies"], "description": "Additional information for specific transfer type.", "properties": { "currencies": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/FiatCurrency" } }, "additionalProperties": { "description": "Additional properties that apply to specific transfer type.", "type": "object", "properties": { "transactionLimits": { "type": "integer", "description": "Transaction amount limit for the transfer type.", "example": 100000 } } } } }, "Fingerprint": { "type": "string", "description": "A UUID that uniquely identifies the account number. If the same account is used more than once, each card object will have a different id, but the fingerprint will stay the same.", "example": "eb170539-9e1c-4e92-bf4f-1d09534fdca2" }, "BillingDetails": { "type": "object", "required": ["name", "city", "country", "line1", "postalCode"], "properties": { "name": { "type": "string", "description": "Full name of the card or bank account holder.", "maxLength": 1024, "example": "Satoshi Nakamoto" }, "city": { "type": "string", "description": "City portion of the address.", "maxLength": 1024, "example": "Boston" }, "country": { "type": "string", "description": "Country portion of the address. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2.", "maxLength": 2, "example": "US" }, "line1": { "type": "string", "description": "Line one of the street address.", "maxLength": 1024, "example": "100 Money Street" }, "line2": { "type": "string", "description": "Line two of the street address.", "maxLength": 1024, "example": "Suite 1" }, "district": { "description": "State / County / Province / Region portion of the address. If the country is US or Canada, then district is required and should use the two-letter code for the subdivision.", "type": "string", "maxLength": 16, "example": "MA" }, "postalCode": { "type": "string", "description": "Postal / ZIP code of the address.", "maxLength": 16, "example": "01234" } } }, "BankAddress": { "type": "object", "description": "The address details for the bank, as provided during bank account creation.", "required": ["country"], "properties": { "bankName": { "type": "string", "description": "Name of the bank. This property is required for bank accounts outside of the US that do not support IBAN'", "maxLength": 35, "example": "SAN FRANCISCO" }, "city": { "type": "string", "description": "City portion of the address. This property is required for bank accounts outside of the US.", "maxLength": 35, "example": "SAN FRANCISCO" }, "country": { "type": "string", "description": "Country portion of the address. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2.", "maxLength": 2, "example": "US" }, "line1": { "type": "string", "description": "Line one of the street address.", "maxLength": 35, "example": "100 Money Street" }, "line2": { "type": "string", "description": "Line two of the street address.", "maxLength": 35, "example": "Suite 1" }, "district": { "type": "string", "description": "State / County / Province / Region portion of the address. US and Canada use the two-letter code for the subdivision.", "maxLength": 16, "example": "CA" } } }, "UtcTimestamp": { "type": "string", "description": "ISO-8601 UTC date/time format.", "example": "2020-04-10T02:13:30.000Z" }, "Wire": { "type": "object", "required": [ "id", "status", "description", "trackingRef", "fingerprint", "billingDetails", "createDate", "updateDate" ], "properties": { "id": { "$ref": "#/components/schemas/Id" }, "type": { "type": "string", "description": "The type of the bank account.", "example": "wire" }, "status": { "$ref": "#/components/schemas/ExternalFiatAccountStatus" }, "description": { "type": "string", "description": "Bank name plus last four digits of the bank account number or IBAN.", "example": "WELLS FARGO BANK, NA ****0010" }, "trackingRef": { "type": "string", "description": "Wire tracking ref that needs to be set in the wire reference to beneficiary field.", "example": "CIR13FB13A" }, "transferTypesInfo": { "type": "object", "description": "A map which shows transfer types supported on this account as well as additional information for each.", "additionalProperties": { "$ref": "#/components/schemas/TransferTypeInfo" }, "example": { "wire": { "currencies": ["USD", "EUR"] }, "rtgs": { "currencies": ["USD"] } } }, "fingerprint": { "$ref": "#/components/schemas/Fingerprint" }, "billingDetails": { "$ref": "#/components/schemas/BillingDetails" }, "bankAddress": { "$ref": "#/components/schemas/BankAddress" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "virtualAccountEnabled": { "type": "boolean", "description": "Whether virtual account applies to the bank account.", "example": false } } }, "IdempotencyKey": { "type": "string", "description": "Universally unique identifier (UUID v4) idempotency key. This key is utilized to ensure exactly-once execution of mutating requests.", "format": "uuid", "example": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7" }, "WireCreationRequestUs": { "type": "object", "title": "US Bank Account", "description": "Relevant fields for U.S. bank accounts.", "required": [ "idempotencyKey", "accountNumber", "routingNumber", "billingDetails", "bankAddress" ], "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, "accountNumber": { "description": "Account number that identifies the bank account.", "type": "string", "example": "12340010", "minLength": 6, "maxLength": 35 }, "routingNumber": { "description": "ABA routing number for the bank account. Note this has to be specific for bank wire transfers.", "type": "string", "example": "121000248" }, "billingDetails": { "$ref": "#/components/schemas/BillingDetails" }, "bankAddress": { "$ref": "#/components/schemas/BankAddress" } } }, "BankAddressIbanSupported": { "type": "object", "description": "The address of the bank. City and country fields are required.", "required": ["city", "country"], "properties": { "bankName": { "type": "string", "description": "Name of the bank. This property is required for bank accounts outside of the US that do not support IBAN'", "maxLength": 35, "example": "SAN FRANCISCO" }, "city": { "type": "string", "description": "City portion of the address. This property is required for bank accounts outside of the US.", "maxLength": 1024, "example": "SAN FRANCISCO" }, "country": { "type": "string", "description": "Country portion of the address. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2.", "maxLength": 2, "example": "US" }, "line1": { "type": "string", "description": "Line one of the street address.", "maxLength": 35, "example": "100 Money Street" }, "line2": { "type": "string", "description": "Line two of the street address.", "maxLength": 35, "example": "Suite 1" }, "district": { "type": "string", "description": "State / County / Province / Region portion of the address. US and Canada use the two-letter code for the subdivision.", "maxLength": 16, "example": "CA" } } }, "WireCreationRequestIban": { "type": "object", "title": "Non US Bank Account - IBAN Supported", "description": "Relevant fields for non-U.S. bank accounts that support IBAN.", "required": ["idempotencyKey", "iban", "billingDetails", "bankAddress"], "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, "iban": { "description": "International Bank Account Number (IBAN) for the bank account.", "type": "string", "example": "DE31100400480532013000" }, "billingDetails": { "$ref": "#/components/schemas/BillingDetails" }, "bankAddress": { "$ref": "#/components/schemas/BankAddressIbanSupported" } } }, "BankAddressNonIban": { "type": "object", "description": "The address of the bank. BankName, City and Country fields are required.", "required": ["bankName", "city", "country"], "properties": { "bankName": { "type": "string", "description": "Name of the bank. This property is required for bank accounts outside of the US that do not support IBAN'", "maxLength": 35, "example": "SAN FRANCISCO" }, "city": { "type": "string", "description": "City portion of the address. This property is required for bank accounts outside of the US.", "maxLength": 1024, "example": "SAN FRANCISCO" }, "country": { "type": "string", "description": "Country portion of the address. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2.", "maxLength": 2, "example": "US" }, "line1": { "type": "string", "description": "Line one of the street address.", "maxLength": 35, "example": "100 Money Street" }, "line2": { "type": "string", "description": "Line two of the street address.", "maxLength": 35, "example": "Suite 1" }, "district": { "type": "string", "description": "State / County / Province / Region portion of the address. US and Canada use the two-letter code for the subdivision.", "maxLength": 16, "example": "CA" } } }, "WireCreationRequestAccountNumber": { "type": "object", "title": "Non US Bank Account - IBAN Not Supported", "description": "Relevant fields for non-U.S. banks that do NOT support IBAN.", "required": [ "idempotencyKey", "accountNumber", "routingNumber", "billingDetails", "bankAddress" ], "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, "accountNumber": { "description": "Account number that identifies the bank account.", "type": "string", "example": "0321800123", "minLength": 6, "maxLength": 35 }, "routingNumber": { "description": "The bank's SWIFT / BIC code.", "type": "string", "example": "SBININBB354" }, "billingDetails": { "$ref": "#/components/schemas/BillingDetails" }, "bankAddress": { "$ref": "#/components/schemas/BankAddressNonIban" } } }, "WireCreationRequest": { "type": "object", "description": "Request object used to create a bank account (wires). Different fields are required depending on the bank country, see the guide documentation for the list of supported bank countries along with which ones support IBAN.", "oneOf": [ { "$ref": "#/components/schemas/WireCreationRequestUs" }, { "$ref": "#/components/schemas/WireCreationRequestIban" }, { "$ref": "#/components/schemas/WireCreationRequestAccountNumber" } ] }, "WireInstructionBeneficiary": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the beneficiary.", "example": "CIRCLE INTERNET FINANCIAL INC" }, "address1": { "type": "string", "description": "Address line 1 of the beneficiary's address.", "example": "99 HIGH STREET" }, "address2": { "type": "string", "description": "Address line 2 of the beneficiary's address.", "example": "BOSTON MA 02110" } } }, "WireInstructionBeneficiaryBank": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the beneficiary's bank.", "example": "WELLS FARGO BANK" }, "swiftCode": { "type": "string", "description": "SWIFT code of the beneficiary's bank account.", "example": "WFBIUS6SXXX" }, "routingNumber": { "type": "string", "description": "ABA Routing number of the beneficiary's bank account.", "example": "121000248" }, "accountNumber": { "type": "string", "description": "Account number of the beneficiary's bank account.", "example": "****7427" }, "currency": { "type": "string", "description": "Currency of the beneficiary's bank account.", "example": "USD" }, "address": { "type": "string", "description": "Address of the beneficiary's bank.", "example": "4250 EXECUTIVE SQUARE SUITE 300" }, "city": { "type": "string", "description": "City of the beneficiary's bank.", "example": "LA JOLLA" }, "postalCode": { "type": "string", "description": "Postal code of the beneficiary's bank.", "example": "02110" }, "country": { "type": "string", "description": "Country code of the beneficiary's bank. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2.", "example": "US" } } }, "WireInstruction": { "type": "object", "properties": { "trackingRef": { "type": "string", "description": "Circle tracking reference that needs to be set in the wire reference field.", "example": "CIR13FB13A" }, "beneficiary": { "$ref": "#/components/schemas/WireInstructionBeneficiary" }, "beneficiaryBank": { "$ref": "#/components/schemas/WireInstructionBeneficiaryBank" } } }, "CubixFiatAccountResponse": { "type": "object", "required": [ "id", "status", "trackingRef", "accountId", "createDate", "updateDate", "transferTypesInfo" ], "properties": { "id": { "$ref": "#/components/schemas/Id" }, "status": { "$ref": "#/components/schemas/ExternalFiatAccountStatus" }, "trackingRef": { "type": "string", "description": "Tracking ref that needs to be set in the public description field when you send the funds to Circle's CUBIX account.", "example": "CIR25XSXT8" }, "accountId": { "type": "string", "format": "uuid", "description": "Your CUBIX Account ID.", "example": "ff2212d7-8476-4d1e-9d95-eda6455f4f54" }, "transferTypesInfo": { "type": "object", "description": "A map which shows transfer types supported on this account as well as additional information for each. For CUBIX accounts this will always only show information for CUBIX transfers.", "additionalProperties": { "$ref": "#/components/schemas/TransferTypeInfo" }, "example": { "cubix": { "currencies": ["USD"] } } }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" } } }, "CubixFiatAccountCreationRequest": { "type": "object", "required": ["idempotencyKey", "accountId"], "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, "accountId": { "type": "string", "format": "uuid", "description": "Cubix Account ID.", "example": "ff2212d7-8476-4d1e-9d95-eda6455f4f54" } } }, "CubixInstruction": { "type": "object", "properties": { "trackingRef": { "type": "string", "description": "Circle tracking reference that needs to be set in the CUBIX public memo field.", "example": "CIR25XSXT8" }, "accountId": { "type": "string", "format": "uuid", "description": "Circle account ID that needs to be set in the CUBIX account ID field.", "example": "ff2212d7-8476-4d1e-9d95-eda6455f4f54" } } }, "RiskEvaluation": { "type": "object", "description": "Results of risk evaluation. Only present if the payment is denied by Circle's risk service.", "nullable": true, "properties": { "decision": { "description": "Enumerated decision of the account.", "type": "string", "enum": ["approved", "denied", "review"] }, "reason": { "description": "Risk reason for the definitive decision outcome.", "type": "string", "nullable": true, "example": "3000" } } }, "PixFiatAccountResponse": { "type": "object", "required": [ "id", "status", "description", "trackingRef", "fingerprint", "createDate", "updateDate", "transferTypesInfo" ], "properties": { "id": { "$ref": "#/components/schemas/Id" }, "status": { "$ref": "#/components/schemas/ExternalFiatAccountStatus" }, "description": { "type": "string", "description": "Bank name plus last four digits of the PIX account number.", "example": "BTG Pactual ****0010" }, "trackingRef": { "type": "string", "description": "Wire tracking ref that needs to be set in the wire reference to beneficiary field.", "example": "CIR13FB13A" }, "transferTypesInfo": { "type": "object", "description": "A map which shows transfer types supported on this account as well as additional information for each. For PIX accounts this will always only show information for PIX transfers.", "additionalProperties": { "$ref": "#/components/schemas/TransferTypeInfo" }, "example": { "pix": { "currencies": ["BRL"] } } }, "riskEvaluation": { "$ref": "#/components/schemas/RiskEvaluation" }, "fingerprint": { "$ref": "#/components/schemas/Fingerprint" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" } } }, "PixAccountType": { "type": "string", "title": "Account type", "description": "Beneficiary account type.", "enum": ["checking", "savings", "salary", "prepaid"], "example": "checking" }, "PixFiatAccountCreationRequest": { "type": "object", "required": [ "idempotencyKey", "name", "accountNumber", "ispb", "branchCode", "taxId", "accountType" ], "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, "name": { "type": "string", "description": "Name of the beneficiary.", "example": "CIRCLE INTERNET FINANCIAL INC" }, "accountNumber": { "type": "string", "description": "Beneficiary account number.", "example": "322286803" }, "ispb": { "type": "string", "description": "Beneficiary ISPB.", "example": "68033222" }, "branchCode": { "type": "string", "description": "Beneficiary account branch code.", "example": "123" }, "taxId": { "type": "string", "description": "Beneficiary Tax ID.", "example": "57112345675712" }, "accountType": { "$ref": "#/components/schemas/PixAccountType" } } }, "PixInstruction": { "type": "object", "properties": { "trackingRef": { "type": "string", "description": "Circle tracking reference that needs to be set in the PIX reference field.", "example": "CIR25XSXT8" }, "ispb": { "type": "string", "description": "ISPB of beneficiary's bank.", "example": "68033222" }, "branchCode": { "type": "string", "description": "Beneficiary account branch code.", "example": "123" }, "accountNumber": { "type": "string", "description": "Beneficiary account number.", "example": "322286803" }, "accountType": { "$ref": "#/components/schemas/PixAccountType" }, "taxId": { "type": "string", "description": "Beneficiary Tax ID.", "example": "57112345675712" }, "name": { "type": "string", "description": "Name of the beneficiary.", "example": "CIRCLE INTERNET FINANCIAL INC" } } }, "Address": { "type": "string", "description": "An alphanumeric string representing a blockchain address. Formatting varies by blockchain.\nBe sure to preserve the exact formatting and capitalization of the address. \n**Important:** For Ripple (XRP) addresses, only the classic address format is supported (for example, `rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY`). \nThe `x-address` format is NOT supported currently (for example, `XV5sbjUmgPpvXv4ixFWZ5ptAYZ6PD2q1qM6owqNbug8W6KV`).\n", "example": "0x8381470ED67C3802402dbbFa0058E8871F017A6F" }, "AddressTag": { "type": "string", "description": "The secondary identifier for a blockchain address. An example of this is the memo field on the Stellar network, which can be text, id, or hash format.", "nullable": true, "example": "123456789" }, "Currency": { "type": "string", "description": "A currency associated with a balance or address.", "nullable": true, "enum": ["USD", "EUR", "BTC", "ETH"] }, "AddressObject": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/Address" }, "addressTag": { "$ref": "#/components/schemas/AddressTag" }, "currency": { "$ref": "#/components/schemas/Currency" }, "chain": { "$ref": "#/components/schemas/Chain" }, "id": { "description": "Unique identifier of the deposit address.", "$ref": "#/components/schemas/Id" }, "walletId": { "type": "string", "description": "Unique identifier of the wallet to which the deposit address is associated.", "example": "1000999922" } } }, "BusinessGenerateAddressRequest": { "type": "object", "required": ["idempotencyKey", "currency", "chain"], "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, "currency": { "$ref": "#/components/schemas/Currency" }, "chain": { "$ref": "#/components/schemas/Chain" } } }, "AddressDescription": { "type": "string", "description": "An identifier or sentence that describes the recipient.", "example": "My USDC address at a cryptocurrency exchange" }, "BusinessRecipientAddressObject": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "address": { "$ref": "#/components/schemas/Address" }, "addressTag": { "$ref": "#/components/schemas/AddressTag" }, "chain": { "$ref": "#/components/schemas/Chain" }, "currency": { "$ref": "#/components/schemas/Currency" }, "description": { "$ref": "#/components/schemas/AddressDescription" }, "status": { "type": "string", "enum": ["active", "pending_verification", "verification_succeeded"] } } }, "BusinessRecipientAddressCreationRequest": { "type": "object", "description": "Adds a recipient address. The currency parameter will default to USD for all chains except for BTC where it defaults to BTC.", "required": ["idempotencyKey", "address", "chain", "description"], "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, "address": { "$ref": "#/components/schemas/Address" }, "addressTag": { "$ref": "#/components/schemas/AddressTag" }, "chain": { "$ref": "#/components/schemas/Chain" }, "currency": { "$ref": "#/components/schemas/Currency" }, "description": { "$ref": "#/components/schemas/AddressDescription" } } }, "WalletLocation": { "type": "object", "required": ["type", "id"], "properties": { "type": { "type": "string", "enum": ["wallet"] }, "id": { "type": "string", "description": "The id of the wallet.", "example": "12345" } } }, "FiatMoney": { "type": "object", "required": ["amount", "currency"], "properties": { "amount": { "description": "Magnitude of the amount, in units of the currency, with a `.`.", "type": "string", "example": "3.14" }, "currency": { "$ref": "#/components/schemas/FiatCurrency" } } }, "FiatMoneyUsd": { "type": "object", "required": ["amount", "currency"], "properties": { "amount": { "description": "Magnitude of the amount, in units of the currency, with a `.`.", "type": "string", "example": "3.14" }, "currency": { "description": "Currency code.", "type": "string", "enum": ["USD"] } } }, "InstitutionalCustomerExternalRef": { "type": "string", "description": "A reference to the external customer which is in the memo field of the fiat transfer.", "pattern": "^(EXT[A-Z0-9]{18}).$", "example": "EXT01ABSJKDKASJHDS922" }, "WireDestinationResponse": { "type": "object", "required": ["type", "id"], "properties": { "type": { "type": "string", "enum": ["wire"] }, "id": { "$ref": "#/components/schemas/Id" }, "name": { "type": "string", "description": "Bank name plus last four digits of the bank account number or IBAN.", "example": "COMMERZBANK AG ****3000" } } }, "BusinessDeposit": { "type": "object", "description": "A deposit", "required": ["id", "destination", "amount", "status", "createDate"], "properties": { "id": { "$ref": "#/components/schemas/Id" }, "sourceWalletId": { "type": "string", "description": "The identifier for the bank account where the funds were deposited from.", "format": "uuid", "example": "9b57048d-2365-4ff5-956b-0199170d1035" }, "destination": { "$ref": "#/components/schemas/WalletLocation" }, "amount": { "$ref": "#/components/schemas/FiatMoney" }, "fee": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "status": { "type": "string", "description": "Status of the deposit. Status `pending` indicates that the deposit is in the process of running; `complete` indicates it finished successfully; `failed` indicates it failed.", "enum": ["pending", "complete", "failed"] }, "riskEvaluation": { "$ref": "#/components/schemas/RiskEvaluation" }, "customerExternalRef": { "$ref": "#/components/schemas/InstitutionalCustomerExternalRef" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "source": { "$ref": "#/components/schemas/WireDestinationResponse" }, "fromAmount": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "fees": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "externalRef": { "description": "The external reference associated with the deposit.", "$ref": "#/components/schemas/Id" }, "trackingRef": { "type": "string", "description": "Tracking reference used for making the deposit.", "example": "CIR37N5FXJ" } } }, "CryptoPaymentsMoney": { "type": "object", "required": ["amount", "currency"], "properties": { "amount": { "description": "Magnitude of the amount, in units of the currency, with a `.`.", "type": "string", "example": "3.14" }, "currency": { "description": "Currency code.", "type": "string", "enum": ["USD", "EUR", "ETH", "BTC"] } } }, "PaymentMethodBlockchain": { "type": "object", "required": ["type", "chain"], "properties": { "type": { "type": "string", "enum": ["blockchain"] }, "chain": { "type": "string", "description": "The blockchain network for the payment.", "enum": [ "ALGO", "ARB", "AVAX", "BASE", "BTC", "ETH", "HBAR", "NOBLE", "OP", "POLY", "SOL", "SUI", "XLM" ] }, "address": { "type": "string", "example": "0x8381470ED67C3802402dbbFa0058E8871F017A6F" } } }, "PaymentIntentFees": { "type": "object", "required": ["type", "amount", "currency"], "properties": { "type": { "type": "string", "enum": ["blockchainLeaseFee", "totalPaymentFees"] }, "amount": { "description": "Magnitude of the amount, in units of the currency, with a `.`.", "type": "string", "example": "3.14" }, "currency": { "description": "Currency code.", "type": "string", "enum": ["USD", "BTC", "ETH"] } } }, "Timeline": { "type": "object", "required": ["status", "time"], "properties": { "status": { "type": "string", "enum": [ "created", "pending", "complete", "expired", "failed", "refunded" ] }, "context": { "type": "string", "enum": ["underpaid", "paid", "overpaid"] }, "reason": { "type": "string", "enum": ["requested_by_merchant", "fee_collection_failed"] }, "time": { "description": "ISO-8601 UTC date/time format.", "type": "string", "format": "date-time" } } }, "PaymentIntent": { "type": "object", "required": ["amount", "settlementCurrency", "paymentMethods"], "properties": { "id": { "type": "string", "description": "Unique system generated identifier for the entity.", "format": "uuid", "example": "b8627ae8-732b-4d25-b947-1df8f4007a29" }, "amount": { "$ref": "#/components/schemas/CryptoPaymentsMoney" }, "amountPaid": { "$ref": "#/components/schemas/CryptoPaymentsMoney" }, "amountRefunded": { "$ref": "#/components/schemas/CryptoPaymentsMoney" }, "settlementCurrency": { "description": "Desired currency for the payments to settle in.", "type": "string", "enum": ["USD", "BTC", "ETH"] }, "paymentMethods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethodBlockchain" } }, "fees": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentIntentFees" } }, "paymentIds": { "description": "List of associated payments.", "type": "array", "items": { "type": "string", "format": "uuid", "example": "69808f36-3e5e-4f37-bf82-ca79e4d70fc1" } }, "refundIds": { "description": "List of associated refunds.", "type": "array", "items": { "type": "string", "format": "uuid", "example": "425dca6d-ac79-43b6-b0f9-43fdc51de91b" } }, "timeline": { "description": "State management timeline.", "type": "array", "items": { "$ref": "#/components/schemas/Timeline" } }, "expiresOn": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "merchantWalletId": { "$ref": "#/components/schemas/MerchantWalletId" } } }, "ContinuousPaymentIntent": { "type": "object", "required": [ "currency", "settlementCurrency", "paymentMethods", "type" ], "properties": { "id": { "$ref": "#/components/schemas/Id" }, "currency": { "description": "Desired currency of the payment.", "type": "string", "enum": ["USD", "BTC", "ETH"] }, "amountPaid": { "$ref": "#/components/schemas/CryptoPaymentsMoney" }, "amountRefunded": { "$ref": "#/components/schemas/CryptoPaymentsMoney" }, "settlementCurrency": { "description": "Desired currency for the payments to settle in.", "type": "string", "enum": ["USD", "BTC", "ETH"] }, "paymentMethods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethodBlockchain" } }, "fees": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentIntentFees" } }, "timeline": { "description": "State management timeline.", "type": "array", "items": { "$ref": "#/components/schemas/Timeline" } }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "type": { "type": "string", "enum": ["continuous"] }, "merchantWalletId": { "$ref": "#/components/schemas/MerchantWalletId" } } }, "PaymentIntentCreationRequest": { "type": "object", "required": [ "idempotencyKey", "amount", "settlementCurrency", "paymentMethods" ], "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, "amount": { "$ref": "#/components/schemas/CryptoPaymentsMoney" }, "settlementCurrency": { "description": "Desired currency for the payments to settle in. This must match the currency used for the payment method.", "type": "string", "enum": ["USD", "EUR", "BTC", "ETH"] }, "paymentMethods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethodBlockchain" } }, "merchantWalletId": { "$ref": "#/components/schemas/MerchantWalletId" } } }, "PaymentMethodBlockchainRequest": { "type": "object", "required": ["type", "chain"], "properties": { "type": { "type": "string", "enum": ["blockchain"] }, "chain": { "$ref": "#/components/schemas/Chain" } } }, "ContinuousPaymentIntentCreationRequest": { "type": "object", "required": [ "idempotencyKey", "currency", "settlementCurrency", "paymentMethods", "merchantWalletId" ], "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, "currency": { "description": "Desired currency for the payment", "type": "string", "enum": ["USD", "EUR", "BTC", "ETH"] }, "settlementCurrency": { "description": "Desired currency for the payments to settle in. This must match the currency used for the payment.", "type": "string", "enum": ["USD", "EUR", "BTC", "ETH"] }, "paymentMethods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethodBlockchainRequest" } }, "merchantWalletId": { "$ref": "#/components/schemas/MerchantWalletId" }, "type": { "type": "string", "enum": ["continuous"] } } }, "CryptoRefundDestination": { "type": "object", "description": "The destination of a crypto refund.", "required": ["address", "chain"], "properties": { "address": { "type": "string", "description": "The blockchain address.", "example": "0x8381470ED67C3802402dbbFa0058E8871F017A6F" }, "addressTag": { "$ref": "#/components/schemas/AddressTag" }, "chain": { "$ref": "#/components/schemas/Chain" } } }, "CryptoRefundCreationRequest": { "type": "object", "required": ["idempotencyKey", "destination", "amount", "toAmount"], "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, "destination": { "$ref": "#/components/schemas/CryptoRefundDestination" }, "amount": { "type": "object", "description": "The source amount of the refund, it can be in either the original payment currency or the settlement currency.", "required": ["currency"], "properties": { "currency": { "description": "Currency code.", "type": "string", "enum": ["USD", "ETH", "BTC"] } } }, "toAmount": { "type": "object", "description": "The destination amount of the refund, it must be in the original payment currency.", "required": ["amount", "currency"], "properties": { "amount": { "description": "Magnitude of the amount, in units of the currency, with a `.`.", "type": "string", "example": "3.14" }, "currency": { "description": "Currency code.", "type": "string", "enum": ["USD", "ETH", "BTC"] } } } } }, "IdMerchant": { "type": "string", "description": "Unique system generated identifier for the merchant.", "format": "uuid", "example": "fc988ed5-c129-4f70-a064-e5beb7eb8e32" }, "CryptoPaymentsOptionalAmountMoney": { "type": "object", "required": ["currency"], "properties": { "amount": { "description": "Magnitude of the amount, in units of the currency, with a `.`.", "type": "string", "example": "3.14" }, "currency": { "description": "Currency code.", "type": "string", "enum": ["USD", "ETH", "BTC"] } } }, "PaymentStatus": { "type": "string", "description": "Enumerated status of the payment. `pending` means the payment is waiting to be processed. `confirmed` means the payment has been approved by the bank and the merchant can treat it as successful, but settlement funds are not yet available to the merchant. `paid` means settlement funds have been received and are available to the merchant. `failed` means something went wrong (most commonly that the payment was denied). `action_required` means that additional steps are required to process this payment; refer to `requiredAction` for more details. Terminal states are `paid` and `failed`.", "enum": ["pending", "confirmed", "paid", "failed", "action_required"] }, "CryptoPaymentNetworkFee": { "type": "object", "required": ["amount", "currency"], "properties": { "amount": { "type": "string", "description": "Magnitude of the amount, in units of the currency, with a `.`.", "example": "3.14" }, "currency": { "type": "string", "description": "Currency code for the amount.", "enum": ["USD", "EUR", "BTC", "ETH"] }, "feePayer": { "type": "string", "description": "The party that pays the network fee based on merchant configuration.", "enum": ["endUser", "merchant"] } } }, "CryptoPayment": { "type": "object", "description": "Status information of the related payment.", "required": ["id", "type", "merchantId", "amount", "status"], "properties": { "id": { "$ref": "#/components/schemas/Id" }, "type": { "description": "Type of the payment object.", "type": "string", "enum": ["payment", "refund"] }, "merchantId": { "$ref": "#/components/schemas/IdMerchant" }, "merchantWalletId": { "$ref": "#/components/schemas/MerchantWalletId" }, "amount": { "$ref": "#/components/schemas/CryptoPaymentsOptionalAmountMoney" }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "fees": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "networkFees": { "$ref": "#/components/schemas/CryptoPaymentNetworkFee" }, "paymentIntentId": { "type": "string", "format": "uuid", "example": "6e4d4047-db14-4c09-b238-1215aee50d03" }, "settlementAmount": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "fromAddresses": { "type": "object", "properties": { "chain": { "$ref": "#/components/schemas/Chain" }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } } } }, "depositAddress": { "type": "object", "properties": { "chain": { "$ref": "#/components/schemas/Chain" }, "address": { "type": "string", "example": "0x97de855690955e0da79ce5c1b6804847e7070c7f" }, "addressTag": { "$ref": "#/components/schemas/AddressTag" } } }, "transactionHash": { "type": "string", "example": "0x7351585460bd657f320b9afa02a52c26d89272d0d10cc29913eb8b28e64fd906" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "riskEvaluation": { "$ref": "#/components/schemas/RiskEvaluation" } } }, "Email": { "type": "string", "description": "Email of the user.", "maxLength": 1024, "example": "satoshi@circle.com" }, "AddressBookRecipientMetadata": { "type": "object", "properties": { "nickname": { "type": "string", "description": "Nickname related to the address.", "example": "sample nickname" }, "email": { "$ref": "#/components/schemas/Email" }, "bns": { "type": "string", "description": "Blockchain Name Service (e.g. ENS) domain for the address.", "example": "sample.circle" } } }, "AddressBookRecipient": { "type": "object", "required": ["chain", "address", "metadata"], "properties": { "id": { "$ref": "#/components/schemas/Id" }, "chain": { "$ref": "#/components/schemas/Chain" }, "address": { "$ref": "#/components/schemas/Address" }, "addressTag": { "$ref": "#/components/schemas/AddressTag" }, "metadata": { "$ref": "#/components/schemas/AddressBookRecipientMetadata" }, "status": { "type": "string", "description": "Status of the address book recipient.", "enum": ["pending", "inactive", "active", "denied"] }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" } } }, "AddressBookRecipientRequest": { "type": "object", "required": ["idempotencyKey", "chain", "address", "metadata"], "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, "chain": { "type": "string", "description": "The blockchain network to use for the address.", "enum": [ "ALGO", "APTOS", "ARB", "AVAX", "BASE", "CELO", "ETH", "HBAR", "NEAR", "NOBLE", "OP", "PAH", "POLY", "SOL", "SUI", "UNI", "XLM", "XRP", "ZKS" ] }, "address": { "$ref": "#/components/schemas/Address" }, "addressTag": { "$ref": "#/components/schemas/AddressTag" }, "metadata": { "$ref": "#/components/schemas/AddressBookRecipientMetadata" } } }, "AddressBookRecipientModifyRequest": { "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/AddressBookRecipientMetadata" } } }, "SourceResponse": { "type": "object", "description": "The payment source.", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "type": { "type": "string", "description": "Type of the source.", "enum": ["card", "ach", "wire", "sepa"] } } }, "RequiredAction": { "type": "object", "description": "When the payment status is `action_required`, this object summarizes the required additional steps.", "required": ["type", "redirectUrl"], "properties": { "type": { "type": "string", "description": "The type of action that is required to proceed with the payment. Currently only one type is supported.", "enum": ["three_d_secure_required"] }, "redirectUrl": { "type": "string", "description": "The URL to bring the user to in order to complete the payment.", "example": "https://example.org" } } }, "CancelRefundReversalStatus": { "type": "string", "enum": ["pending", "confirmed", "paid", "failed"], "description": "Enumerated status of the payment. `pending` means the payment is waiting to be processed. `confirmed` means the payment has been approved by the bank and the merchant can treat it as successful, but settlement funds are not yet available to the merchant. `paid` means settlement funds have been received and are available to the merchant. `failed` means something went wrong (most commonly that the payment was denied). Terminal states are `paid` and `failed`." }, "PaymentInfoCancel": { "type": "object", "description": "Status information of the related cancel. This property is only present on canceled payment or refund items.", "nullable": true, "properties": { "id": { "$ref": "#/components/schemas/Id" }, "type": { "type": "string", "description": "Type of the payment object.", "enum": ["cancel"] }, "description": { "description": "Enumerated description of the payment item.", "type": "string", "nullable": true, "enum": ["Payment"] }, "status": { "$ref": "#/components/schemas/CancelRefundReversalStatus" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" } } }, "PaymentInfoPaymentAndRefund": { "type": "object", "description": "Status information of the related payment. This property is only present on refund or cancel items.", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "type": { "type": "string", "description": "Type of the payment object.", "enum": ["payment", "refund"] }, "amount": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "description": { "type": "string", "description": "Enumerated description of the payment item.", "nullable": true, "enum": ["Payment"] }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "requiredAction": { "$ref": "#/components/schemas/RequiredAction" }, "fees": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" } } }, "Channel": { "type": "string", "format": "uuid", "description": "The channel identifier that can be set for the payment. When not provided, the default channel is used.", "example": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7" }, "FiatPayment": { "type": "object", "description": "Status information of the related payment. This property is only present on refund or cancel items.", "required": ["id", "type", "merchantId", "amount", "source", "status"], "properties": { "id": { "$ref": "#/components/schemas/Id" }, "type": { "description": "Type of the payment object.", "type": "string", "enum": ["payment"] }, "merchantId": { "$ref": "#/components/schemas/IdMerchant" }, "merchantWalletId": { "$ref": "#/components/schemas/MerchantWalletId" }, "amount": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "fromAmount": { "$ref": "#/components/schemas/FiatMoney" }, "source": { "$ref": "#/components/schemas/SourceResponse" }, "description": { "description": "Enumerated description of the payment.", "type": "string", "enum": ["Payment"] }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "captured": { "description": "Determines if a payment has successfully been captured. This property is only present for payments that did not use auto capture.", "type": "boolean" }, "captureAmount": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "captureDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "requiredAction": { "$ref": "#/components/schemas/RequiredAction" }, "cancel": { "$ref": "#/components/schemas/PaymentInfoCancel" }, "refunds": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentInfoPaymentAndRefund" } }, "fees": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "channel": { "$ref": "#/components/schemas/Channel" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" } } }, "FiatCancel": { "type": "object", "description": "Status information of the related cancel. This property is only present on canceled payment or refund items.", "nullable": true, "required": ["id", "type", "merchantId", "amount", "source", "status"], "properties": { "id": { "$ref": "#/components/schemas/Id" }, "type": { "type": "string", "description": "Type of the payment object.", "enum": ["cancel"] }, "merchantId": { "$ref": "#/components/schemas/IdMerchant" }, "merchantWalletId": { "$ref": "#/components/schemas/MerchantWalletId" }, "amount": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "source": { "$ref": "#/components/schemas/SourceResponse" }, "description": { "description": "Enumerated description of the payment.", "type": "string", "enum": ["Payment"] }, "status": { "$ref": "#/components/schemas/CancelRefundReversalStatus" }, "originalPayment": { "$ref": "#/components/schemas/PaymentInfoPaymentAndRefund" }, "fees": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "channel": { "$ref": "#/components/schemas/Channel" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" } } }, "FiatRefund": { "type": "object", "required": ["id", "type", "merchantId", "amount", "source", "status"], "properties": { "id": { "$ref": "#/components/schemas/Id" }, "type": { "description": "Type of the payment object.", "type": "string", "enum": ["refund"] }, "merchantId": { "$ref": "#/components/schemas/IdMerchant" }, "merchantWalletId": { "$ref": "#/components/schemas/MerchantWalletId" }, "amount": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "source": { "$ref": "#/components/schemas/SourceResponse" }, "description": { "description": "Enumerated description of the payment.", "type": "string", "enum": ["Payment"] }, "status": { "$ref": "#/components/schemas/CancelRefundReversalStatus" }, "originalPayment": { "$ref": "#/components/schemas/PaymentInfoPaymentAndRefund" }, "cancel": { "$ref": "#/components/schemas/PaymentInfoCancel" }, "fees": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "channel": { "$ref": "#/components/schemas/Channel" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" } } }, "AvsResults": { "type": "string", "description": "Status of the AVS check. Raw AVS response, expressed as an upper-case letter. `not_requested` indicates check was not made. `pending` is pending/processing.", "example": "D" }, "CvvResults": { "description": "Enumerated status of the check. `not_requested` indicates check was not made. `pass` indicates value is correct. `fail` indicates value is incorrect. `unavailable` indicates card issuer did not do the provided check. `pending` indicates check is pending/processing.", "type": "string", "enum": ["not_requested", "pass", "fail", "unavailable", "pending"] }, "ThreeDsResult": { "type": "string", "description": "Enumerated status of the check. `pass` indicates successful 3DS authentication. `fail` indicates failed 3DS authentication.", "enum": ["pass", "fail"] }, "Eci": { "type": "string", "description": "ECI (electronic commerce indicator) value returned by Directory Servers (namely Visa, MasterCard, JCB, and American Express) indicating the outcome of authentication attempted on transactions enforced by 3DS.", "enum": ["00", "01", "02", "05", "06", "07"] }, "PaymentVerificationResponse": { "type": "object", "description": "Indicates the status of the payment verification. This property will be present once the payment is confirmed.", "required": ["avs", "cvv"], "properties": { "avs": { "$ref": "#/components/schemas/AvsResults" }, "cvv": { "$ref": "#/components/schemas/CvvResults" }, "threeDSecure": { "$ref": "#/components/schemas/ThreeDsResult" }, "eci": { "$ref": "#/components/schemas/Eci" } } }, "ExternalRef": { "type": "string", "description": "External network identifier which will be present once provided from the applicable network. \n\nExamples:\n* **Input/Output Message Accountability Data (IMAD/OMAD)**: unique number given to each FedWire payment when using the Federal Reserve Bank Service which can be used to investigate and track wire transfers.\n", "example": "YYYYMMDDXXXXXXXX012345" }, "PaymentErrorCode": { "type": "string", "description": "Indicates the failure reason of a payment. Only present for payments in failed state. Possible values are [`payment_failed`, `payment_fraud_detected`, `payment_denied`, `payment_not_supported_by_issuer`, `payment_not_funded`, `payment_unprocessable`, `payment_stopped_by_issuer`, `payment_canceled`, `payment_returned`, `payment_failed_balance_check`, `card_failed`, `card_invalid`, `card_address_mismatch`, `card_zip_mismatch`, `card_cvv_invalid`, `card_expired`, `card_limit_violated`, `card_not_honored`, `card_cvv_required`, `credit_card_not_allowed`, `card_account_ineligible`, `card_network_unsupported`, `channel_invalid`, `unauthorized_transaction`, `bank_account_ineligible`, `bank_transaction_error`, `invalid_account_number`, `invalid_wire_rtn`, `invalid_ach_rtn`, `vendor_inactive`]'", "nullable": true, "enum": [ "payment_failed", "payment_fraud_detected", "payment_denied", "payment_not_supported_by_issuer", "payment_not_funded", "payment_unprocessable", "payment_stopped_by_issuer", "payment_canceled", "payment_returned", "payment_failed_balance_check", "card_failed", "card_invalid", "card_address_mismatch", "card_zip_mismatch", "card_cvv_invalid", "card_expired", "card_limit_violated", "card_not_honored", "card_cvv_required", "card_restricted,", "card_account_ineligible", "card_network_unsupported", "channel_invalid", "unauthorized_transaction", "bank_account_ineligible", "bank_transaction_error", "invalid_account_number", "invalid_wire_rtn", "invalid_ach_rtn", "ref_id_invalid", "account_name_mismatch", "account_number_mismatch", "account_ineligible", "wallet_address_mismatch", "customer_name_mismatch", "institution_name_mismatch", "vendor_inactive" ] }, "PhoneNumber": { "type": "string", "description": "Phone number of the user in E.164 format. We recommend using a library such as [libphonenumber](https://github.com/google/libphonenumber) to parse and validate phone numbers.", "maxLength": 16, "pattern": "/\\+?[1-9]\\d{1,14}/", "example": "+14155555555" }, "MetadataPhoneEmail": { "type": "object", "required": ["email"], "properties": { "email": { "$ref": "#/components/schemas/Email" }, "phoneNumber": { "$ref": "#/components/schemas/PhoneNumber" } } }, "FiatPaymentPolymorphic": { "type": "object", "required": ["id", "type", "merchantId", "amount", "source", "status"], "properties": { "id": { "$ref": "#/components/schemas/Id" }, "type": { "description": "Type of the payment object.", "type": "string", "enum": ["payment", "refund", "cancel"] }, "merchantId": { "$ref": "#/components/schemas/IdMerchant" }, "merchantWalletId": { "$ref": "#/components/schemas/MerchantWalletId" }, "amount": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "fromAmount": { "$ref": "#/components/schemas/FiatMoney" }, "source": { "$ref": "#/components/schemas/SourceResponse" }, "description": { "description": "Enumerated description of the payment.", "type": "string", "enum": ["Payment"] }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "requiredAction": { "$ref": "#/components/schemas/RequiredAction" }, "verification": { "$ref": "#/components/schemas/PaymentVerificationResponse" }, "originalPayment": { "$ref": "#/components/schemas/FiatPayment" }, "cancel": { "$ref": "#/components/schemas/FiatCancel" }, "refunds": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/FiatRefund" } }, "fees": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "trackingRef": { "description": "Payment tracking reference. Will be present once known.", "type": "string", "nullable": true, "example": "24910599141085313498894" }, "externalRef": { "$ref": "#/components/schemas/ExternalRef" }, "errorCode": { "$ref": "#/components/schemas/PaymentErrorCode" }, "metadata": { "$ref": "#/components/schemas/MetadataPhoneEmail" }, "channel": { "$ref": "#/components/schemas/Channel" }, "riskEvaluation": { "$ref": "#/components/schemas/RiskEvaluation" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" } } }, "PayoutStatus": { "type": "string", "description": "Status of the payout. Status `pending` indicates that the payout is in process; `complete` indicates it finished successfully; `failed` indicates it failed.", "enum": ["pending", "complete", "failed"] }, "BusinessAccountPayoutDestinationType": { "type": "string", "description": "The destination bank account type.", "enum": ["wire", "cubix"] }, "BankDestination": { "type": "object", "description": "The destination bank account.", "required": ["type", "id"], "properties": { "type": { "$ref": "#/components/schemas/BusinessAccountPayoutDestinationType" }, "id": { "$ref": "#/components/schemas/Id" }, "name": { "type": "string", "description": "Bank name plus last four digits of the bank account number or IBAN.", "example": "COMMERZBANK AG ****3000" } } }, "FiatPayoutToMoney": { "type": "object", "required": ["currency"], "properties": { "amount": { "description": "Magnitude of the amount, in units of the currency, with a `.`.", "type": "string", "example": "3.14", "readOnly": true }, "currency": { "$ref": "#/components/schemas/FiatCurrency" } } }, "PayoutErrorCode": { "type": "string", "nullable": true, "description": "Indicates the failure reason of a payout. Only present for payouts in failed state. Possible values are [`insufficient_funds`, `transaction_denied`, `transaction_failed`, `transaction_returned`, `bank_transaction_error`, `fiat_account_limit_exceeded`, `invalid_bank_account_number`, `invalid_ach_rtn`, `invalid_wire_rtn`, `vendor_inactive`]'", "enum": [ "insufficient_funds", "transaction_denied", "transaction_failed", "transaction_returned", "bank_transaction_error", "fiat_account_limit_exceeded", "invalid_bank_account_number", "invalid_ach_rtn", "invalid_wire_rtn", "vendor_inactive" ] }, "FinalAdjustments": { "type": "object", "description": "Final adjustment which increases (credits) or decreases (debits) the total returned amount to the source wallet.", "nullable": true, "properties": { "fxCredit": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "fxDebit": { "$ref": "#/components/schemas/FiatMoneyUsd" } } }, "IdPayout": { "type": "string", "description": "Universally unique identifier (UUID v4) of the payout that is associated with the return.", "format": "uuid", "example": "abdb500d-4a59-457c-801f-2d418c8703ac" }, "UnwithdrawalObject": { "type": "object", "description": "Return information if the payout is returned by bank. Only present if `errorCode` of payout is `transaction_returned`.", "nullable": true, "properties": { "id": { "$ref": "#/components/schemas/Id" }, "payoutId": { "$ref": "#/components/schemas/IdPayout" }, "amount": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "fees": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "reason": { "type": "string", "description": "Reason for the return.", "example": "payout_returned" }, "status": { "type": "string", "description": "Status of the return. A `pending` status indicates that the return is in process; `complete` indicates it finished successfully; `failed` indicates it failed.", "enum": ["pending", "complete", "failed"] }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" } } }, "ListBusinessPayout": { "title": "ListBusinessPayoutsResponse", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "sourceWalletId": { "type": "string", "description": "The identifier of the source wallet used to fund a payout.", "example": "53535335" }, "destination": { "$ref": "#/components/schemas/BankDestination" }, "amount": { "$ref": "#/components/schemas/FiatMoney" }, "toAmount": { "$ref": "#/components/schemas/FiatPayoutToMoney" }, "fees": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "status": { "$ref": "#/components/schemas/PayoutStatus" }, "errorCode": { "$ref": "#/components/schemas/PayoutErrorCode" }, "riskEvaluation": { "$ref": "#/components/schemas/RiskEvaluation" }, "adjustments": { "$ref": "#/components/schemas/FinalAdjustments" }, "return": { "$ref": "#/components/schemas/UnwithdrawalObject" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" } } } } } }, "BusinessDestinationRequest": { "type": "object", "description": "The destination bank account.", "required": ["type", "id"], "properties": { "type": { "type": "string", "enum": ["wire", "cubix", "pix", "sepa", "sepa_instant"] }, "id": { "$ref": "#/components/schemas/Id" } } }, "InstitutionalWalletId": { "type": "string", "description": "Unique system-generated identifier for the wallet of the institutional entity.", "example": "212000" }, "BusinessPayoutCreationRequest": { "type": "object", "required": ["idempotencyKey", "destination", "amount"], "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, "destination": { "$ref": "#/components/schemas/BusinessDestinationRequest" }, "amount": { "$ref": "#/components/schemas/FiatMoney" }, "toAmount": { "description": "To be used when requesting currency exchange", "$ref": "#/components/schemas/FiatPayoutToMoney" }, "source": { "type": "object", "required": ["id", "type"], "properties": { "id": { "$ref": "#/components/schemas/InstitutionalWalletId" }, "type": { "type": "string", "enum": ["wallet"] } }, "description": "The source wallet to pay out from. If not provided, the deposit will come from the main wallet of the account.\n\nYou can get wallet IDs associated with your account using the [Core API for Institutions](/api-reference/circle-mint/institutional/get-all-external-entities).\n" } } }, "BusinessPayout": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "sourceWalletId": { "type": "string", "description": "The identifier of the source wallet used to fund a payout.", "example": "53535335" }, "destination": { "$ref": "#/components/schemas/BankDestination" }, "amount": { "$ref": "#/components/schemas/FiatMoney" }, "toAmount": { "$ref": "#/components/schemas/FiatPayoutToMoney" }, "fees": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "status": { "$ref": "#/components/schemas/PayoutStatus" }, "trackingRef": { "type": "string", "description": "A payout tracking reference. Will be present once known.", "nullable": true, "example": "CIR-6ESOQANEP3NAO" }, "errorCode": { "$ref": "#/components/schemas/PayoutErrorCode" }, "riskEvaluation": { "$ref": "#/components/schemas/RiskEvaluation" }, "adjustments": { "$ref": "#/components/schemas/FinalAdjustments" }, "return": { "$ref": "#/components/schemas/UnwithdrawalObject" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" } } }, "PayoutDestinationType": { "type": "string", "description": "The destination type.", "enum": ["address_book"] }, "CryptoPayoutDestinationType": { "type": "string", "description": "The destination type.", "enum": ["address_book"] }, "CryptoPayoutDestination": { "type": "object", "description": "The destination.", "required": ["type", "id"], "properties": { "type": { "$ref": "#/components/schemas/CryptoPayoutDestinationType" }, "id": { "$ref": "#/components/schemas/Id" } } }, "PayoutMoney": { "type": "object", "required": ["amount", "currency"], "properties": { "amount": { "type": "string", "description": "Magnitude of the amount, in units of the currency, with a `.`.", "example": "3.14" }, "currency": { "type": "string", "description": "Currency code for the amount.", "enum": ["USD", "EUR", "BTC", "ETH", "MTC", "FLW", "MAN"] } } }, "CryptoPayout": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "sourceWalletId": { "type": "string", "description": "The identifier of the source wallet used to fund a payout.", "example": "53535335" }, "destination": { "$ref": "#/components/schemas/CryptoPayoutDestination" }, "amount": { "$ref": "#/components/schemas/PayoutMoney" }, "toAmount": { "$ref": "#/components/schemas/PayoutMoney" }, "fees": { "$ref": "#/components/schemas/PayoutMoney" }, "networkFees": { "$ref": "#/components/schemas/PayoutMoney" }, "status": { "$ref": "#/components/schemas/PayoutStatus" }, "errorCode": { "$ref": "#/components/schemas/PayoutErrorCode" }, "riskEvaluation": { "$ref": "#/components/schemas/RiskEvaluation" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" } } }, "IdentityAddress": { "type": "object", "required": ["line1", "city", "district", "postalCode", "country"], "properties": { "line1": { "type": "string", "description": "Line one of the street address.", "maxLength": 1024, "example": "100 Money Street" }, "line2": { "type": "string", "description": "Line two of the street address.", "maxLength": 1024, "example": "Suite 1" }, "city": { "type": "string", "description": "City portion of the address.", "maxLength": 1024, "example": "Boston" }, "district": { "description": "State / County / Province / Region portion of the address. If the country is US or Canada, then district is required and should use the two-letter code for the subdivision.", "type": "string", "maxLength": 16, "example": "MA" }, "postalCode": { "type": "string", "description": "Postal / ZIP code of the address.", "maxLength": 16, "example": "01234" }, "country": { "type": "string", "description": "Country portion of the address. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2.", "maxLength": 2, "example": "US" } } }, "Identity": { "type": "object", "description": "The identity of the originator. Identities are required when:\n * `destination.type: \"blockchain\"`\n * `destination.chain: \"ETH\"`\n * `amount.amount` >= $3,000 in value\n", "required": ["type", "name", "addresses"], "properties": { "type": { "type": "string", "description": "The type of identity for the originator.\n* `individual` - A uniquely distinguishable individual.\n* `business` - Any entity other than a natural person that can establish a permanent customer relationship with an affected entity or otherwise own property. This can include companies, foundations, anstalt, partnerships, associations and other relevantly similar entities.\n", "enum": ["individual", "business"] }, "name": { "type": "string", "description": "Full name of the identity.", "example": "Satoshi Nakamoto", "maxLength": 1024 }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityAddress" } } } }, "TransferSourceWalletLocation": { "description": "A source wallet location.", "type": "object", "required": ["type", "id"], "properties": { "type": { "type": "string", "enum": ["wallet"] }, "id": { "type": "string", "description": "The id of the wallet.", "example": "12345" }, "identities": { "type": "array", "items": { "$ref": "#/components/schemas/Identity" } } } }, "CryptoPayoutMoney": { "type": "object", "required": ["amount", "currency"], "properties": { "amount": { "type": "string", "description": "The numeric value of the amount, expressed in units of the specified currency.\nUse a period (`.`) as the decimal separator.\n", "example": "3.14" }, "currency": { "type": "string", "description": "The ISO 4217 currency code for the amount.", "enum": ["USD", "EUR"] } } }, "CryptoPayoutCreationRequest": { "type": "object", "required": ["idempotencyKey", "destination", "amount"], "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, "source": { "$ref": "#/components/schemas/TransferSourceWalletLocation" }, "destination": { "$ref": "#/components/schemas/CryptoPayoutDestination" }, "amount": { "$ref": "#/components/schemas/CryptoPayoutMoney" }, "toAmount": { "$ref": "#/components/schemas/CryptoPayoutMoney" } } }, "ExchangeType": { "type": "string", "description": "The type of exchange.", "enum": ["reference", "tradable"], "example": "tradable" }, "ExchangeRateOptionalAmountMoney": { "type": "object", "required": ["currency"], "properties": { "amount": { "description": "Magnitude of the amount, in units of the currency, with a `.`.", "type": "string", "example": "3.14" }, "currency": { "type": "string", "description": "Currency code.", "enum": [ "USDC", "EURC", "MXN", "SGD", "BRL", "HKD", "GBP", "CNH", "AED" ] } } }, "ExchangeRateRequest": { "type": "object", "required": ["from", "to", "idempotencyKey", "type"], "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, "type": { "$ref": "#/components/schemas/ExchangeType" }, "from": { "$ref": "#/components/schemas/ExchangeRateOptionalAmountMoney" }, "to": { "$ref": "#/components/schemas/ExchangeRateOptionalAmountMoney" } } }, "FiatOptionalAmountMoney": { "type": "object", "title": "OptionalAmountMoney", "required": ["currency"], "properties": { "amount": { "description": "Magnitude of the amount, in units of the currency, with a `.`.", "type": "string", "example": "3.14" }, "currency": { "$ref": "#/components/schemas/FiatCurrency" } } }, "ExchangeRateResponse": { "type": "object", "required": ["id", "rate", "from", "to", "expiry", "type"], "properties": { "id": { "$ref": "#/components/schemas/Id" }, "rate": { "description": "Exchange rate", "type": "number", "format": "float", "example": 0.1974 }, "from": { "$ref": "#/components/schemas/FiatOptionalAmountMoney" }, "to": { "$ref": "#/components/schemas/FiatOptionalAmountMoney" }, "expiry": { "$ref": "#/components/schemas/UtcTimestamp" }, "type": { "$ref": "#/components/schemas/ExchangeType" }, "estimatedSettlementTime": { "type": "string", "format": "date-time", "example": "2020-04-10T03:13:30.000Z", "description": "Estimated settlement timestamp in ISO-8601 UTC date/time format. \nOnce funds are received, we aim to settle by the time shown. Settlement times are estimates and may vary due to processing delays. \nShown only for quotes where `type` = `tradable`.\n" } } }, "BurnFeePayoutAmount": { "type": "object", "required": ["amount", "currency"], "properties": { "amount": { "description": "Sum of all initiated payouts, in units of the currency, with a `.`.", "type": "string", "example": "3.14" }, "currency": { "$ref": "#/components/schemas/FiatCurrency" } } }, "BurnFeePaymentAmount": { "type": "object", "required": ["amount", "currency"], "properties": { "amount": { "description": "Sum of all push payments received, in units of the currency, with a `.`.", "type": "string", "example": "3.14" }, "currency": { "$ref": "#/components/schemas/FiatCurrency" } } }, "BurnFeeNetAmount": { "type": "object", "required": ["amount", "currency"], "properties": { "amount": { "description": "Sum of all initiated payouts minus sum of all received push payments, in units of the currency, with a `.`.", "type": "string", "example": "3.14" }, "currency": { "$ref": "#/components/schemas/FiatCurrency" } } }, "RedemptionFeeCalculation": { "type": "object", "description": "A burn fee calculation for a day.", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "fee": { "$ref": "#/components/schemas/FiatMoney" }, "cumulatedPayoutAmount": { "$ref": "#/components/schemas/BurnFeePayoutAmount" }, "cumulatedPaymentAmount": { "$ref": "#/components/schemas/BurnFeePaymentAmount" }, "cumulatedNetAmount": { "$ref": "#/components/schemas/BurnFeeNetAmount" }, "valueDate": { "description": "A date representing a day for which a fee is calculated.", "type": "string", "example": "2023-05-23" }, "status": { "description": "Fee collection status", "type": "string", "enum": ["scheduled", "pending", "paid"] }, "thresholdResetTimestamp": { "description": "Fee calculation reset timestamp.", "type": "string", "example": "2023-05-23T23:59:59.999Z" }, "createDate": { "description": "The create date of the burn fee calculation.", "type": "string", "format": "date-time" }, "feeType": { "description": "The aggregation method used to calculate the fee.", "type": "string", "enum": ["gross", "net"], "example": "net" } } }, "TransferSourceBlockchainLocation": { "description": "A source blockchain address.", "type": "object", "required": ["type", "chain"], "properties": { "type": { "type": "string", "enum": ["blockchain"] }, "chain": { "$ref": "#/components/schemas/Chain" }, "identities": { "type": "array", "items": { "$ref": "#/components/schemas/Identity" } } } }, "TransferSourceLocation": { "description": "A source of funds.", "oneOf": [ { "$ref": "#/components/schemas/TransferSourceWalletLocation" }, { "$ref": "#/components/schemas/TransferSourceBlockchainLocation" } ] }, "TransferDestinationBlockchainLocation": { "description": "A destination blockchain address.", "type": "object", "required": ["type", "chain", "address"], "properties": { "type": { "type": "string", "enum": ["blockchain"] }, "address": { "$ref": "#/components/schemas/Address" }, "addressTag": { "$ref": "#/components/schemas/AddressTag" }, "chain": { "$ref": "#/components/schemas/Chain" } } }, "TransferDestinationWalletLocation": { "description": "A destination wallet location.", "type": "object", "required": ["type", "id"], "properties": { "type": { "type": "string", "enum": ["wallet"] }, "id": { "type": "string", "description": "The id of the wallet.", "example": "12345" }, "address": { "type": "string", "description": "An alphanumeric string which indicates the wallet address used to receive the transfer. Will only be set when the transfer source is a blockchain address.", "example": "0x8381470ED67C3802402dbbFa0058E8871F017A6F" }, "addressTag": { "$ref": "#/components/schemas/AddressTag" } } }, "TransferDestinationLocation": { "description": "A destination of funds.", "oneOf": [ { "$ref": "#/components/schemas/TransferDestinationBlockchainLocation" }, { "$ref": "#/components/schemas/TransferDestinationWalletLocation" } ] }, "Fee": { "type": "object", "required": ["amount", "currency", "type"], "properties": { "amount": { "type": "string", "description": "Magnitude of the fee amount, in units of the currency, with a `.`.", "example": "10.00" }, "currency": { "type": "string", "description": "Currency code for the amount.", "enum": ["USD"] }, "type": { "type": "string", "description": "Category of the fee.", "enum": ["network"] } } }, "TransferErrorCode": { "type": "string", "description": "Indicates the failure reason of a transfer. Only present for transfers in a `failed` state. Possible values are `insufficient_funds`, `blockchain_error` and `transfer_denied` and `transfer_failed`", "nullable": true, "enum": [ "transfer_failed", "transfer_denied", "blockchain_error", "insufficient_funds" ] }, "Transfer": { "type": "object", "description": "A transfer of funds.", "required": ["id", "source", "destination", "amount", "status"], "properties": { "id": { "$ref": "#/components/schemas/Id" }, "source": { "$ref": "#/components/schemas/TransferSourceLocation" }, "destination": { "$ref": "#/components/schemas/TransferDestinationLocation" }, "amount": { "$ref": "#/components/schemas/Money" }, "fees": { "description": "An array of fees applied to a transaction. This is only available when there is at least one non-zero fee.", "type": "array", "items": { "$ref": "#/components/schemas/Fee" } }, "transactionHash": { "description": "A hash that uniquely identifies the onchain transaction. This is only available where either source or destination are of type blockchain.", "type": "string", "example": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63" }, "status": { "description": "Status of the transfer. Status `pending` indicates that the transfer is in the process of running; `complete` indicates it finished successfully; `failed` indicates it failed. Circle Mint Singapore customers may have transfers in the `pending` status if the recipient addresses are not verified.", "type": "string", "enum": ["pending", "complete", "failed"] }, "errorCode": { "$ref": "#/components/schemas/TransferErrorCode" }, "createDate": { "description": "The create date of the transfer.", "type": "string", "format": "date-time" } } }, "TransferRequestVerifiedBlockchainLocation": { "type": "object", "required": ["type", "addressId"], "properties": { "type": { "type": "string", "enum": ["verified_blockchain"] }, "addressId": { "type": "string", "description": "The ID of the verified blockchain recipient address.", "example": "f1f36b85-cafe-484e-a46b-02340bfdb927", "format": "uuid" } } }, "BusinessTransferCreationRequest": { "type": "object", "required": ["idempotencyKey", "destination", "amount"], "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, "destination": { "$ref": "#/components/schemas/TransferRequestVerifiedBlockchainLocation" }, "amount": { "$ref": "#/components/schemas/Money" }, "source": { "description": "The wallet to be used as the source of the transfer. If not provided, the transfer will come from the main wallet of the account.\n\nYou can get wallet IDs associated with your account using the [Core API for Institutions](/api-reference/circle-mint/institutional/get-all-external-entities).\n", "type": "object", "required": ["id", "type"], "properties": { "id": { "$ref": "#/components/schemas/InstitutionalWalletId" }, "type": { "type": "string", "enum": ["wallet"] } } } } }, "MockWirePaymentBeneficiaryBankInstruction": { "type": "object", "required": ["accountNumber"], "properties": { "accountNumber": { "type": "string", "description": "Virtual account number or Circle corporate Wells Fargo wire account number that needs to be set as destination.", "example": "11111111" } } }, "MockWirePaymentRequest": { "type": "object", "required": ["trackingRef", "amount", "beneficiaryBank"], "properties": { "trackingRef": { "type": "string", "description": "Wire tracking reference that needs to be set in the wire reference to beneficiary field. This field is retrievable through the response during wire creation or via the bank instruction endpoint.", "example": "CIR13FB13A" }, "amount": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "beneficiaryBank": { "$ref": "#/components/schemas/MockWirePaymentBeneficiaryBankInstruction" } } }, "MockWirePaymentResponse": { "type": "object", "properties": { "trackingRef": { "type": "string", "description": "Wire tracking reference that needs to be set in the wire reference to beneficiary field. This field is retrievable through the response during wire creation or via the bank instruction endpoint.", "example": "CIR13FB13A" }, "amount": { "$ref": "#/components/schemas/FiatMoneyUsd" }, "beneficiaryBank": { "$ref": "#/components/schemas/MockWirePaymentBeneficiaryBankInstruction" }, "status": { "type": "string", "description": "Enumerated status of the wire payment. Status `pending` indicates that the wire payment is in process; `processed` indicates it finished successfully; `failed` indicates it failed.", "enum": ["pending", "processed", "failed"] } } }, "FxCurrency": { "type": "string", "enum": ["USDC", "EURC", "MXN", "BRL"] }, "FxMoney": { "type": "object", "required": ["amount", "currency"], "properties": { "amount": { "description": "Magnitude of the amount, in units of the currency, with a `.`.", "type": "string", "example": "3.14" }, "currency": { "$ref": "#/components/schemas/FxCurrency" } } }, "TradeStatus": { "type": "string", "description": "Status of the trade.", "enum": [ "pending", "confirmed", "failed", "complete", "pending_settlement" ] }, "Trade": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "from": { "$ref": "#/components/schemas/FxMoney" }, "to": { "$ref": "#/components/schemas/FxMoney" }, "status": { "$ref": "#/components/schemas/TradeStatus" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "quoteId": { "$ref": "#/components/schemas/Id" }, "settlementId": { "$ref": "#/components/schemas/Id" }, "rate": { "type": "string", "description": "Rate associated with the FX trade.", "example": 0.9039 }, "expectedBatchTime": { "description": "Expected time for the trade to be batched for settlement.", "$ref": "#/components/schemas/UtcTimestamp" } } }, "FxTradeRequest": { "type": "object", "required": ["idempotencyKey", "quoteId"], "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, "quoteId": { "$ref": "#/components/schemas/Id" } } }, "CreateFxTradeResponse": { "title": "CreateFxTradeResponse", "properties": { "data": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "from": { "$ref": "#/components/schemas/FxMoney" }, "to": { "$ref": "#/components/schemas/FxMoney" }, "status": { "$ref": "#/components/schemas/TradeStatus" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "quoteId": { "$ref": "#/components/schemas/Id" } } } } }, "SettlementStatus": { "type": "string", "description": "Status of the settlement.", "enum": ["pending", "settled"] }, "SettlementDetailStatus": { "type": "string", "enum": ["pending", "completed"] }, "Settlement": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "entityId": { "$ref": "#/components/schemas/Id" }, "status": { "$ref": "#/components/schemas/SettlementStatus" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "details": { "type": "array", "items": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "type": { "type": "string", "enum": ["payable", "receivable"] }, "amount": { "$ref": "#/components/schemas/FxMoney" }, "status": { "$ref": "#/components/schemas/SettlementDetailStatus" }, "reference": { "type": "string", "example": "FXR1234567" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" } } } } } }, "MXNSettlementInstructions": { "type": "object", "properties": { "currency": { "type": "string", "enum": ["MXN"] }, "fiatAccountType": { "$ref": "#/components/schemas/BusinessAccountPayoutDestinationType" }, "instruction": { "$ref": "#/components/schemas/WireInstruction" } } }, "BRLSettlementInstructions": { "type": "object", "properties": { "currency": { "type": "string", "enum": ["BRL"] }, "fiatAccountType": { "type": "string", "enum": ["pix"] }, "instruction": { "type": "object", "properties": { "ispb": { "type": "string", "example": "87654321" }, "branchCode": { "type": "string", "example": "0001" }, "accountNumber": { "type": "string", "example": "12345678" }, "name": { "type": "string", "example": "Circle Internet Financial LLC" }, "accountType": { "$ref": "#/components/schemas/PixAccountType" }, "taxId": { "type": "string", "example": "12.345.678/0001-90" } } } } }, "FxFiatCurrency": { "type": "string", "enum": ["MXN", "BRL"] }, "CreateFxAccountRequest": { "type": "object", "properties": { "fiatAccountId": { "$ref": "#/components/schemas/Id" }, "currency": { "$ref": "#/components/schemas/FxFiatCurrency" } } }, "CreateFxAccountResponse": { "type": "object", "properties": { "currency": { "$ref": "#/components/schemas/FxFiatCurrency" }, "fiatAccountId": { "$ref": "#/components/schemas/Id" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, "updateDate": { "$ref": "#/components/schemas/UtcTimestamp" } } }, "FxCurrencyLimit": { "type": "object", "properties": { "limit": { "type": "string", "example": "1000000.00" }, "usage": { "type": "string", "example": "0.00" }, "available": { "type": "string", "example": "1000000.00" } } }, "DailyFxLimits": { "type": "object", "properties": { "EURC": { "$ref": "#/components/schemas/FxCurrencyLimit" }, "MXN": { "$ref": "#/components/schemas/FxCurrencyLimit" }, "USDC": { "$ref": "#/components/schemas/FxCurrencyLimit" }, "BRL": { "$ref": "#/components/schemas/FxCurrencyLimit" } } }, "MockPixPaymentRequest": { "type": "object", "required": ["trackingRef", "amount", "accountNumber"], "properties": { "trackingRef": { "type": "string", "description": "PIX tracking reference that needs to be set in the PIX reference to beneficiary field. This field is retrievable through the response during PIX creation or via the bank instruction endpoint.", "example": "CIR13FB13A" }, "amount": { "type": "object", "required": ["amount", "currency"], "properties": { "amount": { "description": "Magnitude of the amount, in units of the currency, with a `.`.", "type": "string", "example": "3.14" }, "currency": { "type": "string", "enum": ["BRL"] } } }, "accountNumber": { "type": "string", "description": "The account number that the money should be transferred to.", "example": "4842622" } } }, "MockPixPaymentResponse": { "type": "object", "properties": { "trackingRef": { "type": "string", "description": "PIX tracking reference that needs to be set in the PIX reference to beneficiary field. This field is retrievable through the response during PIX creation or via the bank instruction endpoint.", "example": "CIR13FB13A" }, "amount": { "type": "object", "required": ["amount", "currency"], "properties": { "amount": { "description": "Magnitude of the amount, in units of the currency, with a `.`.", "type": "string", "example": "3.14" }, "currency": { "type": "string", "enum": ["BRL"] } } }, "beneficiaryAccountNumber": { "type": "string", "example": "4842622" }, "status": { "type": "string", "description": "Enumerated status of the PIX payment. Status `pending` indicates that the PIX payment is in process; `processed` indicates it finished successfully; `failed` indicates it failed.", "enum": ["pending", "processed", "failed"] } } }, "DailyCustodyBalancesRequest": { "type": "object", "required": [ "idempotencyKey", "currency", "localBalance", "asOfDate", "reportType", "additionalFields" ], "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, "currency": { "type": "string", "description": "The type of token being reported.", "enum": ["USDC", "EURC"], "example": "USDC" }, "localBalance": { "type": "number", "format": "double", "description": "Regional specific balance for the provided token type.\n\neea - tokens held by the EU licensed crypto-asset service provider, which are held by Union clients of that EU licensed crypto-asset service provider.\n\njapan_trust - total amount held in custody on behalf of customers of the EPIESP.\n", "example": 1000000 }, "asOfDate": { "type": "string", "format": "date", "description": "The day being reported in the format YYYY-MM-DD with timezone UTC.", "example": "2025-06-26" }, "reportType": { "type": "string", "description": "The type of report being created.", "enum": ["eea", "japan_trust"], "example": "eea" }, "additionalFields": { "type": "object", "description": "Additional fields are required only for the `eea` report type. They are ignored for the `japan_trust` report type.\n", "required": [ "equivalentEuroLocalBalance", "totalBalance", "equivalentEuroTotalBalance" ], "properties": { "equivalentEuroLocalBalance": { "type": "number", "format": "double", "description": "EUR equivalent of the `localBalance` field.", "example": 26994.6 }, "totalBalance": { "type": "number", "format": "double", "description": "Tokens held by the EU licensed crypto-asset service provider", "example": 5000000 }, "equivalentEuroTotalBalance": { "type": "number", "format": "double", "description": "EUR equivalent of the total worldwide token balance.", "example": 853949.09 } } } } }, "DailyCustodyBalancesResponse": { "type": "object", "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, "id": { "$ref": "#/components/schemas/Id" }, "createDate": { "type": "string", "format": "date-time", "example": "2025-07-15T18:03:52.429Z" }, "localBalance": { "type": "number", "format": "double", "description": "Regional specific balance for the provided token type.\n\neea - tokens held by the EU licensed crypto-asset service provider, which are held by Union clients of that EU licensed crypto-asset service provider.\n\njapan_trust - total amount held in custody on behalf of customers of the EPIESP.\n", "example": 1000000 }, "currency": { "type": "string", "description": "The type of token being reported.", "enum": ["USDC", "EURC"], "example": "USDC" }, "asOfDate": { "type": "string", "format": "date", "description": "The day being reported in the format YYYY-MM-DD with timezone UTC.", "example": "2025-06-26" }, "reportType": { "type": "string", "description": "The type of report being created.", "enum": ["eea", "japan_trust"], "example": "eea" }, "additionalFields": { "type": "object", "description": "Additional fields are required only for the `eea` report type. They are ignored for the `japan_trust` report type.\n", "properties": { "equivalentEuroLocalBalance": { "type": "number", "format": "double", "description": "EUR equivalent of the `localBalance` field.", "example": 26994.6 }, "totalBalance": { "type": "number", "format": "double", "description": "Tokens held by the EU licensed crypto-asset service provider", "example": 5000000 }, "equivalentEuroTotalBalance": { "type": "number", "format": "double", "description": "EUR equivalent of the total worldwide token balance.", "example": 853949.09 } } } } }, "ExternalEntity": { "type": "object", "description": "An external entity", "properties": { "walletId": { "$ref": "#/components/schemas/InstitutionalWalletId" }, "businessName": { "type": "string", "description": "The name of the business.", "example": "Circle Internet Financial Inc." }, "businessUniqueIdentifier": { "type": "string", "description": "The unique identifier of the business. For example, a company number or tax ID.", "example": "1234567890" }, "identifierIssuingCountryCode": { "type": "string", "description": "The country code of the issuing authority. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2.", "pattern": "^[A-Z]{2}$", "example": "US" }, "complianceState": { "type": "string", "description": "The compliance status of the external entity.", "enum": ["PENDING", "ACCEPTED", "REJECTED"] } } }, "InstitutionalAddress": { "type": "object", "required": ["country", "state", "city", "postalCode"], "properties": { "country": { "type": "string", "description": "Country portion of the address. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2.", "pattern": "^[A-Z]{2}$", "example": "US" }, "state": { "type": "string", "description": "State / county / province / region / district / emirate portion of the address. US and Canada use the two-letter code for the subdivision.", "example": "MA" }, "city": { "type": "string", "description": "City portion of the address.", "example": "Boston" }, "postcode": { "type": "string", "description": "Postal / ZIP code of the address. If there is no applicable postal code, set the value to `00000`.", "example": "01234" }, "streetName": { "type": "string", "description": "Street name of the address.", "example": "Main Street" }, "buildingNumber": { "type": "string", "description": "Street number of the address.", "example": "100" } } }, "ExternalEntityCreationRequest": { "type": "object", "required": [ "businessName", "businessUniqueIdentifier", "identifierIssuingCountryCode", "address" ], "properties": { "businessName": { "type": "string", "description": "The name of the business.", "example": "Circle Internet Financial Inc." }, "businessUniqueIdentifier": { "type": "string", "description": "The unique identifier of the business. For example, a company number or tax ID.", "example": "1234567890" }, "identifierIssuingCountryCode": { "type": "string", "description": "The country code of the issuing authority. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2.", "pattern": "^[A-Z]{2}$", "example": "US" }, "address": { "$ref": "#/components/schemas/InstitutionalAddress" } } } }, "headers": { "XRequestId": { "description": "Universally unique identifier (UUID v4) for the request. Helpful for identifying a request when communicating with Circle support.", "schema": { "type": "string", "format": "uuid", "example": "2adba88e-9d63-44bc-b975-9b6ae3440dde" } } }, "responses": { "NotAuthorized": { "description": "The request has not been applied because it lacks valid authentication credentials.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "title": "NotAuthorized", "required": ["code", "message"], "properties": { "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Something went wrong." } }, "example": { "code": 401, "message": "Malformed authorization." } }, "examples": { "response": { "value": { "code": 401, "message": "Malformed authorization." } } } } } }, "BadRequest": { "description": "The request cannot be processed due to a client error.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "title": "BadRequest", "required": ["code", "message"], "properties": { "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Something went wrong." } }, "example": { "code": 400, "message": "Bad request." } }, "examples": { "response": { "value": { "code": 400, "message": "Bad request." } } } } } }, "LimitExceeded": { "description": "Limit exceeded. See error message for more details.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "title": "LimitExceeded", "required": ["code", "message"], "properties": { "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Something went wrong." } }, "example": { "code": 429, "message": "Too many requests." } }, "examples": { "response": { "value": { "code": 429, "message": "Too many requests." } } } } } }, "NotFound": { "description": "The specified resource was not found.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "title": "NotFound", "required": ["code", "message"], "properties": { "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Something went wrong." } }, "example": { "code": 404, "message": "Not found." } }, "examples": { "response": { "value": { "code": 404, "message": "Not found." } } } } } }, "Forbidden": { "description": "The request provides authentication, but the authenticated user does not possess sufficient permissions for accessing this resource.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "title": "Forbidden", "required": ["code", "message"], "properties": { "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Something went wrong." } }, "example": { "code": 3, "message": "Forbidden" } }, "examples": { "response": { "value": { "code": 3, "message": "Forbidden" } } } } } }, "Conflict": { "description": "The request has not been applied because it comes in conflict with another request (such as re-using an idempotencyKey for a different request).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "title": "Conflict", "required": ["code", "message"], "properties": { "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Something went wrong." } }, "example": { "code": 409, "message": "Conflicts with another request." } }, "examples": { "response": { "value": { "code": 409, "message": "Conflicts with another request." } } } } } } }, "parameters": { "IdPath": { "name": "id", "description": "Universally unique identifier (UUID v4) of a resource.", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "b3d9d2d5-4c12-4946-a09d-953e82fae2b0" } }, "Currency": { "name": "currency", "description": "Queries beneficiary bank account currency. Default is USD.", "in": "query", "required": false, "schema": { "type": "string", "enum": ["USD", "EUR"] } }, "From": { "name": "from", "description": "Queries items created since the specified date-time (inclusive).", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2020-04-10T02:13:30.000Z" } }, "To": { "name": "to", "description": "Queries items created before the specified date-time (inclusive).", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2020-04-10T02:13:30.000Z" } }, "PageBefore": { "name": "pageBefore", "description": "A collection ID value used for pagination.\n\nIt marks the exclusive end of a page. When provided, the collection resource will return the next `n` items before\nthe id, with `n` being specified by `pageSize`.\n\nThe items will be returned in the natural order of the collection.\n\nThe resource will return the first page if neither `pageAfter` nor `pageBefore` are specified.\n\nSHOULD NOT be used in conjuction with pageAfter.\n", "in": "query", "required": false, "schema": { "type": "string" } }, "PageAfter": { "name": "pageAfter", "description": "A collection ID value used for pagination.\n\nIt marks the exclusive begin of a page. When provided, the collection resource will return the next `n` items after\nthe id, with `n` being specified by `pageSize`.\n\nThe items will be returned in the natural order of the collection.\n\nThe resource will return the first page if neither `pageAfter` nor `pageBefore` are specified.\n\nSHOULD NOT be used in conjuction with pageBefore.\n", "in": "query", "required": false, "schema": { "type": "string" } }, "PageSize": { "name": "pageSize", "description": "Limits the number of items to be returned.\n\nSome collections have a strict upper bound that will disregard this value. In case the specified value is higher\nthan the allowed limit, the collection limit will be used.\n\nIf avoided, the collection will determine the page size itself.\n", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "example": 5 } }, "Source": { "name": "source", "description": "Universally unique identifier (UUID v4) for the source. Filters results to fetch only payments made from the provdided source.", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "b3d9d2d5-4c12-4946-a09d-953e82fae2b0" } }, "SettlementId": { "name": "settlementId", "description": "Queries items with the specified settlement id. Matches any settlement id if unspecified.", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "b48c8962-8e9f-40c3-9f1d-d9adde2ffe61" } }, "PaymentIntentId": { "name": "paymentIntentId", "description": "Queries items with the specified payment intent id.", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "b48c8962-8e9f-40c3-9f1d-d9adde2ffe61" } }, "PaymentSourceType": { "name": "type", "description": "Source account type. Filters the results to fetch all payments made from a specified account type. Matches any source type if unspecified.", "in": "query", "required": false, "schema": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": ["card"] } } }, "PaymentStatus": { "name": "status", "description": "Queries items with the specified status. Matches any status if unspecified.", "in": "query", "required": false, "schema": { "type": "string", "enum": ["pending", "confirmed", "paid", "failed", "action_required"] } }, "Destination": { "name": "destination", "description": "Universally unique identifier (UUID v4) for the destination bank account. Filters the results to fetch all payouts made to a destination bank account.", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "e3d0a838-d732-49d0-bf44-73a668e38973" } }, "Chain": { "name": "chain", "description": "Queries items with the specified chain. Matches any chain if unspecified", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ALGO", "APTOS", "ARB", "AVAX", "BASE", "BTC", "CELO", "CODEX", "ETH", "HBAR", "HYPEREVM", "INK", "LINEA", "NEAR", "NOBLE", "OP", "PLUME", "PAH", "POLY", "SEI", "SOL", "SONIC", "SUI", "UNI", "WORLDCHAIN", "XDC", "XLM", "XRP", "ZKS", "ZKSYNC" ] } }, "FxCurrencyPath": { "name": "currency", "description": "Fiat currency name.", "in": "path", "required": true, "schema": { "type": "string", "enum": ["BRL", "MXN"] } } } } }