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.
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.
- Get your sandbox key from 717 Capital. It starts with
717_test_. Keep it on your server. - Check it works:
curl https://nvsuwrmeqmpqvqmccsvn.supabase.co/functions/v1/partner-api/ping \ -H "Authorization: Bearer $KEY_717" - Create a test user and open the
verification_urlit 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"}' - Approve them instantly (sandbox only):
POST $BASE/sandbox/users/user_123/approve - 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 receivetransaction.updatedwebhooks.
Authentication
Send your API key as a bearer token on every request:
Authorization: Bearer 717_test_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Sandbox keys (717_test_) only work in the sandbox; production keys (717_live_) only work in production.
Environments
| Sandbox | Production | |
|---|---|---|
| Base URL | https://nvsuwrmeqmpqvqmccsvn.supabase.co/functions/v1/partner-api | Provided at go-live |
| Networks | Testnets (e.g. Polygon Amoy, Ethereum Sepolia, Solana Devnet) | Mainnets (Polygon, Ethereum, Base, Arbitrum, Optimism, Solana) |
| Stablecoins | USDC | USDC and USDT |
| Amounts | $0.01–$2.00 per transaction | No sandbox cap |
| Bank transfers | Simulated | Real ACH and wire |
| Identity verification | Test data accepted; approve with a sandbox call | Real 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}.
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"}'
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.
network | Sandbox (testnet) | Production | Wallet address | Assets |
|---|---|---|---|---|
polygon | Polygon Amoy | Polygon | 0x… | USDC, USDT* |
ethereum | Ethereum Sepolia | Ethereum | 0x… | USDC, USDT* |
base | Base Sepolia | Base | 0x… | USDC, USDT* |
arbitrum | Arbitrum Sepolia | Arbitrum One | 0x… | USDC, USDT* |
optimism | OP Sepolia | Optimism | 0x… | USDC, USDT* |
solana | Solana Devnet | Solana | base58 | USDC, 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.
Confirms your key works. Returns { ok, partner, environment }.
Networks and stablecoins available in this environment: { environment, default, data: [{ network, label, network_id, address_format, assets }] }.
| Field | Type | |
|---|---|---|
external_user_id | string | Required. Your ID for the user (max 120 chars). |
name | string | Required. The user's full legal name. |
type | string | individual (default) or business. |
return_url | string | Optional https URL to send the user back to after verification. |
Returns the user object: 201 when created, 200 if it already existed.
Current status, verification link, and deposit/withdrawal details.
| Field | Type | |
|---|---|---|
wallet_address | string | Required. The user's address on the chosen network (0x… for EVM networks, base58 for Solana). |
network | string | polygon (default), ethereum, base, arbitrum, optimism, solana. |
asset | string | USDC (default) or USDT (production only). |
| Field | Type | |
|---|---|---|
routing_number | string | Required. 9-digit ABA routing number. |
account_number | string | Required. 4–17 digits. |
account_type | string | checking (default) or savings. |
account_holder_name | string | Required. Should match the verified user. |
bank_name | string | Required. |
network | string | Network the user will send from. Default polygon. |
asset | string | USDC (default) or USDT (production only). |
address | object | Only if requested by a 409: { street1, city, region, postal_code, country }. |
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.
Approves the user's verification instantly.
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": { … } }
| Type | When | data |
|---|---|---|
user.status_changed | Verification status changed (e.g. approved) | The user object |
user.more_info_needed | Review needs something else from the user | User object + requirements |
user.info_received | The user supplied what was asked | User object |
transaction.updated | A deposit or withdrawal was created or changed status | user_id, external_user_id, transaction_id, direction, status, amount_in, currency_in, amount_out, currency_out, tx_hash, hold_reason, failure_reason |
test.ping | Sent 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": { … } }
| Status | code | Meaning |
|---|---|---|
| 400 | invalid_request | A field is missing or malformed. error names it. |
| 400 | asset_unavailable_in_sandbox | USDT requested in the sandbox. Test with USDC. |
| 401 | unauthorized | Missing or invalid key, or a test key used in production (or vice versa). |
| 404 | user_not_found / not_found | Unknown user or route. |
| 409 | user_not_approved | The user must finish verification first. |
| 409 | no_deposit_account | Sandbox deposit attempted before a deposit account exists. |
| 409 | conflict | Something else must happen first. Read error. |
| 5xx | upstream_error / internal_error | Temporary 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:
POST /users→ openverification_urland fill it in with test details (any clear photo works as the ID), or skip it withPOST /sandbox/users/{id}/approve.POST /users/{id}/deposit-accountwith a wallet you control (and yournetwork, if not Polygon).POST /sandbox/users/{id}/depositwith{"amount": 1}. You'll gettransaction.updated(processing → completed), and 1 test USDC arrives in the wallet on that network's testnet (Polygon Amoy for Polygon).POST /users/{id}/withdrawal-accountwith test bank details (e.g. routing021000021, account123456789).- From the wallet, send ≤ 2 test USDC on the testnet to
withdrawal.send_to. You'll gettransaction.updatedfor the withdrawal; the USD payout is simulated.
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:
- Test USDC: faucet.circle.com. Pick the testnet below.
- Gas: each testnet has a free faucet for its gas token (test POL, test ETH or devnet SOL). Search "[network] testnet faucet".
| Network | Testnet | Chain ID | Gas | Explorer |
|---|---|---|---|---|
| Polygon | Polygon Amoy | 80002 | POL (faucet) | amoy.polygonscan.com |
| Ethereum | Sepolia | 11155111 | ETH | sepolia.etherscan.io |
| Base | Base Sepolia | 84532 | ETH | sepolia.basescan.org |
| Arbitrum | Arbitrum Sepolia | 421614 | ETH | sepolia.arbiscan.io |
| Optimism | OP Sepolia | 11155420 | ETH | sepolia-optimism.etherscan.io |
| Solana | Devnet | n/a | SOL (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 name | Polygon Amoy Testnet |
| RPC URL | https://polygon-amoy.drpc.org |
| Chain ID | 80002 |
| Currency symbol | POL |
| Block explorer | https://amoy.polygonscan.com |
Then add test USDC as a custom token: contract 0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582, symbol USDC, 6 decimals.
Going live
- Complete a full sandbox round trip (onboard → deposit → withdraw) and handle every webhook type.
- 717 Capital completes your business onboarding and issues your
717_live_key and production base URL. - Switch your base URL and key, and register your production webhook endpoint.
- Use real (mainnet) wallet addresses. Your
networkvalues stay the same; production maps them to mainnets automatically. - Optionally enable USDT, now available.
- Remove calls to
/sandbox/*routes (they return 404 in production).