Silvergate SEN Quickstart

Deposit U.S. dollars that settle in USDC, and euros that settle in EUROC

1. Get an API key

Circle APIs use API keys as the mechanism to authenticate client requests. The API key must be set in the Authorization header of the request sent from your backend server. The format of the header is Bearer secret-key-value.

Learn more about authenticating API calls here.

To obtain an API key for the sandbox environment, simply create an account and generate a new key in settings - it only takes a few seconds.


Get an API key

Once you have generated your API key, record it in a secure place.

2. Create a SEN Bank Account to Deposit Funds from

Make an API call to create the bank account you intend to deposit from by using the create bank account for SEN transfers endpoint. From there you can populate Authentication Bearer with the API key (from the previous step), add values to the form fields idempotencyKey and accountNumber, and click try it.

📘

Please note that for your ‘Euro SEN’ bank account to transact with Circle, authorization needs to be provided to Silvergate Bank. Contact your Circle rep for additional details.

Alternatively, you can use the command below to make an API call to POST /v1/businessAccount/banks/sen yourself.

# Replace ${YOUR_API_KEY} with the API key obtained on step 1
curl -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H "Authorization: Bearer ${YOUR_API_KEY}" \
    -X POST --url https://api-sandbox.circle.com/v1/businessAccount/banks/sen \
    --data '
  {
    "idempotencyKey": "6ae62bf2-bd71-49ce-a599-165ffcc33680",
    "accountNumber": "12345678"
  }
  '

In either case, you should receive a response like below.

{
  "data": {
    "id": "25968c8f-5586-4784-8f03-7870b67e964a",
    "status": "pending",
    "description": "SILVERGATE BANK ****1234",
    "trackingRef": "CIR3HVW9JK",
    "fingerprint": "2f1e5767-e777-4499-84b1-fd1f3ad383f5",
    "createDate": "2022-06-28T13:02:50.097Z",
    "updateDate": "2022-06-28T13:02:50.097Z"
  }
}

3. Obtain the SEN Bank Account Deposit Details

Circle SEN deposits are only "push" transfers, so you have to initiate the transfer from your bank account.

📘

Instructions by currency

When gathering SEN bank account instructions you will need to specify the currency you intend to deposit. At this time, SEN supports both USD and EUR currency.

You can obtain the details required for initiating the SEN bank transfer by using the get SEN transfer instructions endpoint. From there you can populate the path parameter id (gathered from the previous step) and query parameter currency. If a currency is not provided USD account number be returned by default.

Alternatively, you can use the command below to make an API call to GET /v1/businessAccount/banks/sen/{id}/instructions yourself.

curl -H 'Accept: application/json' \
    -H "Authorization: Bearer ${YOUR_API_KEY}" \
    -X GET --url https://api-sandbox.circle.com/v1/businessAccount/banks/sen/${BANK_ACCOUNT_ID}/instructions
curl -H 'Accept: application/json' \
    -H "Authorization: Bearer ${YOUR_API_KEY}" \
    -X GET --url https://api-sandbox.circle.com/v1/businessAccount/banks/sen/${BANK_ACCOUNT_ID}/instructions?currency=EUR

In either case, you should receive a response like below.

{
  "data": {
    "trackingRef": "CIR3HVW9JK",
    "accountNumber": "11111111"
  }
}

In the production environment, the transfer details above will represent Circle's bank account details for incoming transfers. That information should be shared with the person initiating the SEN transfer. Once the funds reach Circle's banking infrastructure, we will attempt to reconcile that deposit and settle the funds on your account.

🚧

Transfer Tracking Reference

Note that a bank account created via Circle APIs has a tracking reference (trackingRef attribute) that is unique to that bank account. For deposits via SEN transfer, it is imperative that the person initiating the transfer include that value on the trackingRef field when prompted for it by their bank. Failure to indicate the tracking reference makes it impossible for Circle to reconcile the deposit - such transfers will be returned to the sender.

4. Send Deposit via SEN

Now that you have obtained SEN transfer details for the deposit, you just need to wait for the transfer to be initiated, and eventually the deposit to settle and be reconciled.

It is difficult to test flows involving push transfers, so we have created an endpoint for creating a mock SEN transfer. From there you can populate the trackingRef (from the previous step), accountNumber (from the previous step), amount.amount and amount.currency.

Alternatively, you can use the command below to make an API call to POST /v1/mocks/payments/sen yourself.

curl -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H "Authorization: Bearer ${YOUR_API_KEY}" \
    -X POST --url https://api-sandbox.circle.com/v1/mocks/payments/sen \
    --data '
  {
    "trackingRef": "${TRACKING_REF}",
    "accountNumber": "${ACCOUNT_NUMBER}",
    "amount": {
      "amount": "1000.00",
      "currency": "EUR"
    }
  }
  '

In either case, you should receive a response like below.

{
  "data":{
    "trackingRef":"CIR3HVW9JK",
    "amount":{
      "amount":"1000.00",
      "currency":"EUR"
    },
    "status":"pending"
  }
}

5. Check for the Existence of Deposit

Due to "push" nature of SEN transfers, you will have to monitor deposits into your account in order to detect the SEN transfer you are expecting. You can either poll for deposits using the get deposits endpoint at certain intervals, or use our notifications service to receive updates.

Eventually, you will observe a deposit object that matches your expectation, such as the one below.

{
  "data": [
    {
      "id": "b2930a66-53f1-4fdd-8ff4-e220517400c5",
      "sourceWalletId": "25968c8f-5586-4784-8f03-7870b67e964a",
      "destination": {
        "type": "wallet",
        "id": "123456789"
      },
      "amount": {
        "amount": "1000.00",
        "currency": "EUR"
      },
      "status": "complete",
      "createDate": "2022-06-28T13:09:00.695Z",
      "updateDate": "2022-06-28T13:12:59.265Z"
    }
  ]
}

You can detect a match by looking into the sourceWalletId attribute, as it should match the id of the bank account you created on step 2.

When the deposit is settled, the status will be equals to complete.

If the status is equal to failed then it means we could not settle that deposit. That typically happens due to a mismatch between the information provided during the creation of the bank account (step 2) and the information received from the sender bank.

🎉 You are all done!

6. Like what you see? Keep going!

You have just touched the tip of the iceberg of Circle APIs.

Check how to subscribe to notifications on changes in deposit status. Also make sure you check the rest of the documentation - a few starting points are suggested below.