Sandbox

Partner API

Let your users move between US dollars and stablecoins (USDC and USDT) inside your product, on the network your platform uses. 717 Capital handles identity verification, dedicated bank accounts in each user's name, conversion, and settlement.

Overview

Every user goes through four stages. Your integration needs only a handful of API calls and one webhook endpoint.

01Create userYou send us your user's ID and name.
02Verify identityThe user completes a short 717-hosted verification.
03DepositThe user wires or ACHs USD to their own account; USDC lands in their wallet.
04WithdrawThe user sends USDC to their address; USD is paid to their bank.
Users always hold their own funds. Deposits are delivered straight to the user's self-custody wallet, and withdrawals start when the user sends USDC from that wallet. Your platform never takes custody.

Quickstart

In the examples below, $BASE is your base URL (https://nvsuwrmeqmpqvqmccsvn.supabase.co/functions/v1/partner-api) and $KEY_717 is your API key.

  1. Get your sandbox key from 717 Capital. It starts with 717_test_. Keep it on your server.
  2. Check it works:
    curl https://nvsuwrmeqmpqvqmccsvn.supabase.co/functions/v1/partner-api/ping \
      -H "Authorization: Bearer $KEY_717"
  3. Create a test user and open the verification_url it returns:
    curl -X POST $BASE/users \
      -H "Authorization: Bearer $KEY_717" -H "Content-Type: application/json" \
      -d '{"external_user_id":"user_123","name":"Jane Doe","return_url":"https://yourapp.com/wallet"}'
  4. Approve them instantly (sandbox only): POST $BASE/sandbox/users/user_123/approve
  5. Create a deposit account with a wallet address you control, then simulate a $1 deposit: POST $BASE/sandbox/users/user_123/deposit. Within seconds you'll receive transaction.updated webhooks.
The sandbox uses test networks, not real ones. Test USDC is delivered on each network's testnet, a free practice copy of the blockchain where tokens have no value. For Polygon that's Polygon Amoy (chain ID 80002). To see the test USDC arrive, your wallet must be switched to the testnet; it won't appear on regular Polygon. See Testnet tokens for wallet settings.

Authentication

Send your API key as a bearer token on every request:

Authorization: Bearer 717_test_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Server-side only. Never put your key in a mobile app, browser code, or a public repository. If a key is exposed, ask 717 Capital to rotate it; the old key stops working immediately.

Sandbox keys (717_test_) only work in the sandbox; production keys (717_live_) only work in production.

Environments

SandboxProduction
Base URLhttps://nvsuwrmeqmpqvqmccsvn.supabase.co/functions/v1/partner-apiProvided at go-live
NetworksTestnets (e.g. Polygon Amoy, Ethereum Sepolia, Solana Devnet)Mainnets (Polygon, Ethereum, Base, Arbitrum, Optimism, Solana)
StablecoinsUSDCUSDC and USDT
Amounts$0.01–$2.00 per transactionNo sandbox cap
Bank transfersSimulatedReal ACH and wire
Identity verificationTest data accepted; approve with a sandbox callReal review

Onboarding users

Call POST /users the first time a user taps Deposit or Withdraw. It's safe to call again: the same external_user_id always returns the same user.

Send the user to verification_url, in a new tab, an in-app browser, or a redirect. They'll provide their details, upload a photo ID, and accept the account agreements. It takes about five minutes on a phone. If you passed a return_url, they'll see a button back to your app when they finish.

Knowing when they're approved

You'll receive a user.status_changed webhook. When can_transact is true, enable deposits and withdrawals in your UI. You can also poll GET /users/{external_user_id}.

Each read of a not-yet-approved user returns a fresh verification_url, valid for 30 days. Users who leave partway can reopen any link and pick up where they left off.

Deposits (USD → USDC)

Once approved, call POST /users/{id}/deposit-account with the user's wallet address, and optionally the network and asset (defaults: polygon, USDC). The response's deposit.bank_details is a dedicated US bank account in the user's own name. Show it to them; every USD transfer they send there is converted to the stablecoin and delivered to their wallet automatically.

curl -X POST $BASE/users/user_123/deposit-account \
  -H "Authorization: Bearer $KEY_717" -H "Content-Type: application/json" \
  -d '{"wallet_address":"0x742d35Cc6634C0532925a3b8D404fA40b5398Ad2","network":"polygon","asset":"USDC"}'

Calling again with the same wallet, network and asset returns the same account. A user can have several deposit accounts (for example USDC on Polygon and USDT on Ethereum); all are listed in deposits. Deposits arrive by ACH (1–3 business days).

Withdrawals (USDC → USD)

Call POST /users/{id}/withdrawal-account with the user's bank details, and optionally the network and asset they'll send from. The response's withdrawal.send_to is an address on that network. When the user sends that stablecoin there from their wallet, it's converted and paid by ACH to their bank.

curl -X POST $BASE/users/user_123/withdrawal-account \
  -H "Authorization: Bearer $KEY_717" -H "Content-Type: application/json" \
  -d '{"routing_number":"021000021","account_number":"123456789","account_type":"checking",
       "account_holder_name":"Jane Doe","bank_name":"Chase","network":"polygon","asset":"USDC"}'
The bank account should be in the verified user's name. Only send the stablecoin shown (asset) on the network shown (network). Other tokens or networks can't be recovered.

Payouts need the user's residential address, which we take from their verification automatically. In rare cases the request returns 409; resend it with an address object (see endpoints).

Networks & stablecoins

Pass network and asset when creating deposit and withdrawal accounts. Use the plain network name; we map it to the right chain in each environment. If you leave them out, you get USDC on Polygon.

networkSandbox (testnet)ProductionWallet addressAssets
polygonPolygon AmoyPolygon0x…USDC, USDT*
ethereumEthereum SepoliaEthereum0x…USDC, USDT*
baseBase SepoliaBase0x…USDC, USDT*
arbitrumArbitrum SepoliaArbitrum One0x…USDC, USDT*
optimismOP SepoliaOptimism0x…USDC, USDT*
solanaSolana DevnetSolanabase58USDC, USDT*

* USDT works in production only for now. In the sandbox, requests with "asset":"USDT" return 400 asset_unavailable_in_sandbox, so build and test with USDC; switching to USDT later is just a different asset value.

GET /networks returns the live list for the environment you're calling, so your UI can stay in sync without hard-coding it.

Endpoints

All requests and responses are JSON. {id} is always your external_user_id.

GET/ping

Confirms your key works. Returns { ok, partner, environment }.

GET/networks

Networks and stablecoins available in this environment: { environment, default, data: [{ network, label, network_id, address_format, assets }] }.

POST/users
FieldType
external_user_idstringRequired. Your ID for the user (max 120 chars).
namestringRequired. The user's full legal name.
typestringindividual (default) or business.
return_urlstringOptional https URL to send the user back to after verification.

Returns the user object: 201 when created, 200 if it already existed.

GET/users/{id}

Current status, verification link, and deposit/withdrawal details.

POST/users/{id}/deposit-account
FieldType
wallet_addressstringRequired. The user's address on the chosen network (0x… for EVM networks, base58 for Solana).
networkstringpolygon (default), ethereum, base, arbitrum, optimism, solana.
assetstringUSDC (default) or USDT (production only).
POST/users/{id}/withdrawal-account
FieldType
routing_numberstringRequired. 9-digit ABA routing number.
account_numberstringRequired. 4–17 digits.
account_typestringchecking (default) or savings.
account_holder_namestringRequired. Should match the verified user.
bank_namestringRequired.
networkstringNetwork the user will send from. Default polygon.
assetstringUSDC (default) or USDT (production only).
addressobjectOnly if requested by a 409: { street1, city, region, postal_code, country }.
GET/users/{id}/transactions

The user's conversions, newest first (up to 100). Each has transaction_id, direction (deposit/withdrawal), status, amount_in, currency_in, amount_out, currency_out, tx_hash, hold_reason, and timestamps.

POST/sandbox/users/{id}/approveSandbox

Approves the user's verification instantly.

POST/sandbox/users/{id}/depositSandbox

Simulates a USD deposit into the user's deposit account. Body: { "amount": 1.00, "rail": "ach" | "wire", "network"?, "asset"? }, amount up to 2.00. Without network/asset, the user's most recent deposit account is used. Returns 202; conversion events follow by webhook.

The user object

{
  "id": "8a1f…",
  "external_user_id": "user_123",
  "name": "Jane Doe",
  "status": "approved",            // not_started | pending | partner_review | approved | rejected | frozen
  "can_transact": true,
  "verification_url": null,          // a link while not yet approved
  "return_url": "https://yourapp.com/wallet",
  "deposit": {
    "delivers_to_wallet": "0x742d…8Ad2",
    "network": "polygon", "network_id": "polygon-amoy", "asset": "USDC", "rail": "ach",
    "bank_details": {
      "bank_name": "…", "account_holder_name": "Jane Doe",
      "aba_routing_number": "…", "account_number": "…", "account_type": "checking"
    }
  },
  "withdrawal": {
    "send_to": "0x123…", "network": "polygon", "network_id": "polygon-amoy", "asset": "USDC",
    "pays_out_to_bank_ending": "6789"
  },
  "deposits": [ … ],                 // every deposit account (one per wallet/network/asset)
  "withdrawals": [ … ],              // every withdrawal account
  "environment": "sandbox"
}

deposit and withdrawal are the most recently created accounts; deposits and withdrawals list them all. send_usdc_to is also returned as an alias of send_to.

Webhooks

Give 717 Capital an HTTPS endpoint. We'll send you a signing secret (whsec_…). Every update is a POST:

{ "id": "5b7c…", "type": "transaction.updated", "created": 1794700000, "data": { … } }
TypeWhendata
user.status_changedVerification status changed (e.g. approved)The user object
user.more_info_neededReview needs something else from the userUser object + requirements
user.info_receivedThe user supplied what was askedUser object
transaction.updatedA deposit or withdrawal was created or changed statususer_id, external_user_id, transaction_id, direction, status, amount_in, currency_in, amount_out, currency_out, tx_hash, hold_reason, failure_reason
test.pingSent when 717 tests your endpoint{ message }

Verifying signatures

Each request carries X-717-Timestamp (Unix seconds), X-717-Signature (hex HMAC-SHA256 of "{timestamp}.{raw body}" with your secret), and X-717-Event-ID. Verify against the raw request body before parsing it, reject timestamps older than 5 minutes, and deduplicate on X-717-Event-ID.

const crypto = require("crypto");

// app.post("/webhooks/717", express.raw({ type: "application/json" }), handler)
function verify717(rawBody, headers, secret) {
  const ts = headers["x-717-timestamp"], sig = headers["x-717-signature"] || "";
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  return sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}
import hmac, hashlib, time

def verify_717(raw_body: bytes, headers, secret: str) -> bool:
    ts = headers.get("X-717-Timestamp", "")
    sig = headers.get("X-717-Signature", "")
    if not ts or abs(time.time() - int(ts)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, expected)

Respond with any 2xx within 10 seconds. Events can arrive out of order; use updated_at or re-read the user to get the latest state.

Errors

Errors return a non-2xx status and a body like:

{ "error": "This user isn't approved yet (status: pending)…", "code": "user_not_approved", "details": { … } }
StatuscodeMeaning
400invalid_requestA field is missing or malformed. error names it.
400asset_unavailable_in_sandboxUSDT requested in the sandbox. Test with USDC.
401unauthorizedMissing or invalid key, or a test key used in production (or vice versa).
404user_not_found / not_foundUnknown user or route.
409user_not_approvedThe user must finish verification first.
409no_deposit_accountSandbox deposit attempted before a deposit account exists.
409conflictSomething else must happen first. Read error.
5xxupstream_error / internal_errorTemporary problem. Retry with backoff; requests are safe to repeat.

API spec (OpenAPI)

The complete API is also available as a machine-readable OpenAPI file. You don't need it to integrate, but developers can import it into tools like Postman or Insomnia to get every request ready to run, or use it to generate client code.

Sandbox testing

A complete round trip, end to end:

  1. POST /users → open verification_url and fill it in with test details (any clear photo works as the ID), or skip it with POST /sandbox/users/{id}/approve.
  2. POST /users/{id}/deposit-account with a wallet you control (and your network, if not Polygon).
  3. POST /sandbox/users/{id}/deposit with {"amount": 1}. You'll get transaction.updated (processing → completed), and 1 test USDC arrives in the wallet on that network's testnet (Polygon Amoy for Polygon).
  4. POST /users/{id}/withdrawal-account with test bank details (e.g. routing 021000021, account 123456789).
  5. From the wallet, send ≤ 2 test USDC on the testnet to withdrawal.send_to. You'll get transaction.updated for the withdrawal; the USD payout is simulated.
Sandbox transactions over $2.00 fail. Use small amounts in your fixtures.

Testnet tokens

Sandbox deposits deliver test USDC to the testnet of the network you chose. To test withdrawals, the wallet needs a little test USDC plus the testnet's gas token. Both are free:

NetworkTestnetChain IDGasExplorer
PolygonPolygon Amoy80002POL (faucet)amoy.polygonscan.com
EthereumSepolia11155111ETHsepolia.etherscan.io
BaseBase Sepolia84532ETHsepolia.basescan.org
ArbitrumArbitrum Sepolia421614ETHsepolia.arbiscan.io
OptimismOP Sepolia11155420ETHsepolia-optimism.etherscan.io
SolanaDevnetn/aSOL (faucet)explorer (devnet)

Seeing test USDC in your wallet (Polygon Amoy example)

Most wallets hide testnets by default. Either turn on "show test networks" in the wallet's settings, or add the network manually:

Network namePolygon Amoy Testnet
RPC URLhttps://polygon-amoy.drpc.org
Chain ID80002
Currency symbolPOL
Block explorerhttps://amoy.polygonscan.com

Then add test USDC as a custom token: contract 0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582, symbol USDC, 6 decimals.

Going live

  1. Complete a full sandbox round trip (onboard → deposit → withdraw) and handle every webhook type.
  2. 717 Capital completes your business onboarding and issues your 717_live_ key and production base URL.
  3. Switch your base URL and key, and register your production webhook endpoint.
  4. Use real (mainnet) wallet addresses. Your network values stay the same; production maps them to mainnets automatically.
  5. Optionally enable USDT, now available.
  6. Remove calls to /sandbox/* routes (they return 404 in production).